Android Plan Review

Android Plan Review

> Reviews implementation plans and architecture proposals. For existing code, use /supervised-review.

Android Anti-Patterns — Quick Reference

Flag any of the following the moment they appear in the plan — do not wait for domain reviewers:

• NEVER accept a plan that calls DAOs directly from a ViewModel — repository layer boundary violation; breaks testability and single-source-of-truth.
• NEVER accept GlobalScope for any operation — unstructured, non-cancellable, guaranteed memory leak vector.
• NEVER accept user-editable state stored in-memory only with no SavedStateHandle — lost on process death, fails Android CTS.
• NEVER accept StateFlow used for one-shot navigation events — re-delivered on resubscription and config change; use Channel + receiveAsFlow().
• NEVER accept collectAsState for Flow collection in Composables — use collectAsStateWithLifecycle or leaks collection during background.
• NEVER accept a ViewModel scoped as @Singleton in Hilt — survives screen destruction, holds stale UI state indefinitely.
• NEVER accept PII, auth tokens, or credentials in Logcat — Play Store policy violation; always CRITICAL severity.
• NEVER accept a Foreground Service plan without explicit android:foregroundServiceType — crash on API 34+ (Android 14).
• NEVER accept SharedPreferences for new structured persistence without justification — DataStore is the current MAD recommendation.
• NEVER accept a plan that omits android:exported on a component with an intent filter targeting API 31+ — required field, causes install failure.

---

Required Inputs

Load files only at the phase indicated. Pre-loading wastes context; the skeptic.txt / domain-reviewer.txt mutual exclusion is a hard correctness requirement — a reviewer persona contaminated with skeptic instructions will hedge findings instead of committing to them.

| File | Load at phase | Do NOT load at | If missing | |---|---|---|---| | references/prompts/orchestrator.txt | Start of run | — | Apply Non-Negotiable Rules + Orchestration Sequence from this SKILL.md | | references/prompts/lead-engineer.txt | Start of run | — | Inline: assign 5 domains per catalog below, produce Plan v1, respond to skeptic IDs | | resources/audit-passes.md | Step 3 — before reviewer spawn | Start of run | Refuse to run — audit cannot proceed without pass definitions | | resources/severity-guide.md | Step 3 — before reviewer spawn | Start of run | Refuse to run — findings cannot be graded without it | | references/prompts/domain-reviewer.txt | Step 3 — before reviewer spawn | Step 5 (MUST NOT load alongside skeptic.txt) | Inline the 8 passes from resources/audit-passes.md + severity rubric | | references/prompts/skeptic.txt | Step 5 — before skeptic spawn | Step 3 (MUST NOT load alongside domain-reviewer.txt) | Inline: no artifacts, no solutions, challenge-only, use SK--### format | | references/templates/domain-round-template.md | Step 5 — before skeptic spawn | — | Use Skeptic Transcript Contract section below | | references/templates/final-report-template.md | Step 7 — final compile | — | Use Required Final Output section below |

---

Non-Negotiable Rules

• Keep all work in a single end-to-end run. No deferred phases.
• Domain scopes are disjoint. No plan section falls in two domains.
• Skeptic is challenge-only. Skeptic emits no designs, no fixes, no code.
• Every finding references a plan section or line — vague findings ("needs more thought") are rejected.
• Every patch-note change maps to exactly one SK--### ID from that domain's transcript.
• Final issue list preserves original reviewer finding IDs and any skeptic ID that altered it.
• Duplicates merged during consolidation must preserve source-domain traceability.

NEVER

• NEVER assign a plan section to two domains. Creates duplicate, conflicting findings.
• NEVER let the skeptic see another domain's findings. Cross-contamination breaks traceability.
• NEVER spawn domain reviewers sequentially when subagents are available. Parallel depth is the point.
• NEVER name a domain "misc", "other", or "general". Unscoped domains produce unchallengeable findings.
• NEVER let the lead invent new findings during refinement. Skeptic rounds expose gaps; they do not authorize new scope without a triggering SK--### ID.
• NEVER skip the skeptic phase for any domain. Every domain must be adversarially reviewed.
• NEVER emit a patch-note change without its originating SK--### ID.

---

Orchestration Sequence

Execute in this exact order:

1. Scope phase. Read the plan document(s) provided by the user. Identify: feature scope, stated tech stack, screen/flow inventory, data model sketches, any constraints noted.

1. Lead engineer assignment. Assign the plan sections across the five fixed Android domains below. For each domain, define:

• Which plan sections / components it owns (disjoint).
• A one-line rationale for why this grouping makes sense for this plan.
• Note if a domain has "no planned content" (still receives a skeptic round asking whether the omission is intentional).

1. Parallel domain reviewers. MANDATORY before spawning: Read references/prompts/domain-reviewer.txt, resources/audit-passes.md, and resources/severity-guide.md in full. Do NOT load references/prompts/skeptic.txt at this step. Spawn one general-purpose subagent per domain in a single message (multiple tool calls). Each subagent prompt includes:

• The full domain-reviewer.txt persona.
• The domain's assigned plan sections.
• The 8-pass audit checklist.
• The severity rubric.
• Output contract: findings table with id | severity | pass | plan-ref | problem | recommendation.

1. Consolidation → Plan v1. Lead merges raw findings; deduplicates while preserving source-domain IDs. Malformed rows (missing plan-ref or wrong ID format): mark [MALFORMED] with source domain; proceed with valid rows.

1. Per-domain skeptic rounds. MANDATORY before skeptic spawn: Read references/prompts/skeptic.txt and references/templates/domain-round-template.md in full. Do NOT reload domain-reviewer.txt. For each domain (sequential or parallel):

