planner-spec-expand

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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]].

From Archive228/loopkit, MIT.

More from Archive228/loopkit