Skip to content

docs: post-android-skills hygiene — layering rule, stale facts, §5 CameraX collapse, align docs to code (#143) - #144

Open
stozo04 wants to merge 1 commit into
mainfrom
docs/post-android-skills-hygiene
Open

docs: post-android-skills hygiene — layering rule, stale facts, §5 CameraX collapse, align docs to code (#143)#144
stozo04 wants to merge 1 commit into
mainfrom
docs/post-android-skills-hygiene

Conversation

@stozo04

@stozo04 stozo04 commented Aug 22, 2026 •
edited by cursor Bot
Loading

Copy link
Copy Markdown
Owner

Description

Documentation audit + cleanup: the post-android-skills hygiene pass specced in #143 (layering rule, stale facts, §5 CameraX collapse, e2e retention), the PR #141 follow-up (fresh-clone behaviour of the android-skills plugin, with the explicit --scope project), and an align-docs-to-code pass over docs/ — every version number, symbol, file path, status header and feature list checked against the current tree (three read-only sub-agent sweeps + hand verification). Mechanical corrections only; nothing restructured; proposals that need an owner decision are listed, not applied.

Docs-only. git diff --name-only main..HEAD -- app/ → 0 files. No Kotlin, Gradle, manifest, or resource touched.

Related Issue

Closes #143. Follow-up to #141 (review recommendation on Lesson 007 / fresh-clone accuracy).

Type of Change

  • 📝 Documentation: Changes or additions to documentation/guides

What this PR does

#143 tasks

# Task Result
1 Stale facts in ANDROID_STANDARDS.md §8 re-verified against the live Play page on 2026-08-22 — Target API level requirements (page stamped last updated 2026-08-14): "new apps and app updates must target Android 16 (API level 36) or higher" from August 31, 2026, extension to November 1, 2026; existing apps ≥ API 35. The doc now states that, dated, and says OpenLoop is already at the floor. Lines 7/192/194 updated. Line 200 "zero network, zero tracking" rewritten to the truth (on-device media; Firebase Crashlytics + Analytics declared in play-store/data-safety.md). Also fixed: compileSdk/targetSdk 36 → targetSdk 36, compileSdk 37 (lines 196, 251 — app/build.gradle.kts:25,35), and §11's dead PreviewScreen references → the real BackHandler sites (CameraScreen, GalleryScreen, TrimScreen, ProcessingScreen — grepped) and inset consumers (camera, gallery, trim, editor).
2 Collapse §5 CameraX Generic rules → pointer to /android-skills:camerax + the Google links (kept); CLAUDE.md precedence caveat (MlKitAnalyzer vs manual FaceTracker); repo-only rules as a lesson-linked list: 012, 022, 025, 031, 036 (025 added — it is a PreviewView rule no skill knows). §5: 18 → 16 lines, all ours.
3 Layering rule One paragraph in the ANDROID_STANDARDS.md header; matching sentence in the ANDROID_STANDARDS.md row of docs/README.md's folder map.
4 Loose root files FIREBASE.md gets a folder-map row and stays put (workflow path); the "do not create" sentence now names the six root files + the PRD-<feature>.md set. elvis-asset-processing.md git mv'd to docs/guides/ (history follows) + row in guides/README.md; zero inbound links existed (re-grepped), so nothing orphaned. Alternative the owner may prefer: fold it into PRD-camera-lenses.md as an appendix — say so and I'll re-home it.
5 docs/e2e/ retention Applied the procedure as written → zero deletions (table below). Before/after size: 13,850,236 bytes (13.21 MiB) → unchanged.
6 pr-reviewer CameraX checklist Proposed, not applied (below).

PR #141 recommendation (Lesson 007 accuracy)

docs/guides/android-skills.md → "Scope: this project only" gained a "Fresh clone / new machine — the skills do not load by themselves" paragraph, citing Configure team marketplaces (read 2026-08-22, verbatim: "As of Claude Code v2.1.195 … A plugin that only the project's .claude/settings.json enables, and that comes from an external source such as a GitHub repository … doesn't load until the team member installs it. Until then, Claude Code reports the plugin as not installed and shows the claude plugin install command to run.") — with the explicit --scope project and why omitting it re-creates the user-scope drift. PRD-android-skills.md Decision note got the matching one-liner ("self-contained on a fresh clone" = the marketplace name resolves, not that the skills load).

Task 5 — e2e retention, applied step by step

git ls-files docs/e2e = 29 files. Step 2 (anything cited by a PRD / guide / README stays) — grepped every filename across all *.md/*.html/*.yml:

Area Files Cited by a live doc? Procedure verdict
camera-lenses (08-08/09) proof.md + 5 .webp (248 KB) yes — PRD-camera-lenses.md stays
speed-curves (08-17/18) 6 .png (1.79 MB) yes — PRD-speed-curves.md stays
twisted-tongue (08-16) 1 .png (1.92 MB) yes — twisted-tounge/GUIDE.md stays
in-app-review (08-10) proof.md + 1 .png (1.31 MB) no (PR #124 body only) only proof in its area → newest → keep
localization (08-16) proof.md + 3 .webp (156 KB) no (PR #132) only one → keep
launcher-icon (08-17) 1 .png (109 KB) no (PR #133) only one → keep
lens-removal (08-17) proof.md + 1 .png (1.69 MB) no (PR #134) only one → keep
photo-booth (08-20) 7 images (6.07 MB) no (PR #138 body embeds them by repo path) only one → keep
upgrade-reverse-save (08-20) 1 .png (559 KB) no (PR #138) only one → keep

Step 3 ("group by feature area, keep the newest per area, delete the rest") deletes nothing: every unreferenced area has exactly one proof set — the 2026-08-10 pass (8d6093b) already pruned the older ones.

The owner's option (not done — deletion needs an explicit "proceed"): commit 8d6093b read the rule more aggressively — every proof for an already-merged PR goes unless a live doc cites it (it deleted the only capture-zoom / issue-95 / photo-capture / in-app-updates proofs). Applying that reading here would delete 15 files, 9,890,168 bytes (9.43 MiB), leaving 3.78 MiB:

Say "proceed" and it's a one-commit follow-up. (One-line aside: the 1.3–1.9 MB PNGs would shrink ~15× as WebP q90 — measured 1,645 KB → 113 KB — but that's lossy and renames files merged PR bodies embed, so not done.)

Task 6 — pr-reviewer §5 CameraX checklist (owner decision)

.claude/skills/pr-reviewer/references/google-standards-checklist.md §5 (lines 72–85) is the same generic paraphrase §5 of ANDROID_STANDARDS.md just shed.

  • (a) Collapse — replace the five generic items with: "invoke android-skills:camerax for the CameraX review; then apply the repo rules — single camera-bound call site (012), release CameraX when PreviewView leaves composition (022), parent-intercept pinch (025), CameraEffect attached once / switched by uniform (031), getBitmap() stale after stop (036)." Keeps the review rubric aligned with the standards doc; the skill body is maintained by Google.
  • (b) Leave it — the checklist is the skill's own review rubric; a reviewer running without the plugin (cloud runner) still gets a usable CameraX list.

Recommendation: (a), with one line retained for the no-plugin case ("if android-skills:camerax is unavailable, fall back to the Google links"). Not changed in this PR.

Edits beyond #143's letter — per the "align docs to code" instruction

#143's acceptance list says "Nothing in PRD-*.md, lessons_learned/, guides/ … or play-store/ was modified." The owner's instruction for this PR was broader ("ensure documentation matches and aligns to our current code") and explicitly asked for the #141 change inside guides/. So that box is deliberately not ticked. Rule applied: mechanical falsehoods only (dead paths/symbols/line cites, wrong versions asserted as current, status headers contradicted by shipped code, one-liners contradicted by their own file) — no restructuring, no rewritten design text. Every edit is a one-line git diff hunk:

  • CLAUDE.md:100 — compileSdk/targetSdk 36 → targetSdk 36 / compileSdk 37 (it contradicted its own line 98).
  • PRD-mission-control.md — status banner at the top: §1–§5/§7/§9 describe the 2026-05 build (PreviewScreen, LoopingPreview, 1.5 s bursts, phases 3–5 "planned"); current architecture = CLAUDE.md snapshot + feature PRDs; still-authoritative = tokens, data layout, decision log. "Zero network requirements" → the Firebase truth. Nothing else in it touched — see Proposal 1.
  • TEST_COVERAGE.md — 6 renamed ViewModel test names corrected to the live ones (startBurstCapture starts recording and auto-caps at 30 seconds, finalize success auto-routes to Trim …, commitPendingDeletion …, etc.); six dead page0_/page1_/page2_ onboarding rows → the two real OnboardingScreenTest tests; the four PermissionExplanationScreenTest rows re-headed under their own class; the false "advanceTimeBy(1500)" sentence; "Gallery, Camera, Preview screens untested" gap row removed (all have suites — listed under Closed gaps (screen UI)); accessibility gap narrowed to contrast; AppUpdateFlowRobolectricTest + InAppReviewRobolectricTest added to the Robolectric table; compact class-name inventories for the ~43 suites the doc omitted.
  • PRD-camera-lenses.md — LensEffect → LensSurfaceProcessor; three dead CameraScreen.kt:<line> cites → file only; contentDescription = "Lenses" → camera_drawer_open ("Lenses and Photo Booth"); "No category tab row in v1" marked superseded by the drawer's Photo Booth | Lenses tabs (photo-booth D2).
  • PRD-photo-booth.md — boothSaveInProgress (never existed) → the shared photoSaveInProgress; "Booth button (provisional placement)" struck per its own D2.
  • PRD-photo-capture.md — Status: Awaiting sign-off → Shipped (feat(camera): photo capture mode (v1.0.37) #120 → feat(camera): photo capture mode (v1.0.37) — merge camera-lenses into main #123, v1.0.37); one empty (#) link → plain text.
  • PRD-speed-curves.md — draft API names sample/sliceFor → shipped maxSpeed() / sampleClip(…); one never-committed image link (e2e/2026-08-17-speed-curve-drag.png, no git history at all) removed.
  • PRD-capture-zoom.md — dead CameraManager.kt:58 cite → file only.
  • PRD-aso-discoverability.md — main 1.0.37 → 1.0.47 (dated); "README says Zero network calls… verified" → said, fixed; "docs/index.html is 11 lines" pre-feat(review)+docs(aso): in-app review gate, landing page, and listing reconciliation #124 paragraph prefixed with a shipped note; "Three lenses ship" → seven (Big Mouth/Bug Eyes removed in Remove Big Mouth and Bug Eyes (and the warp engine they were the only users of) #134); §5.3 tasks 1–6 marked ✅ with evidence; "In-App Review would be a fourth" → is.
  • lessons_learned/ (7 files, one hunk each) — PermissionDeniedScreen → PermissionExplanationScreen (006); a dated-hand-off note on 012's slice-02 section (names PreviewScreen/LoopingPreview/MAX_RECORDING_MS, all gone); 014's grep check re-scoped to OpenLoopNavHost (the bare grep now hits the permissions when); 015's PreviewScreen.kt example → TrimScreen.kt; 030 updateTrimWindow → updateTrim; 032 dead test name → sticker_offsetOrbitsWithTheHead_keepingItsDistance; 034 broken [[016-…]] wikilink slug. (Sub-agent also verified all 36 index links, Origin columns, and every other cited symbol — live.)
  • play-store/README.md — data-safety row said "(no data collected/shared)" while its own checklist says the opposite → fixed; permissions line now lists the three FOREGROUND_SERVICE* entries (manifest lines 31–33) and legacy WRITE_EXTERNAL_STORAGE ≤ 28; dead pointer to a non-existent docs/local/play-store-beginner-guide.md removed (also from docs/README.md).
  • play-store/release-signing-and-aab.md — "versionCode currently 1 / versionName 1.0.0" (it is 47 / 1.0.47) → "read app/build.gradle.kts"; "CAMERA only" → the real permission list.
  • guides/reverse-video-research.md — two dead file references (HEY_CLAUDE_ITS_ME.md, the deleted slice docs) → plain text + a dated note. The Media3 1.10.x content is a dated COMPLETED record and was left alone.
  • docs/index.html — "Broccoli, Shades and Elvis" → the seven shipped lenses (matches Lens.kt and the README).
  • cspell.json — "language": "en,en-GB" (the docs are written in British English — one line instead of ~15 spellings) + 86 real terms/proper nouns the files surfaced.

Sub-agent sweeps found clean: all guides/ (localization, oem-regression-testing, robolectric-testing-explained, samsung-rtl-steps — every script/test/symbol verified), FIREBASE.md, play-store/{content-rating,data-safety}.md.

Proposals needing an owner decision (not done)

  1. PRD-mission-control.md realignment. It is the doc CLAUDE.md calls "authoritative architecture" and it describes May. Options: (a) rewrite §1–§5/§7/§9 against the current code (state machine from OpenLoopUiState.kt, components from the package map, test architecture from TEST_COVERAGE.md) — a PRD-sized change that needs sign-off; (b) demote it to "decision log + design tokens + data layout" and let CLAUDE.md + feature PRDs be the architecture — delete §4/§5/§7/§9 (~250 lines). Recommendation: (b) — less to keep true. The banner makes either safe in the meantime.
  2. Privacy policy (play-store/privacy-policy.md + docs/privacy-policy.html, identical content) is materially inaccurate — not changed because it is the Play-facing legal text with an effective date: (i) "Files OpenLoop stores … private, app-specific storage (not visible to other apps) … Uninstalling the app removes all of them" — false since photo/booth: work/MediaStoreVideoPublisher.kt publishes every finished render to public MediaStore (Movies/OpenLoop, Pictures/OpenLoop), visible to gallery apps and surviving uninstall; (ii) "Camera — to record video" — photo mode ships; (iii) the permissions list omits WRITE_EXTERNAL_STORAGE (≤ 28) and the three FOREGROUND_SERVICE* entries. Proposed replacement text (needs both files + a new effective date):
    • Files OpenLoop stores → "OpenLoop keeps your raw clips and work-in-progress in the app's private storage (not visible to other apps). Finished loops and photos you save are also written to your device's media library (Movies/OpenLoop, Pictures/OpenLoop) so your Gallery/Photos app can show them — those copies are visible to other apps you have given media access, and they stay on your device if you uninstall OpenLoop (delete them from your Gallery app). Everything in the app's private storage is removed on uninstall."
    • Camera → "to record video and take photos in the app's viewfinder."
    • Permissions → add "Foreground service (FOREGROUND_SERVICE, …_MEDIA_PROCESSING, …_DATA_SYNC) — lets a loop finish rendering if you switch apps; shown by Android as a system indicator, not a notification" and "Storage (WRITE_EXTERNAL_STORAGE, Android 9 and below only) — to save finished loops to your media library".
  3. play-store/store-listing.md:75 full-description copy names 3 of 7 lenses — Console text, your call.
  4. functions/package.json:3 still describes the Cloud Function as "DRAFT" while PRD-crashlytics-autotriage.md/FIREBASE.md say shipped — one-word code-side fix, out of scope for a docs PR.

Gates

  • npx markdownlint-cli2 <25 changed .md> → 0 issues (after --fix on blank-lines/list-marker rules, text tags on bare fences per Lesson 010, one table cell, one empty link).
  • npx cspell --no-progress <changed .md> → 0 issues (en,en-GB + dictionary additions).
  • npx markdown-link-check --config .markdown-link-check.json on every changed file → 0 dead links (one pre-existing dead image link in PRD-speed-curves.md fixed).
  • doc-layout.yml: no .md added outside docs/ (git diff --diff-filter=A → none; the Elvis move is a rename inside docs/).
  • Gradle build / tests / lint / emulator run: not run — docs-only PR, zero files under app/ changed (git diff --name-only -- app/ → empty), same as docs: prune generic guides, fix 6 rot defects, tier the lessons read order #109 and docs: refresh the CLAUDE.md source map (it was missing five packages) #119. Android Studio Engine 2 inspections: not run (headless is vacuous on this machine — STATIC_ANALYSIS.md Tier 2 gotcha).
  • Core-lessons read: 007/009/010 read in full (the ones a markdown-only diff can violate); 008/011–036 were audited symbol-by-symbol by a sub-agent rather than read in main context — disclosed per the session mandate.

Numbers

  • ANDROID_STANDARDS.md: 281 → 281 lines (§5 18 → 16; header +2, §8 re-written at equal length).
  • docs/e2e/: 13.21 MiB → 13.21 MiB (zero deletions under the procedure; 9.43 MiB deletable under the 8d6093b reading — awaiting "proceed").
  • 27 files, +295 / −130.

#143 acceptance criteria

  • Tasks 1–5 done; Task 6 proposed (not applied)
  • cspell 0 · [x] markdownlint 0 · [x] markdown-link-check 0 · [x] doc-layout passes
  • Every deleted docs/e2e/ asset listed with proof — none deleted; the inventory + proof is above
  • §8 cites the live URL and the date checked (2026-08-22; page last updated 2026-08-14)
  • Before/after line counts + e2e size above
  • "Nothing in PRD / lessons / guides / play-store modified" — intentionally not met; see "Edits beyond docs: post-android-skills hygiene — layering rule, stale facts, §5 CameraX collapse, e2e retention #143's letter" (all mechanical, all listed, all one-hunk)

How Has This Been Tested?

  • Manual Verification: every factual edit was checked against the tree before writing it — grep/Glob on the cited symbols, gradle/libs.versions.toml + app/build.gradle.kts for versions, BackHandler/inset/GridCells call sites for §11, git log for the e2e assets, the live developer.android.com and code.claude.com pages for the two external claims (dates in the text). Three read-only sub-agents swept PRDs / guides+play-store / lessons+test-inventory; their clean verdicts are listed above.
  • Automated Tests: Tier 3 Markdown gates on all 25 changed .md files (27 files in the diff incl. cspell.json + index.html) — markdownlint-cli2 0, cspell 0, markdown-link-check 0; doc-layout.yml conditions checked locally. No Gradle task run — docs-only, zero app/ files (precedent docs: prune generic guides, fix 6 rot defects, tier the lessons read order #109 / docs: refresh the CLAUDE.md source map (it was missing five packages) #119).

Checklist

  • 🧪 My changes have been verified locally and work as expected (Tier 3 gates green; every claim grepped).
  • 🔍 I have performed a self-review of my own code (full git diff read; --fix hunks are whitespace / fence tags / one list marker only).
  • ✍️ I have commented my code, particularly in hard-to-understand areas (n/a — docs; dated notes added where history is kept on purpose).
  • 📖 My changes generate no new compile warnings or errors (no code changed).
  • 🧹 The git branch is clean (single commit off main); the two pre-existing .claude/worktrees/ checkouts on other branches were left untouched — not this PR's to prune.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JVeJv8UjqrwGSzHMZHbVu9

Note

Low Risk
Documentation and dictionary only; no app, Gradle, or manifest changes. Remaining owner decisions (mission-control rewrite, privacy-policy legal text) are explicitly not applied.

Overview
Docs-only pass that makes agent/Play docs match the tree after android-skills and shipped features. No Kotlin, Gradle, or resources.

Standards layering. ANDROID_STANDARDS.md now states that generic Google guidance lives in android/skills; §5 CameraX collapses to a skill pointer plus repo lessons (012, 022, 025, 031, 036). §8 is re-verified (2026-08-22): Play’s API-36 floor from 2026-08-31, targetSdk 36 / compileSdk 37, and Firebase telemetry instead of “zero network.” §11 BackHandler/inset lists match current screens.

Fresh-clone plugin truth. guides/android-skills.md and PRD-android-skills.md document that marketplace enablement does not load skills until claude plugin install … --scope project.

Align-to-code. Dead symbols, line cites, test names, lens counts (seven), version 1.0.47, ASO task checkmarks, and Play permission/data-safety wording are corrected across PRDs, lessons, TEST_COVERAGE.md, landing page, and play-store pack. PRD-mission-control.md gets a “May 2026 snapshot” banner rather than a rewrite. cspell adds en-GB plus dictionary terms.

Owner follow-ups (mission-control realignment, privacy-policy legal text, pr-reviewer CameraX checklist, aggressive e2e prune) are listed, not done.

Reviewed by Cursor Bugbot for commit 5cf2129. Bugbot is set up for automated code reviews on this repo. Configure here.

@stozo04 @claude
docs: post-android-skills hygiene — layering rule, stale facts, §5 Ca…
5cf2129 
…meraX collapse, align docs to code (#143)

Closes #143 and lands the PR #141 follow-up (fresh-clone behaviour of the
android-skills plugin: the marketplace name resolves, the skills do not load
until `claude plugin install android-skills@android-skills --scope project`).

ANDROID_STANDARDS.md: layering rule in the header; §5 CameraX collapsed to a
pointer at /android-skills:camerax + the repo-only rules (lessons 012/022/025/
031/036); §8 re-verified against the live Play page 2026-08-22 (API 36 floor
from 2026-08-31, extension to 2026-11-01); "zero network, zero tracking" →
the Firebase truth; compileSdk 37; dead PreviewScreen refs → real BackHandler
sites. docs/README.md: FIREBASE.md row, six root files, layering sentence,
full PRD list. elvis-asset-processing.md → docs/guides/ (+ index row).

docs/e2e retention applied per #143's procedure → zero deletions (every
unreferenced area has exactly one proof); the 8d6093b-style broader prune
(9.43 MiB) is proposed in the PR, not done.

Align-to-code pass (mechanical only, one hunk each): CLAUDE.md compileSdk;
PRD-mission-control status banner; TEST_COVERAGE renamed/dead test names and
closed gaps; dead symbol/line cites in PRD-camera-lenses/photo-booth/
photo-capture/speed-curves/capture-zoom/aso; 7 lesson checklists; play-store
README + release-signing facts; reverse-video-research dead file refs;
index.html lens list; cspell en-GB + dictionary.

Tier 3: markdownlint 0 · cspell 0 · markdown-link-check 0 on all changed .md.
Docs-only — zero files under app/ changed; Gradle gate not run (as #109/#119).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JVeJv8UjqrwGSzHMZHbVu9
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

docs: post-android-skills hygiene — layering rule, stale facts, §5 CameraX collapse, e2e retention

1 participant

@stozo04