Android product planning

Android Product Planning

This skill exists because design and engineering skills produce polished screens from incoherent prompts, and you end up with five beautiful screens that disagree about what the app does. That's the gap this skill closes - before the design skill applies tokens, before the engineering files structure state, before the MCP writes code.

v2 (May 2026). v1 caught the product-shape incoherence (the "viral chaos clock app" three-screens-disagreeing problem). v2 extends to the retention-shape incoherence (loops that don't compound), the platform-shape incoherence (decisions that ignore Android-native realities), and the category-shape incoherence (six of seven categories were stubs in v1). See README.md for the structural changes.

The core philosophy

1. Planning is product logic, not design logic. The output is a one-page spec, not a wireframe. What the app does, who it's for, how it makes money, what the user does every time they open it.
2. Most prompts hide contradictions. "Build a viral chaos app that punishes lateness" contains two product directions (viral/shareable vs. accountability/punishing) that usually conflict. The planning skill's job is to surface that contradiction to the user and force a choice before any code is written.
3. Reference real apps, not invent. For any app idea, 3-5 existing apps already live in roughly that category. Look at them. Steal what works, flip what's stale, add what's missing.
4. Monetization belongs in planning, not after. A free ad-supported app has a different shape than a $4.99 one-time purchase. Subscription apps need onboarding that justifies recurring cost. Decide the model in planning so the design skill doesn't have to retrofit a paywall onto screens that weren't designed for one.
5. Retention is a planning decision, not an engineering one. The Hooked Investment phase, the activation moment, the D30 retention target - these are upstream of "what features to ship." Surface them at plan time.
6. The platform shape is the product shape on Android. Notifications, permissions, deep links, widgets, offline behavior, AI cost - these aren't engineering concerns the team will figure out later. They anchor the spec.
7. Plan once, replan when needed. If the user's answer to a monetization or scope question changes the product fundamentally, loop back through the relevant planning questions. Don't blindly execute on a spec that the user just contradicted.

When this skill triggers

• "Build me an X app" - always plan first
• "Add a [major feature] to my app" - plan the feature, even if the app is already built
• "I have an idea for an app" - plan
• "Make me something that does Y" - plan

When NOT to trigger:

• Code-only requests on an already-planned project ("fix this bug", "refactor this composable")
• Style/visual tweaks ("make this dark mode", "change the accent color")
• Bug fixes, dependency updates, performance work

Question 0 - scope, and who is answering

Two things before the question flow:

Right-size the build. Is this a quick/personal/throwaway app or a product the user means to ship? A simple utility gets the 4-5 question floor and most of the platform and monetization machinery collapses to "N/A - v1." Do not inflate a throwaway into a startup; over-scoping is the most common way this skill goes wrong. Ask if it is unclear. For a clearly personal/learning/portfolio build, compress hard: a few lines on the loop, the primary screen, and the one differentiator; monetization is "free"; skip ASO, launch metadata, the pre-mortem, and most of the platform checklist. Save the full multi-page spec for something genuinely headed to the Play Store.

Decide who is answering. These questions are the user's to answer. If the user delegates ("you decide," "let the skills choose") or is absent, you may infer answers from research - but every inferred answer MUST be tagged [ASSUMPTION - confirm] in the spec and never written as settled fact. Audience, win/lose state, monetization, and retention targets are the user's call; when you stand in for them, label it. A spec that launders the agent's taste into fact is the failure mode to avoid.

The question flow (5-11 questions)

The v2 flow extends v1 from 5-7 to 5-11 questions, but most planning conversations only need 6-8 because branching skips irrelevant questions. The full decision tree is in references/01-clarifying-questions.md. The short version, in order:

1. The loop (full Hooked breakdown). What triggers the user? What action do they take? What variable reward do they get? What do they leave behind that pulls them back? (Investment is the most-skipped stage - surface it.)
2. Jobs to be Done. What is the user hiring this app to make progress on? What are they firing - another app, a notebook, a habit, an avoidance? (The single best counter to "cool feature in search of a user.")
3. The win state. What does success look like - what metric goes up, what feeling happens?
4. The lose state. What happens when they fail or skip? Is failure punishing, neutral, or motivating?
5. The frequency + retention targets. Daily? Hourly? Weekly? Plus D1/D7/D30 target - but state the basis. With no data for this specific product, give the number as a category-benchmark guess and tag it [guess]. Do not present an invented D30 as if it were modeled.
6. The primary screen. If the app had only one screen, what would it be?
7. Monetization. Free with ads, one-time purchase, freemium subscription, IAP, or B2B/strategic free.
8. Activation event. What single action in the first session tells you a user will come back? (See references/11-aha-moments.md for the canonical-examples library.)
9. (Conditional) The hook. Why would someone open this tomorrow if they didn't have to? Asked only when 1-8 don't make the hook obvious.
10. (Conditional, for ambitious specs) Pre-mortem. Imagine the app failed in 12 months. What's the most likely cause?
11. (Conditional) The 4 Product Risks. Value, usability, feasibility, viability - which is biggest? Asked when feasibility risk dominates (AI cost, novel hardware, platform fragmentation).

Five is the floor; eleven is the ceiling. Don't ask more than that - the user gets exhausted and the answers get worse.

Question budget by app type:

• Simple utility (calculator, single-purpose tool) - 4-5 questions.
• Habit / accountability - 7-8 questions.
• Social or community - 8-9 (always ask pre-mortem).
• AI-native - 10-11 (always ask 4 Product Risks).

The category step

Before asking the questions, identify the category. Read references/02-category-router.md. v2 covers all seven categories fully (v1 only had accountability/habit). Categories:

• Accountability / habit - references/categories/accountability-habit.md
• Productivity / task management - references/categories/productivity.md
• Wellness / mindfulness - references/categories/wellness.md (2025 was hard on this category; subs declining.)
• Social / community - references/categories/social.md (Hardest category. Always run pre-mortem.)
• Finance / money management - references/categories/finance.md (Heavy compliance overhead.)
• Tools / utilities - references/categories/tools.md
• Games / entertainment - references/categories/games.md (Game design is its own discipline; the skill is humble here.)

Once a category is identified, name 3-5 reference apps for the user. Describe what each does that's worth stealing or flipping. This anchors the rest of the planning conversation.

The coherence check (18 contradictions to watch)

Before producing the spec, run references/05-coherence-checks.md. v2 extends v1's 10 checks to 18:

v1 checks (still active):

• C1 - Viral/shareable vs. accountability/punishing
• C2 - Subscription + novelty
• C3 - Free with ads + premium aesthetic
• C4 - Daily-frequency app + slow value
• C5 - B2B framing + consumer-app screens
• C6 - Wellness category + punishing failure
• C7 - AI features + privacy expectations
• C8 - Frequency mismatch with notification permission
• C9 - Scope creep mid-planning
• C10 - "This exists already" check

v2 additions:

• C11 - Activation reachable in session 1
• C12 - Investment phase exists
• C13 - Monetization model vs. retention curve shape
• C14 - Notification permission timing
• C15 - Offline fallback for primary screen
• C16 - Widget plan present (for categories where widgets are a known retention surface)
• C17 - AI cost story present
• C18 - Pre-mortem failure mode has a mitigation

Most planning conversations surface 2-4 contradictions across the 18. If 6+ surface, the prompt was too vague - restart with a sharper one-sentence prompt.

When a contradiction surfaces, name it explicitly: "You said X and Y. These usually conflict because Z. Which is the primary direction?"

The Android platform checklist

After the questions are answered and coherence checks have run, walk through references/08-android-platform-checklist.md. 11 Android-platform decisions:

1. Notification strategy (when asked, value moment, copy, fallback)
2. Permission choreography (trigger, rationale, fallback per permission)
3. Deep link map (URL pattern -> in-app destination)
4. Widget strategy (sizes, content, refresh - or explicit "no")
5. Offline-first decision (primary-screen behavior without network)
6. Form-factor scope (phone / wear / large screen / auto)
7. AI cost story (model, on-device/cloud/hybrid, $/MAU, fallback)
8. Android Vitals stability budget (crash%, ANR%, monitoring tool)
9. Material 3 Expressive design system decision (Expressive / custom / ported)
10. Data Safety pre-flight (privacy URL, deletion URL, SDKs declared)
11. ASO and launch metadata (keywords, screenshots, video, localization)

These aren't engineering concerns the team figures out later - they're product decisions that shape what gets built. If a decision is "N/A - [reason]," record it explicitly. Silent omission is itself a planning risk. This checklist is the canonical home for these platform decisions; the design skill consumes them rather than re-deriving them, so the two do not drift.

Independent review before sign-off

One agent authoring and approving every stage is not validation - internal consistency is not correctness, and a self-passed coherence check proves nothing. Before finalizing the spec, run an independent adversarial review: where subagents are available, launch a separate one (the Task tool) briefed to "break this spec - attack its weakest assumption, its unsourced numbers, and any coherence check it passed too easily." Otherwise do a deliberate red-team pass in a fresh frame. Record what it found and fix or explicitly accept each item. At minimum the review must challenge: the unverified market facts, the retention and revenue numbers, and every decision tagged [ASSUMPTION].

The spec output

Once the questions are answered, contradictions resolved, and platform checklist walked, produce a spec following references/00-spec-template.md. The v2 template is more comprehensive than v1's one-page output - a fully populated spec runs 2-3 pages. For minimal apps, many fields will be "N/A."

The spec hands off cleanly to:

• The design skill (android-compose-design) - picks a visual style from "Design system strategy."
• The engineering plan - uses Android platform decisions, AI cost story, stability budget.
• The monetization phase (when that skill exists) - deepens the monetization-model field into pricing, paywall design, funnel events.

The replan rule

If the user's answer to a question contradicts an answer they gave earlier in the same session, stop and surface the contradiction. Don't silently rewrite the earlier answer; force them to choose.

Common cases:

1. Monetization changes scope. User says "freemium subscription" after originally saying "viral chaos novelty." The product is now different. Replan from Q1 with the new constraint.
2. Scope changes loop. User says "actually I want this to also do Y" mid-planning. Y might not fit the loop. Ask whether Y is core or optional - if core, replan; if optional, note it as a v2 candidate.
3. Retention target conflicts with frequency. User says "weekly opens" + "D30 of 30%." Math says weekly + 30% D30 requires unusual sticky value. Surface the gap.
4. Activation event isn't in v1 scope. User names an activation event that requires features the spec hasn't included. Either add the feature or pick a different activation event.

Replans are not failures. They're the planning skill doing its job - catching the contradiction before the design skill builds five screens that have to be thrown away.

Hand-off to the design skill

After the spec is complete and the user has confirmed it, the planning skill's job is done. The design skill (android-compose-design) takes the spec's "Design system strategy" field and picks a visual style. The engineering files apply.

If the design skill is not installed, the planning spec is still useful - it can be handed to any developer (or any AI) and they'll produce a more coherent product than they would from the one-sentence prompt.

Hand-off to the monetization phase

The v2 spec hands these fields to a future monetization-phase skill:

• Model: [the 5-way choice]
• Paywall placement: [high-level - after which value moment]
• Free tier scope: [what's free, what's paid]
• Compliance notes: [what's required by Play Store / law]

The monetization phase deepens these into: exact pricing, exact paywall copy + visuals, funnel events, SDK choices, regional adjustment, experimentation scaffolding. If the monetization phase surfaces a contradiction with the product spec, it invokes the replan rule and routes back here.

The split: planning answers which model; monetization answers exactly how it works.

Optional: personal asset folder

If $CLAUDE_ASSETS/android/[project]/ exists, the planning skill checks for a product-context.md file there - for projects with pre-existing constraints, brand commitments, or domain conventions that should shape the plan. Example: VetLife has commitments about not using performative patriotism, about veteran terminology, about trust-signaling as the design lane. Project-specific planning context belongs there, not in this skill.

File map

android-product-planning/
├── SKILL.md                                    <- this file
├── README.md
└── references/
    ├── 00-spec-template.md                     <- spec output format
    ├── 01-clarifying-questions.md              <- the 5-11 questions
    ├── 02-category-router.md                   <- category identification
    ├── 04-monetization-models.md               <- five monetization models
    ├── 05-coherence-checks.md                  <- 18 contradictions
    ├── 06-onboarding-activation.md             <- first session, aha moment, TTV
    ├── 07-retention-loops.md                   <- Hooked + Investment, RARRA
    ├── 08-android-platform-checklist.md        <- 11 platform decisions
    ├── 09-aso-launch-metadata.md               <- ASO, Play Store policy
    ├── 10-jtbd-framing.md                      <- Jobs to be Done
    ├── 11-aha-moments.md                       <- canonical activation examples
    └── categories/
        ├── accountability-habit.md
        ├── productivity.md
        ├── wellness.md
        ├── social.md
        ├── finance.md
        ├── tools.md
        └── games.md

Lessons learned

v1 baseline (May 2026)

The skill was created in response to a specific observed failure: the "viral chaos clock app" produced by the design skill alone exhibited three contradictions - streak system rewarded acknowledgement but share card bragged about being yelled at; "Caught Today: 7" coexisted with "no incidents yet today"; "Villain Arc: Escalating intensity" had no termination state. These are product bugs, not design bugs.

v1 -> v2 (May 2026)

v1 used in real planning conversations surfaced consistent gaps:

• The Investment phase was always weak. Apps that "remember the user's name" thought that counted; it doesn't. v2 forces the loop question to surface all four Hooked stages and adds C12 to flag thin Investment.
• Activation events were vague. "Engaged with the app" isn't an activation event. v2 adds Q8 (activation) plus the 11-aha-moments.md reference library.
• Notification timing was an engineering afterthought. It's a product decision; opt-in rates depend on it. v2 adds C14 and the platform checklist's notification section.
• Six of seven categories were stubs. v2 covers all seven with reference apps, monetization patterns, contradictions, red flags.
• No retention curve target. "Frequency" alone is aspirational. v2 adds D1/D7/D30 targets to Q5 plus C13 (monetization vs. retention shape).
• No JTBD framing. Loop-without-JTBD is mechanics without meaning. v2 adds Q2.
• No Android platform planning. v1 left this to design and engineering; both treated it as someone else's job. v2 adds the 11-decision platform checklist.
• Spec didn't capture risks. v2 adds a pre-mortem field and a risks section.

v2 -> v3 candidates (to validate after real use)

• Watch for v2 generating exhausting question flows. If users tap out at Q7, the branching isn't aggressive enough. The fix is sharper branching instructions in 01-clarifying-questions.md, not cutting questions.
• Watch for the 18 coherence checks becoming a checklist tedium. Most conversations only need 2-4 to fire. If all 18 are firing on every spec, the prompt collection is broken.
• Consider a "minimum viable planning" mode for utility-tier apps (calculator, flashlight) - currently the budget is 4-5 questions but could go lower.
• Consider building the monetization-phase skill referenced in the hand-off. The split is sketched in HANDOFF-MONETIZATION.md (in v2 release notes); the actual skill isn't built yet.
• Consider a "growth phase" skill that runs post-launch and uses real retention data to inform v1.1/v2 planning.
• Reference apps will date. The category files cite winners from 2023-2026. After ~12 months, refresh the winners/failures sections. Pattern: the shapes are stable; the examples date.
• Compose Multiplatform support - currently Android-only.
• Wear OS / Auto / foldable / tablet-specific planning flows - currently surfaced at the platform-checklist level, but could deserve dedicated files.
• Watch for the planning skill itself producing incoherent specs. If it does, the question order or category routing is wrong.

How to update this section

After each significant use of the skill, add one-line entries under v3 candidates. Pattern-match across 5-10 uses, then do a v3 pass. Don't iterate after every single use - wait for the pattern.