Android plan reviewer

Android Plan Reviewer

You are about to validate an Android implementation plan by checking every section against the real Android codebase and current Android industry knowledge. The process is iterative: spawn parallel agents to analyze sections, collect findings, apply inline corrections to the plan, and repeat until clean. This skill is Android-only - exit early if the working directory is not an Android project.

Step 0: Setup

Gather two pieces of information (skip any the user already provided):

1. Plan file path - the file to review.
2. Max iterations - how many review passes to run. The user can say a number (e.g. 3), or infinite to keep looping until zero issues remain. Default to 3 if not specified.

Once you have both, read the plan file and proceed.

Step 0.5: Android project detection

Before reviewing anything, verify this is an Android project. Check for ANY of these signals (use Glob / Bash ls):

• android/ directory at repo root (Flutter, React Native, Cordova, Ionic projects)
• app/build.gradle or app/build.gradle.kts
• AndroidManifest.xml anywhere in tree
• pubspec.yaml with a Flutter declaration AND an android/ directory
• Unity project with Android export markers (ProjectSettings/AndroidPlayer* or Assets/Plugins/Android/)
• React Native android/build.gradle
• Capacitor capacitor.config.* referencing android platform

If NONE match, exit immediately with this message and stop:

Not an Android project. This skill (android-plan-reviewer) only validates Android implementation plans. Use a generic plan-review skill instead.

Otherwise, continue to Step 1.

Step 1: Detect Section Structure

Plans come in many formats. Read the file and figure out how THIS plan is organized. Common patterns:

