Turn the task into one governing implementation contract: what must change, what must remain intact, how the selected design works, and how to verify the result. Write for an implementer who has the spec and its identified sources but none of this conversation. Deliver the specification without implementing it.
Recover the current task and its evidence
On every invocation or continuation, reread the task, resolved user decisions, repository instructions, and research sources. For an existing spec, read its complete current text and required linked parts, including edits made since the previous invocation. Read supplied feedback in full. Use memory and old reports to locate sources, never to reconstruct their present contents.
Establish the checkout and source revision. Inspect Git status, relevant committed changes, staged and unstaged diffs, and untracked file contents; read the actual files supporting the design. Respect a requested revision without mixing in other states. Use equivalent current sources outside Git. A clean tree, unchanged HEAD, or unchanged dirty-file list does not establish that earlier evidence still holds.
Derive the required outcomes, allowed changes, preserved behavior, exclusions, and unresolved decisions from the task and user instructions. Separate intended behavior from observed capability. A newer document or review suggestion changes neither a settled user decision nor task scope by itself. Apply a new user decision only to what it changes, retaining the other constraints.
For roadmap work, reopen the governing task, related earlier and future tasks, and their linked decisions. Establish which prerequisites actually exist and which earlier contracts must survive. Carry forward what later tasks will consume, extend, replace, or migrate; what this requires of the current task; and what work and decisions remain theirs. Follow relevant relationships across phases. Do not invent requirements from future task titles or unspecified future design. For standalone work, use the available context without requiring a roadmap or a particular preparatory skill.
Verify the task's motivating premises before designing around them. Check the facts used from prior research against implementation, consumers, contracts, tests, configuration, and version-relevant primary documentation as needed. Investigate missing facts and dependencies newly introduced by a candidate design. Reuse still-valid research without repeating unrelated investigation. Distinguish verified facts, supported inferences, and unresolved assumptions. A roadmap checkbox or a proposed interface is not evidence of an existing capability.
Resolve the design within the established boundary
Compare viable approaches against the required behavior, verified system, and constraints. Select and explain the technical design delegated to this stage, including meaningful alternatives and tradeoffs. Keep explicit user selections and decisions reserved for the user authoritative. An implementation finding that disproves a design does not itself authorize taking over its reserved replacement decision, even when an alternative preserves the goal and scope.
Use the earlier/future relationships in the choice: explain whether an approach preserves required contracts, provides a later task's prerequisites, blocks its planned transition, or duplicates its work. Ground these consequences in actual tasks and evidence. Respect planned replacement instead of freezing today's structure forever. Do not design future tasks, build their features early, or add abstractions for hypothetical needs. If a route needs work outside this task, find an in-scope alternative or raise the dependency and its consequences.
Resolve researchable facts yourself. Ask one concrete question at a time when purpose, product behavior, scope, ownership, acceptance of an unagreed material risk, or a reserved design choice needs the user. Present evidence and useful options; wait for the answer while continuing independent work. If evidence is unavailable, identify the missing fact and the decision it prevents instead of guessing.
When a premise fails, reconsider every dependent conclusion before elaborating the design. Rebuild affected parts when necessary. If the task's rationale or boundary is invalid, explain why and what must be decided; do not rescue it by adding requirements. Leave behaviorally equivalent local coding choices to the implementer, but resolve choices that determine observable behavior or contracts.
Build a contract that can be implemented and checked
State the purpose, required result, allowed and excluded work, preserved behavior, starting state and prerequisites, selected design, relevant roadmap constraints, and substance of user decisions. Include enough rationale to distinguish an intentional choice from an unresolved question.
Make every task obligation traceable through these connected parts, using a layout suited to the task rather than a mandatory document schema:
- Behavior: define inputs, preconditions, reachable branches, observable results, state changes, and side effects. State what the caller and downstream consumers observe, including when the operation cannot complete.
- Integration: assign responsibility to components and specify producer and consumer contracts: data shapes, validation, transformations, persistence, and identity across boundaries as needed. Verify that producers can supply what consumers require. Identify existing and proposed locations and the wiring that makes each path reachable.
- Work: order implementable pieces by dependency, beginning with a coherent slice and covering the full outcome. Give each piece its locations, prerequisite, intended change, and check. Include necessary consumer, configuration, data, and test changes without absorbing cleanup or another task's responsibilities.
- Verification: connect each obligation to an observable check with setup, expected result, and observation point. Cover preservation as well as changes. Derive expectations from requirements and independent evidence, not merely the selected design's own calculation or list. Include a distinguishing negative case when the example alone could let an incorrect implementation pass.
Follow complete paths through producers and consumers, including alternative entrypoints that use the changed contract. Specify relevant rejection and failure outcomes, missing or invalid input, partial effects, retries, duplicates, concurrency, and recovery where reachable. Identify which branches reuse verified existing behavior and which require new work. Include compatibility, migration, or rollout only where this change needs them. Do not enumerate impossible cases or invent policies for neighboring features; take missing product decisions to the user. Bound universal claims to the paths the evidence and checks cover.
Put every implementation-critical rule in the spec or an explicitly linked, accessible required spec part. Replace "as discussed" or "option B" with the actual rule, define task-specific terms, and cite concrete source locations or document sections and versions beside claims. Make required supporting sources locatable without session access. A chat, research brief, or review report may explain a choice, but cannot be its only authoritative home. Separate planned verification from checks already performed and record material environment limitations.
Keep one coherent specification through revisions
Use the supplied destination or the repository's spec location. Otherwise check
for an existing task spec, then use specs/<task-slug>/spec.md for a new one.
Prefer one document; if a split helps, link every required part from its entry.
Give each rule one authoritative home. Keep the existing task artifact when
revising unless the user requests another version.
Check each feedback claim against the current spec, task, and evidence. Identify already-resolved or unsupported findings instead of automatically applying them. For accepted corrections, replace or remove the faulty rule and update its effects across behavior, interfaces, examples, diagrams, ordered work, and acceptance. Reassess dependent decisions after a changed premise. Preserve valid requirements while replacing an invalid design within the authority established above.
Keep the resulting document readable as a single current design. Do not append review rounds, duplicate rules, speculative mechanisms, or exceptions merely to retain old text. A real omission may require detail; every addition must serve this task. An out-of-scope improvement remains outside it. Recheck affected requirements throughout the document after each resolved user decision.
Verify the saved handoff before declaring readiness
Before writing, compare the destination with the version you read, incorporate compatible new edits, and resolve material conflicts against governing decisions. Save and reopen the complete spec and every required part. Compare them with the original task obligations and roadmap constraints, not just the work list you authored: each in-scope obligation must have consistent behavior, ownership, ordered work or verified reuse, and acceptance. Preserve explicit exclusions; do not drop a required outcome to make the plan appear complete. Walk the relevant success and failure paths across boundaries and work backward from acceptance checks to the intended outcome. Correct conflicts between prose, examples, interfaces, diagrams, and the plan.
Read as a new implementer: identify anything that still requires conversation memory, an inaccessible reference, a guessed contract, or a missing decision. Make those answers explicit while preserving legitimate local coding freedom. Check source locations and links. Compare relevant source content, including roadmap decisions and dependencies, with what supported the design; revalidate affected choices after intervening changes before claiming it matches that state.
Declare readiness only when the complete task is actionable and no material fact, behavior, feasibility issue, or required user decision is unresolved. Explain why any remaining uncertainty cannot change the contract. A partial draft, interrupted check, or bounded revision does not establish whole-spec readiness. State what remains and what would resolve it; a later review is no reason to leave a known gap.
Return the saved location, selected approach, feedback disposition when relevant, and readiness or blockers. Report checks actually performed without treating planned tests as executed. End at this deliverable unless the user's request also authorizes another stage.