planner-spec-expand

# Planner Spec Expand A one-line brief ("build a claude.ai clone", "a habit tracker with streaks") is not enough surface for a coding agent to make good decisions from. It has no design language, no acceptance criteria, no ordering. The generator ends up inventing scope mid-session and shipping incoherent slices. The planner's job is to expand the brief into a spec dense enough that every downstream decision — what feature to pick, what "done" looks like, what the button should say — has an answer already written down. See Prithvi's post on planner/generator/evaluator separation for the underlying architecture: https://www.prithvirajrk.com/blog/three-agent-harness. ## When to apply - The user handed you a brief under ~200 words and expects a real product. - You're about to seed [[feature-list-json]] and the brief has no orderable features yet. - Scope drifted mid-project and the original spec no longer describes the target — rewrite, don't patch. ## Procedure — expand in this order Do the sections in order. Later sections depend on earlier ones being locked. 1. **Restate the brief in one paragraph.** In your own words, what is being built and for whom. If you can't write this cleanly, ask the user before continuing — the brief is under-specified. 2. **Pick a design language.** One sentence each on: visual tone (minimal / dense / playful), typography stance (one sans / serif+sans / mono accents), color posture (monochrome + one accent / two-color / full palette), density (airy / compact). This locks a thousand later micro-decisions. 3. **Enumerate the acceptance surface.** For each user-observable capability, write one sentence of user-observable behavior AND the concrete steps a human would take to verify it. This is the shape [[feature-list-json]] wants — write it in that shape now. 4. **Order the features.** Sort by dependency: nothing appears before what it depends on. Ties broken by "what does the user see first when they open the app." The top of the list must be runnable-alone. 5. **Name the out-of-scope.** One short list of things the brief could imply but you are explicitly not building. Prevents the generator from wandering. 6. **Write the smoke path.** The single user journey that proves the product exists — 3-6 steps end-to-end. This becomes the initializer's smoke test. ## Checklist before you hand off - Every feature has `description` + `steps` in the shape [[feature-list-json]] expects. - The first 3 features can be built in order with no forward dependency. - Design language fits on one screen — if it's a page, you over-specified. - Out-of-scope list is non-empty. If everything is in scope, you didn't plan, you transcribed. - Smoke path touches the core value prop, not auth or settings. ## Anti-patterns - **Padding the feature list to look thorough.** 40 real features beats 200 fake ones. The generator will build all of them. - **Designing the schema.** That's the generator's job. You describe user-observable behavior; the generator picks the data model. - **Writing prose where you should write steps.** "User can manage conversations" is not a feature. "Clicking the trash icon on a sidebar item deletes that conversation and removes it from the sidebar" is. - **Leaving priority implicit.** If two features tie, break the tie now. The generator will not. ## When NOT to apply Skip this for briefs already specified to acceptance-criteria depth, or for single-feature edits to an existing project — use [[shift-notes]] and pick from the existing [[feature-list-json]] instead. Related: [[feature-list-json]], [[shift-notes]], [[broken-window-check]].