Turn a large feature into a ladder of small contracts. Each rung should be
understandable to the human, testable by an agent, and useful before the
whole feature is done.
-
Grill before planning. Ask one question at a time until you know the
desired outcome, non-goals, review surface, sacred contracts, missing
assets, and first useful playable checkpoint. Give your recommended
answer with each question so the user can accept, reject, or edit it.
Inspect the repo instead of asking questions the code can answer.
Close the interview by asking whether the plan must carry backward
compatibility or data migrations — the default is neither: hard
cutovers, no compat shims, no migration scaffolding, no deploy-order
dances. Only the user opting in puts them in the plan.
-
Slice at API seams. Each slice should behave like a tiny library where
possible: named module boundary, typed inputs/outputs, deterministic
fixtures, and tests at the seam. If a slice needs three unrelated systems
booted before it can be checked, sharpen the seam.
-
Research the fog. When the feature depends on an unfamiliar domain,
high-fidelity visual target, named reference, benchmark, external repo,
library, or "how do people usually do this?" question, do targeted online
research before finalizing slices. Prefer primary sources: official docs,
source repos, papers, case studies, talks, and shipped examples. If a
reference implementation exists, add a replication spike before translation
or approximation.
-
Make progress visible. For visual or interactive work, every slice
should produce something playable: a route, fixture page, harness, CLI
probe, or HTML visualization the human can run, inspect, screenshot, and
critique. Tests prove contracts; demos expose taste and intent.
-
Optimize feedback loops. Slice so the next useful question can be
answered quickly. Prefer tiny runnable surfaces, hot-reloadable harnesses,
sample fixtures, and self-contained workbenches over plans that require the
whole feature to exist before anyone can learn from it. For asset-heavy
work, plan an asset app/workbench where humans and artists can add samples,
upload replacements, preview them live, and see validation failures fast.
-
Use the repo's natural shape. If the repo is a monorepo, plan apps and
packages instead of forcing everything into the current app. Give each
testable surface a first-class route or command; avoid piling new behavior
behind opaque query flags when a small dedicated app would be clearer.
-
Do not block on missing inputs. If art, data, credentials, or external
assets are missing, plan generated placeholders plus a replacement contract.
The feature should advance with placeholders, while a separate handoff path
explains exactly what the human or external partner must provide later.
-
Draft in parallel, then synthesize. For any multi-slice feature, don't
trust one pass to find the right cut. Fan out a few independent drafts and
merge the best into one plan (see the Workflow). Divergence is the point —
so engineer it on two axes: give each draft a different bias (a lens it
optimizes for) and, when more than one model family is available, a mix of
models. Blind, differently-biased drafts surface slices, seams, and risks
a lone plan misses — and where they independently agree, you know the cut
is solid.
-
Recursively uncover fog of war. The first slice graph is a scouting pass,
not proof the field is known. After drafting, inspect each high-risk slice as
if it were its own feature. If it hides multiple variables, unknown external
practice, unproven architecture, or "we'll figure it out during
implementation," reslice that subset and repeat until every next slice has
one question, one seam, one review surface, and one verdict.
-
One visual variable per slice. Visual slices fail when they ask one pass
to match the final hero image. Split by the thing being judged: density,
silhouette, colour, texture, lighting, fog, water placement, water material,
label legibility, animation rhythm. Each slice gets a crop/mask and a verdict
for that variable only. Whole-frame comparison belongs at compose/integration,
after the variables have their own evidence.
-
Interview: keep asking until you can name the slices without
hand-waving. Stop when remaining unknowns can safely be discovered by the
first slice.
-
Research: inspect the repo and research unfamiliar external practice
before drafting when the feature names a reference, library, technique,
standard, visual target, or performance pattern. Capture the discovered
source/repo/article/paper links in the spec and turn any exemplar into a
reproduction spike before a porting slice.
-
Draft in parallel: for a multi-slice feature, spawn at least three
independent subagents to draft the whole plan — fresh context each, a git
worktree apiece if they must run or build to validate, otherwise have them
return the plan inline. Three is the floor, not the count: scale the pool
with the feature's complexity, adding a drafter for each genuinely distinct
approach or lens the problem supports. Give each the same brief from the
interview and nothing else (never another draft) — but assign each a
distinct bias so their divergence is structured, not accidental. The
baseline trio:
- A — fewest-slices bias: the smallest ladder that still ships; merge
slices aggressively, question every rung.
- B — risk-first bias: front-load the scariest unknowns; order slices so
the plan dies fast if an assumption is wrong.
- C — seam-quality bias: optimize API boundaries, ownership, and
testability at each seam, even at the cost of more slices.
Swap in or add lenses when the feature demands them (e.g. asset-pipeline
bias, perf bias, migration-safety bias), but keep the biases orthogonal —
grow the pool by adding a new lens, never by running the same lens twice.
Also mix model families: if you're currently instructed to draft with
codex, run at least one draft with claude — and vice versa — so the pool
balances different models' blind spots, not just different prompts. Family
means vendor (claude vs codex), not tier: every draft uses a
state-of-the-art model; never diversify by dropping to a weaker tier of the
same family. Each drafter: recon the real code and tests (measured facts,
failed approaches, scope firewalls, greppable file/test names), then propose
the slice graph, package/app boundaries, dependencies, API seams, playable
deliverables, verification gates, and human review checkpoints. Skip the
fan-out only for a genuinely single-slice problem.
-
Synthesize: read every draft and build the canonical plan yourself —
don't anoint one. Take the strongest slicing, union the seams, risks, and
firewalls each caught alone, and where drafts disagree pick the
better-justified call and record the genuine alternative for the human. Where
the drafts independently agree you're on firm ground; where they split is
where to think hardest. When the feature has any visual surface, make
a standing
verification gate in the README so every visual slice inherits it: the spec
must tell the implementing agent to run an unbiased screenshot-critique as the
last check on any visual shot before accepting it. Whenever a slice has
something to compare its shot against — a prior look it changes, or a
reference/inspiration image added for the feature — the spec must also name
as the gate
that judges candidate-against-target: the telemetry and less-wrong verdict
that screenshot-critique's single-shot eyes do not give.
For visual work, keep feature-owned visual evidence in the spec folder:
inspiration images, reference screenshots, archived baselines, comparison
contact sheets, generated candidate captures, and critique artifacts. If those
files start outside the spec folder, copy them into the spec folder when they
become part of the feature's review context. Product snapshot folders may still
hold the active regression baselines their harnesses own, but do not rely on
those mutable outputs or external paths as the only record of what the feature
was judged against.
Every multi-slice spec README needs a "Next Agent Prompt" near the top. Write it
in second person, as the prompt a future agent should read when they resume the
feature. The README should not merely describe that it is live handoff state;
the section itself must directly tell the next agent what to do next. It should
include:
The point is that a fresh agent can open the README and know what to do next
without reading the chat.
The feature plan is done when a fresh agent can start at slice 1 without the
conversation, and the human can review the roadmap without reverse-engineering
a wall of text.
