Turn a large feature into a ladder of small contracts. Each rung should be\nunderstandable to the human, testable by an agent, and useful before the\nwhole feature is done.
\nGrill before planning. Ask one question at a time until you know the\ndesired outcome, non-goals, review surface, sacred contracts, missing\nassets, and first useful playable checkpoint. Give your recommended\nanswer with each question so the user can accept, reject, or edit it.\nInspect the repo instead of asking questions the code can answer.\nClose the interview by asking whether the plan must carry backward\ncompatibility or data migrations — the default is neither: hard\ncutovers, no compat shims, no migration scaffolding, no deploy-order\ndances. Only the user opting in puts them in the plan.
\nSlice at API seams. Each slice should behave like a tiny library where\npossible: named module boundary, typed inputs/outputs, deterministic\nfixtures, and tests at the seam. If a slice needs three unrelated systems\nbooted before it can be checked, sharpen the seam.
\nResearch the fog. When the feature depends on an unfamiliar domain,\nhigh-fidelity visual target, named reference, benchmark, external repo,\nlibrary, or \"how do people usually do this?\" question, do targeted online\nresearch before finalizing slices. Prefer primary sources: official docs,\nsource repos, papers, case studies, talks, and shipped examples. If a\nreference implementation exists, add a replication spike before translation\nor approximation.
\nMake progress visible. For visual or interactive work, every slice\nshould produce something playable: a route, fixture page, harness, CLI\nprobe, or HTML visualization the human can run, inspect, screenshot, and\ncritique. Tests prove contracts; demos expose taste and intent.
\nOptimize feedback loops. Slice so the next useful question can be\nanswered quickly. Prefer tiny runnable surfaces, hot-reloadable harnesses,\nsample fixtures, and self-contained workbenches over plans that require the\nwhole feature to exist before anyone can learn from it. For asset-heavy\nwork, plan an asset app/workbench where humans and artists can add samples,\nupload replacements, preview them live, and see validation failures fast.
\nUse the repo's natural shape. If the repo is a monorepo, plan apps and\npackages instead of forcing everything into the current app. Give each\ntestable surface a first-class route or command; avoid piling new behavior\nbehind opaque query flags when a small dedicated app would be clearer.
\nDo not block on missing inputs. If art, data, credentials, or external\nassets are missing, plan generated placeholders plus a replacement contract.\nThe feature should advance with placeholders, while a separate handoff path\nexplains exactly what the human or external partner must provide later.
\nDraft in parallel, then synthesize. For any multi-slice feature, don't\ntrust one pass to find the right cut. Fan out a few independent drafts and\nmerge the best into one plan (see the Workflow). Divergence is the point —\nso engineer it on two axes: give each draft a different bias (a lens it\noptimizes for) and, when more than one model family is available, a mix of\nmodels. Blind, differently-biased drafts surface slices, seams, and risks\na lone plan misses — and where they independently agree, you know the cut\nis solid.
\nRecursively uncover fog of war. The first slice graph is a scouting pass,\nnot proof the field is known. After drafting, inspect each high-risk slice as\nif it were its own feature. If it hides multiple variables, unknown external\npractice, unproven architecture, or \"we'll figure it out during\nimplementation,\" reslice that subset and repeat until every next slice has\none question, one seam, one review surface, and one verdict.
\nOne visual variable per slice. Visual slices fail when they ask one pass\nto match the final hero image. Split by the thing being judged: density,\nsilhouette, colour, texture, lighting, fog, water placement, water material,\nlabel legibility, animation rhythm. Each slice gets a crop/mask and a verdict\nfor that variable only. Whole-frame comparison belongs at compose/integration,\nafter the variables have their own evidence.
\nInterview: keep asking until you can name the slices without\nhand-waving. Stop when remaining unknowns can safely be discovered by the\nfirst slice.
\nResearch: inspect the repo and research unfamiliar external practice\nbefore drafting when the feature names a reference, library, technique,\nstandard, visual target, or performance pattern. Capture the discovered\nsource/repo/article/paper links in the spec and turn any exemplar into a\nreproduction spike before a porting slice.\nIf prior experiments already established an accepted approach, apply\nFrom research to implementation below before drafting alternatives.
\nDraft in parallel: for a multi-slice feature, spawn at least three\nindependent subagents to draft the whole plan — fresh context each, a git\nworktree apiece if they must run or build to validate, otherwise have them\nreturn the plan inline. Three is the floor, not the count: scale the pool\nwith the feature's complexity, adding a drafter for each genuinely distinct\napproach or lens the problem supports. Give each the same brief from the\ninterview and nothing else (never another draft) — but assign each a\ndistinct bias so their divergence is structured, not accidental. The\nbaseline trio:
\nSwap in or add lenses when the feature demands them (e.g. asset-pipeline\nbias, perf bias, migration-safety bias), but keep the biases orthogonal —\ngrow the pool by adding a new lens, never by running the same lens twice.\nAlso mix model families: if you're currently instructed to draft with\ncodex, run at least one draft with claude — and vice versa — so the pool\nbalances different models' blind spots, not just different prompts. Family\nmeans vendor (claude vs codex), not tier: every draft uses a\nstate-of-the-art model; never diversify by dropping to a weaker tier of the\nsame family. Each drafter: recon the real code and tests (measured facts,\nfailed approaches, scope firewalls, greppable file/test names), then propose\nthe slice graph, package/app boundaries, dependencies, API seams, playable\ndeliverables, verification gates, and human review checkpoints. Skip the\nfan-out only for a genuinely single-slice problem.
\nSynthesize: read every draft and build the canonical plan yourself —\ndon't anoint one. Take the strongest slicing, union the seams, risks, and\nfirewalls each caught alone, and where drafts disagree pick the\nbetter-justified call and record the genuine alternative for the human. Where\nthe drafts independently agree you're on firm ground; where they split is\nwhere to think hardest. When the feature has any visual surface, make\nscreenshot-critique a standing\nverification gate in the README so every visual slice inherits it: the spec\nmust tell the implementing agent to run an unbiased screenshot-critique as the\nlast check on any visual shot before accepting it. Whenever a slice has\nsomething to compare its shot against — a prior look it changes, or a\nreference/inspiration image added for the feature — the spec must also name\ncompare-screenshots as the gate\nthat judges candidate-against-target: the telemetry and less-wrong verdict\nthat screenshot-critique's single-shot eyes do not give.
\nRecursive fog audit: review the canonical graph slice by slice. For any\nslice with hidden variables, broad verbs (\"make it realistic\", \"match the\nreference\", \"add the backend\"), missing research, or more than one visual\nvariable/API seam, run this same slicing logic on that slice as a sub-feature.\nKeep repeating until the next implementation slice can be accepted or rejected\nby one focused artifact. Record deferred variables as later slices, not prose\ninside the current slice. The exit test is the decision budget: a slice is\nfully specified when the implementing agent inherits decisions rather than\nmaking them — every freedom left open is either named as delegated in the\nslice file or the slice needs another pass.
\nMaterialize: create specs/<feature>/ when the feature has more than\none slice or needs assets/visualizations.
Refactor-clean the plan: run refactor-clean\nover the materialized spec — the plan is architecture too, and it must describe\nthe shape the codebase would want if designed today, not the old shape with the\nfeature bolted on. Name each concept that should have one owner (projection,\nenvironment, data contract, renderer phase, state machine, test oracle) and\nconfirm no slice introduces a parallel abstraction, duplicated concept, or\ncompatibility layer that a later slice must delete. Any transitional scaffolding\na slice genuinely needs must be named as a short-lived seam with an explicit\nremoval condition and the slice that removes it — collapsed the instant its\nconsumers migrate, never carried to the end by default. Encode the resulting\nsingle-owner invariants and the end-state (\"reads as designed today, not tacked\non\") in the README so every implementing pass inherits them.
\nScrollback audit: the conversation dies; the spec survives. Before\ncalling the plan done, sweep the full conversation and every earlier\nplanning artifact (maps, interview notes, drafts) for content that exists\nonly there — decisions with their rationale, rejected alternatives with\nwhy they lost, mid-stream scope changes, user-supplied constraints and\nthrowaway remarks that decided something. Each either lands in its owning\nspec file or is deliberately dropped; a scope change propagates to every\nspot that references it, not just where it landed. Then re-read each\nsurviving pre-plan artifact the spec supersedes (a map's kickoff prompt,\nopen-questions list, or proposed plan) and mark superseded sections with\na pointer to the plan — stale instructions must not be able to misroute a\nfresh agent. Done when every conversation decision is findable in the\nspec and no surviving artifact contradicts the ladder.
\nBuild slice by slice: leave each slice with a runnable artifact and\nverification before depending on it. Keep each artifact small enough to\niterate on quickly. Keep the README's \"Next Agent Prompt\" written as the\nhandoff text a future agent should read and follow.
\nReslice when the work says so: if implementation hits a snag and the slice\nstarts changing unrelated variables — or the choices ledger keeps filling\nfrom one slice — stop broadening the patch. Update the spec\nfirst: split the slice into smaller contracts, name the frozen inputs, move the\nextra visual variables to later slices, and rewrite the Next Agent Prompt to\nresume from the first new slice. Then continue. Reslicing is progress, not\nfailure.
\nFreeze the accepted spike's runnable code, dependencies, configuration,\ninputs, prompts/skills, and evidence by immutable identity. Inspect what it\nactually does; option names and summaries are not proof of behavior.
\nMap proven behavior → evidence → owning slice → parity gate in the spec.\nGive every drafter this contract and the limits of the findings. Separate\nuser-required differences from untested proposals; cleanup must not silently\nredesign the winner.
\nPlan an early production-entry-point comparison against the frozen reference\nwith matched inputs and controlled responses. Check computed requests,\ndecisions, and complete outputs; name permitted differences. Every preservation\nrow needs an owner and a check. Run parity before expensive confirmation and\nretain the original quality gates.
\nUse specs/<feature>.md only for a small, single-slice problem. Large\nfeatures live in:
specs/<feature>/README.md — goal, context, slice graph, review map,\ncontracts, firewalls, known unknowns, and a \"Next Agent Prompt\" section with\nthe current status, next pickup point, global TODO checklist, and handoff\ninstructions for the next pass.specs/<feature>/slices/<NN>-<name>.md — one independently verifiable\nslice per file.specs/<feature>/visualizations/*.html — roadmap diagrams, prototypes,\nharness mockups, generated reports, contact sheets, or other\nhuman-reviewable artifacts.specs/<feature>/assets/ — reference images, fixtures, captures, and other\ninputs needed to judge the work.For visual work, keep feature-owned visual evidence in the spec folder:\ninspiration images, reference screenshots, archived baselines, comparison\ncontact sheets, generated candidate captures, and critique artifacts. If those\nfiles start outside the spec folder, copy them into the spec folder when they\nbecome part of the feature's review context. Product snapshot folders may still\nhold the active regression baselines their harnesses own, but do not rely on\nthose mutable outputs or external paths as the only record of what the feature\nwas judged against.
\nEach slice file answers:
\nEvery multi-slice spec README needs a \"Next Agent Prompt\" near the top. Write it\nin second person, as the prompt a future agent should read when they resume the\nfeature. The README should not merely describe that it is live handoff state;\nthe section itself must directly tell the next agent what to do next. It should\ninclude:
\nThe point is that a fresh agent can open the README and know what to do next\nwithout reading the chat.
\nThe feature plan is done when a fresh agent can start at slice 1 without the\nconversation, and the human can review the roadmap without reverse-engineering\na wall of text.
\nOnce the slices have all shipped, close-spec archives\nthe plan to specs/done/ and rewrites it from a build ladder into a durable\nrationale record.