Skip to content

moonlight-lupin/agent-skills / plugins/dev-pipeline/skills/review-lessons

review-lessons

Verified

Library of lessons from past build-review loops — not a stage. Use when a review or fix round hits a specific case: a reviewer BLOCKING that contradicts the brief, a test that passes but checks nothing, a feature dead in production, SQLite/WAL migrations, MCP tool surfaces, REST API authz, app ↔ external-source sync, Android/APK verification, fill-template extraction, CLI/git mechanics, reviewer outages. Load the one file the case needs; never load the whole library.

FileKindSize
SKILL.mdexecutableskill md5.5 KB
references/architecture-refactor-test-updates.mdexecutablescript2.9 KB
references/beta-gate-release-hardening.mdexecutablescript3.3 KB
references/ci-and-repo-hygiene.mdexecutablescript3.7 KB
references/confirm-loop-lessons.mdexecutablescript24.2 KB
references/cross-model-parallel-review.mdexecutablescript4.8 KB
references/data-integrity-principles.mdexecutablescript7.3 KB
references/delegate-skills-adaptation.mdexecutablescript2.1 KB
references/evidence-pairs.mdexecutablescript2.5 KB
references/extraction-from-filled-docs.mdexecutablescript6.1 KB
references/field-briefing-integration.mdexecutablescript5.2 KB
references/full-module-replacement-scoping.mdexecutablescript6.3 KB
references/generated-frontmatter-and-reviewer-outages.mdexecutablescript3.0 KB
references/loop-pitfalls.mdexecutablescript27.9 KB
references/mcp-category-tool-implementation.mdexecutablescript5.3 KB
references/mcp-design-review-patterns.mdexecutablescript5.7 KB
references/minified-bundle-selector-research.mdexecutablescript4.4 KB
references/mobile-app-verification.mdexecutablescript4.8 KB
references/multi-batch-sequencing.mdexecutablescript5.7 KB
references/parallel-dual-review.mdexecutablescript10.8 KB
references/pitfalls-dispatch-semantics.mdexecutablescript6.3 KB
references/pitfalls-fix-round-verification.mdexecutablescript6.6 KB
references/planning-with-files-adaptation.mdexecutablescript2.6 KB
references/plugin-gates-and-fix-rounds.mdexecutablescript8.2 KB
references/production-reachability-review.mdexecutablescript5.0 KB
references/reconciliation-review-findings.mdexecutablescript3.1 KB
references/rest-api-review-checklist.mdexecutablescript13.0 KB
references/review-findings-adjudication.mdexecutablescript34.4 KB
references/scope-test-in-process-execution.mdexecutablescript4.2 KB
references/security-property-tests.mdexecutablescript14.2 KB
references/sqlite-migration-pitfalls.mdexecutablescript4.1 KB
references/sqlite-wal-review-findings.mdexecutablescript5.0 KB
references/sync-pipeline-review-patterns.mdexecutablescript13.2 KB
references/tool-mechanics-pitfalls.mdexecutablescript44.1 KB
references/upgrade-path-test-pattern.mdexecutablescript3.0 KB

references/mobile-app-verification.md

View on GitHub
# Mobile/APK Artifact Verification & Android WebView Networking (session bank, 2026-08-31)

Condensed from hermes-desktop-android Dispatch 6→6i (Capacitor Android wrapper for an Electron renderer). Class-level: verifying BUILT mobile artifacts and Android WebView network-layer debugging.

