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.
-
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:
blind 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.
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.