• Markdown headers (##, ###, or mixed depths)
• Numbered sections (1., 1.1, 2.)
• Bold-text headings (**Section Name**)
• Horizontal rules or blank-line separators
• Any combination of the above

Identify each discrete section:

• Title or identifier
• Line range (start–end)
• Full text content

Tell the user: "Found N sections. Starting review pass 1…"

Step 2: Spawn Parallel Review Agents

Launch one Agent per section using subagent_type: "general-purpose". To avoid overwhelming the system, clamp to 10 agents per batch:

• If there are ≤ 10 sections, launch all agents in a single message.
• If there are > 10 sections, split into batches of 10. Launch each batch in one message (all agents in the batch run in parallel), wait for the batch to complete and collect results, then launch the next batch. Continue until all sections have been reviewed.

Every section gets its own agent regardless of size - don't merge or skip small sections. A 3-line "Scope Check" section gets the same treatment as a 200-line task implementation. Small sections are fast to review and occasionally hide wrong assumptions.

Each agent gets this prompt (fill in the {{placeholders}}):

You are reviewing one section of an implementation plan for accuracy and quality.

## Your Section

**Title:** {{section_title}}
**Content:**
{{section_text}}

## Project Context

Working directory: {{cwd}}

## Phase 1 - Codebase Validation

Verify every factual claim this section makes against the actual Android code. Specifically check:

- **File and directory paths** - do they exist? (use Glob, Read)
- **Function / class / variable names** - do they exist with the described signatures? (use Grep, Read)
- **Architecture claims** - does the code actually work the way the section describes? Read the relevant source files.
- **Gradle dependencies and versions** - do `build.gradle`, `build.gradle.kts`, `libs.versions.toml`, or `settings.gradle*` declare the versions the plan assumes? Check `app/`, root, and any included modules.
- **AndroidManifest** - do declared permissions, activities, services, receivers, providers, intent filters, and `<meta-data>` entries match the plan?
- **ProGuard / R8 rules** - are referenced rules present in `proguard-rules.pro` (or equivalent)? Are keep rules consistent with what the plan describes?
- **Signing config** - do `signingConfigs` blocks in `build.gradle*` match the plan's assumptions about debug/release signing?
- **SDK levels** - do `compileSdk`, `minSdk`, `targetSdk` in `build.gradle*` match the plan?
- **UI stack** - does the project actually use what the plan claims (Jetpack Compose, classic Views, Fragments, Navigation Component, etc.)? Check imports and `setContentView` vs `setContent` usage.
- **Cross-platform layer** - for Flutter / RN / Unity / Capacitor projects, also verify the JS/Dart/C# side matches plan claims about bridges, channels, plugins.
- **Configuration** - do `gradle.properties`, `local.properties`, `google-services.json`, env vars, and project settings match the plan's assumptions?

For every claim, confirm it or flag it as incorrect.

## Phase 2 - Web Research

Use WebSearch and WebFetch to check (Android-focused):

- **Android SDK** - what is the current stable target SDK? Is the plan's `targetSdk` still allowed by current Play Console policy? Are referenced platform APIs deprecated or removed in newer API levels?
- **Jetpack libraries** - current stable versions (androidx.*, Compose BOM, Navigation, Room, Lifecycle, WorkManager, etc.). Compose: stable channel vs alpha/beta - is the plan tracking the right channel?
- **Play Console policy** - recent policy changes (data safety, target SDK requirements, billing, permissions) that affect the plan?
- **Play Billing** - current Billing Library version, breaking changes since the plan's assumed version?
- **Material Design** - Material 3 / Material You guidance changes; deprecated components?
- **Firebase / Play Services** - current SDK versions, deprecated APIs, BoM versions?
- **Android Gradle Plugin (AGP) / Kotlin / Gradle** - current stable AGP, KGP, Gradle versions and known incompatibilities with the plan's versions?
- **Deprecated APIs** - has any framework, Jetpack, or Play Services API the plan references been deprecated, removed, or superseded?
- **Architectural best practices** - is the proposed approach still recommended (e.g., MVI vs MVVM, single-activity vs multi-activity, Hilt vs Koin, Compose Navigation vs Navigation Component, KMP vs platform-only)? Cite official Android Developer docs where possible.
- **Security** - known CVEs or vulnerability patterns (insecure deeplinks, exported components, WebView misuse, weak network configs, key storage, biometric prompt misuse).
- **Community consensus** - check official Android Developers docs, AndroidX release notes, Google I/O sessions, and reputable sources (not just blog posts).

Go deep - don't just confirm the surface claim, check whether the underlying approach is still recommended for Android in 2026.

## Output Format

For each issue you find, return exactly this structure:

ISSUE:
- Section: {{section_title}}
- Location: "{{exact quote from the plan that is wrong or problematic}}"
- Problem: {{what is wrong and why}}
- Correction: "{{the corrected text that should replace the quoted location}}"
- Source: {{how you verified - file path you read, URL you checked, etc.}}
- Severity: {{critical | important | suggestion}}

If you find zero issues, return exactly:

NO_ISSUES: {{section_title}}

Step 3: Collect and Consolidate

Wait for all agents to complete, then gather their results.

Group issues by severity:

1. Critical - factual errors (wrong file paths, nonexistent functions, broken APIs)
2. Important - outdated versions, deprecated patterns, architectural anti-patterns
3. Suggestions - better alternatives, minor improvements, nice-to-haves

Tell the user: "Pass N: found X issues (Y critical, Z important, W suggestions) across N sections."

If zero issues were found across all sections, skip to Step 6 (early termination).

Step 4: Apply Inline Corrections

Edit the plan file. For each issue, replace the problematic text with the corrected version plus a review annotation.

Correction format

Replace the wrong text and append a short bracketed note explaining why:

Before:

Set up a PostgreSQL 14 connection pool using `pg-pool` v3.2

After:

Set up a PostgreSQL 16 connection pool using `pg-pool` v3.7 [Reviewed: PostgreSQL 16 is the current stable release; pg-pool 3.7 includes critical connection-leak fixes - see https://github.com/brianc/node-postgres/releases]

For architectural concerns where the original text isn't factually "wrong" but the approach is problematic, insert a correction note directly after the relevant paragraph:

[Reviewed: This approach creates a new DB connection per request, which is a well-documented anti-pattern under load. Use a connection pool with a max-connections limit instead - see https://node-postgres.com/features/pooling]

Rules

• Every [Reviewed: …] annotation includes why and a source (file path or URL).
• Keep corrections concise - fix the problem, don't rewrite the whole section.
• Preserve the plan's original structure and formatting.
• Apply ALL issues (critical, important, AND suggestions), not just the severe ones.
• Use the Edit tool for surgical changes. Don't rewrite the entire file.

Step 5: Loop or Stop

Increment the iteration counter. Then:

• Zero issues this pass → stop (the plan is clean). Go to Step 6.
• Iteration count < max (or max is infinite) → go back to Step 1. Re-read the modified plan - corrections might have introduced new inconsistencies, and fresh eyes catch things the first pass missed.
• Iteration count ≥ max → stop. Go to Step 6.

Tell the user at each decision point: "Pass N complete. [Continuing… / No issues found - stopping. / Max iterations reached - stopping.]"

Step 6: Final Summary

When the review is done, report:

• Passes completed
• Total issues found and corrected, broken down by severity
• Which sections needed the most work
• Any open concerns that require human judgment (e.g., two valid architectural approaches where the "right" choice depends on business context)