• Skeptic receives only that domain's Plan v1 slice.
• Skeptic emits IDs SK--001, SK--002, …
• Lead responds per ID with Decision: ACCEPT/REJECT/DEFER, Rationale, Plan Delta.

1. Per-domain refinement. Lead applies accepted deltas. Produces Patch Notes ( v1 → final) mapping every change to its SK--### ID.

1. Final compile. Merge refined per-domain slices into one severity-grouped issue list. Append transcripts and patch notes as appendices.

---

Android Domain Catalog (Fixed)

These five domains are always used. If a domain has no content in the plan, the reviewer still runs and flags the omission.

| Domain | Plan sections it owns | Android scope | |---|---|---| | ui-compose | Screens, navigation graph, UI state design, theming, component hierarchy | Composables, state hoisting, NavHost/destinations, Material 3, accessibility, @Preview strategy, recomposition safety | | arch-viewmodel | ViewModel design, UiState shape, use cases, domain layer, coroutine scopes | MVVM/MVI correctness, StateFlow/SharedFlow usage, use-case boundaries, viewModelScope, process-death survival, SavedStateHandle | | data-repository | Repository interfaces, Room schema, DataStore, network layer, caching strategy | Repository pattern, Room entities/DAOs/migrations, DataStore vs SharedPrefs, Retrofit/Ktor setup, offline-first considerations, threading | | di-wiring | Hilt module design, bindings, component scopes, injection strategy | @InstallIn scoping, @Singleton vs @ActivityRetainedScoped vs @ViewModelScoped, @Provides vs @Binds, test substitution | | platform-android | Manifest, permissions, lifecycle, background work, ProGuard/R8, build config | AndroidManifest.xml completeness, runtime permissions UX, WorkManager/Service/BroadcastReceiver plan, activity/fragment lifecycle concerns, minSdk targets, R8 keep rules |

---

Required Final Output

Start with exactly:

# Android Plan Review —

Then include sections in this exact order:

• ## A. Plan-as-submitted — feature scope, stated stack, screens/flows inventoried, stated constraints
• ## B. Domain Assignments — table: | Domain | Plan sections owned | Reviewer agent |
• ## C. Domain Findings (raw) — one subsection per domain with the 8-pass findings table
• ## D. Consolidated Plan v1 — severity-grouped findings list, IDs preserved
• ## E. Skeptic Transcripts (per domain) — one subsection per domain
• ## F. Patch Notes (per domain, v1 → final) — one subsection per domain
• ## G. Final Issue List — severity-grouped, with source IDs
• ## H. Quick-Start Checklist — ≤15 actionable items the implementer should address before writing code, derived from G

---

Skeptic Transcript Contract

ID format: SK--### where ` is the kebab-case domain name. Examples: SK-ui-compose-001, SK-di-wiring-007`.

For each skeptic ID, include:

• Challenge — what assumption or design decision is questionable
• Failure mode — what breaks at runtime, or how the plan leaves the implementer stuck
• Evidence — which finding ID or plan section triggered this concern
• Questions — concise questions the lead must answer

For each patch-notes section, map every change item back to exactly one skeptic ID from that domain's round.

---

Subagent Failure Handling

No output from a domain reviewer: Do not proceed to consolidation. Re-spawn with identical prompt. If it fails twice, run that domain inline in the main thread. Note the fallback in section B: "(domain): ran inline — subagent unavailable".

Reviewer returns findings outside its assigned plan sections: Mark those rows [OUT-OF-SCOPE: route to ] and move them to the correct domain's raw findings table in section C before consolidation. Do not discard — misrouted findings often reveal real cross-domain coupling the plan didn't acknowledge.

Domain has zero findings: Before accepting, verify explicitly: (a) the domain's assigned plan sections contained real design decisions (a bare heading is not reviewable), and (b) all 8 passes were attempted. Record in section C: "(domain): 8 passes run, sections [X, Y] reviewed — no findings." Silent zero rows without this note are rejected.

Plan section is too brief to review (e.g., a single heading with no detail): Flag as [UNDERSPECIFIED] in the domain assignment table and note it in section A. The skeptic round for that domain must include at minimum one challenge on whether the omission is intentional.

Skeptic produces no challenges for a domain with >3 findings: Re-run the skeptic with an explicit instruction to challenge severity assignments at minimum. A non-empty finding set with zero challenges is a skeptic failure, not a clean bill of health.

---

Inline Fallbacks

If subagents are unavailable (Claude.ai): Run domain reviewers one at a time in the main thread. Each reviewer pass is still fully completed before moving to the next domain. The skeptic rounds still run per-domain. Output shape is identical.

If references/prompts/orchestrator.txt is missing: Treat this SKILL.md as the orchestrator prompt.

If a domain reviewer cannot load resources/audit-passes.md: Refuse to produce findings for that domain and report the missing file.

If the skeptic prompt is missing: Inline the skeptic role: produce no artifacts; propose no solutions; challenge assumptions, logic, Android-specific correctness, and edge cases only; use the SK--### ID format.

---

Prompt Assembly Guidance

When spawning each reviewer agent:

• Load the role prompt from references/prompts/domain-reviewer.txt.
• Pass the domain's assigned plan sections as explicit boundaries — reviewers must not opine on other domains' sections.
• Enforce the output table format: id | severity | pass | plan-ref | problem | recommendation.
• Keep reviewer responses deep but scoped; keep consolidation centralized in the lead lane.

Use references/templates/domain-round-template.md for skeptic rounds and references/templates/final-report-template.md for final assembly.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RyanMakesAndBreaksStuff
• Source: RyanMakesAndBreaksStuff/Custom-Codex-Claude-Plugins-and-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.