write-spec

Files (1)

• SKILL.md

SKILL.md (first lines)

# Write Spec

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.

## First Principles

1. **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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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.

7. **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.

8. **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.

9. **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.

10. **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.

## Workflow

1. **Interview:** keep asking until you can name the slices without
   hand-waving. Stop when remaining unknowns can safely be discovered by the
   first slice.
2. **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.
3. **Draft in parallel:** for a multi-slice feature, spawn **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. Give each the *same* brief from the interview and nothing else
   (never another draft), so they diverge. Each one: 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.
4. **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
   [screenshot-critique](../../visual/screenshot-critique/SKILL.md) 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
   [compare-screenshots](../../visual/compare-screenshots/SKILL.md) as the gate
   that judges candidate-against-target: the telemetry and less-wrong verdict
   that screenshot-critique's single-shot eyes do not give.
5. **Recursive fog audit:** review the canonical graph slice by slice. For any
   slice with hidden variables, broad verbs ("make it realistic", "match the
   reference", "add the backend"), missing research, or more than one visual
   variable/API seam, run this same slicing logic on that slice as a sub-feature.
   Keep repeating until the next implementation slice can be accepted or rejected
   by one focused artifact. Record deferred variables as later slices, not prose
   inside the current slice.
6. **Materialize:** create `specs/<feature>/` when the feature has more than
   one slice or needs assets/visualizations.
7. **Refactor-clean the plan:** run [refactor-clean](../refactor-clean/SKILL.md)
   over the materialized spec — the plan is architecture too, and it must describe
   the shape the codebase would want if designed today, not the old shape with the
   feature bolted on. Name each concept that should have one owner (projection,
   environment, data contract, renderer phase, state machine, test oracle) and
   confirm no slice introduces a parallel abstraction, duplicated concept, or

From Classified-AI-Core/skill-library, MIT.

More from Classified-AI-Core/skill-library