## Verify the BUILT artifact, never the source tree
A green `gradlew assembleDebug` + passing tests prove the SOURCES are good. The deliverable is the APK. Before shipping:
1. `aapt dump badging app.apk | head -1` → confirm `versionName` (must be the stamped version, see below).
2. `unzip -p app.apk assets/capacitor.config.json` → confirm the runtime config actually baked (androidScheme etc.). Generated `android/app/build/intermediates/**` can be STALE even when outputs/ APK is fresh — assert the packaged copy, not intermediates.
3. JS bundle: `unzip -p app.apk assets/public/bridge.js | grep -c <new-symbol>` — proves the injected/native-bridge changes shipped.
4. Native code may live in ANY classesN.dex (Capacitor puts app classes in classes4.dex, not classes.dex). `unzip -p app.apk classes4.dex | strings | grep -c <NewClassName>` and grep for new native string literals. Checking only classes.dex produced a false 'stale build' scare AND a wrong public claim — the false alarm was corrected in front of the user. Extract every dex before declaring code missing.
5. Run both test surfaces: JS suite (vitest) AND `JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 ./gradlew :app:testDebugUnitTest`. Passing JVM tests do NOT prove the APK contains the classes.

## Version stamping (every APK, non-negotiable)
Two builds with the same versionName are indistinguishable on-device — burned a whole debug cycle (user ran old build; symptom matched the old bug; no way to tell). Pattern: repo-level `VERSION` file; installer script seds `versionName "..."` into the GENERATED build.gradle (the android/ tree is in .gitignore, so the stamp must be re-applied every sync). Bump VERSION, run installer, build, verify via aapt before delivery.

## Android WebView networking stack (each layer blocks separately)
| Layer | Guard | Fix |
|---|---|---|
| OS network | targetSdk 28+ cleartext | `android:usesCleartextTraffic="true"` in generated manifest |
| https page → http fetch | Chromium mixed content | Capacitor `android.allowMixedContent: true` |
| https page → ws:// | Separate WebSocket mixed-content rule — allowMixedContent does NOT lift it | Set `server.androidScheme: 'http'` (http://localhost is still a Chromium secure context: clipboard/crypto/SW unaffected; wss:// from http page is allowed) |
| Server side | CORS | Gateway must allow the WebView origin (`https?://(localhost|127.0.0.1)(:\d+)?$` regex) |
Debug sequence for 'Failed to fetch' in a Capacitor app against an http LAN gateway: check ALL four rows; symptoms are identical, layer differs. A fix at layer N does not fix layer N+1.

## Backgrounded-JavaScript class of bug (PKCE/login handoff)
When a WebView app hands off to a browser (Custom Tab) mid-flow: Android freezes renderer JS the moment the tab is foregrounded. Anything living in JS-promise state (pending waits, token exchange, tab auto-close) silently dies; activity recreation kills in-memory state entirely. Fix pattern: persist the handshake state to durable storage BEFORE opening the browser; persist the callback natively (Java) BEFORE serving the response page; complete the exchange on resume/boot from persisted state; keep the awake-JS path as a race-winner that clears persisted state (generation-scoped single-flight so live and resume paths cannot double-redeem single-use codes, and stale generations can never mutate newer logins' state). Symptom signature: server-side logs show the handoff completing (code issued) but the app showing nothing afterwards.

## Multi-round review convergence on lifecycle/race/auth code
Security-adjacent surfaces needed 3–4 fix rounds before SHIP (6b: 10 findings → 6c/6d: 1 race split into 2 → 6e: 5 findings → 6f: 1 cross-generation regression → 6g/6i clean). Fixes themselves introduced the next finding (single-flight fix created a cross-generation race). Expect it; budget 3–4 rounds; never force-ship on 'most findings fixed'. Codex re-reviews with `do NOT modify files` + writes findings to /tmp/<name>.md + stdout; ALWAYS capture to a FILE — `| tail -N` piping truncates the head of long reports and lost the Critical section once.

## Sibling concurrent-modification trap
Multiple Cursor/agent processes + orchestrator editing the same repo: patch tool warns 'modified by sibling subagent — read before writing'. The warning is real: re-read before patching, and only patch with anchors verified from a fresh read. Also seen: a patch anchored inside a heredoc corruption risk — after any patch to a script with heredocs, `bash -n` it before running.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall