Keep an existing Technical Design Document (TDD) aligned with the latest decisions and repository reality. Work in lockstep with the user: resolve one design decision, repaint the affected design, report it, and stop.

If the invocation contains no feedback, comment set, or requested direction, send this and stop:

How should we continue the technical design: apply a concrete change, examine
one unresolved decision in depth, or identify the next missing design question?

Otherwise classify the turn as direct feedback, artifact comments, continued grilling, or completion. Follow only that branch through the runbook.

Identify the task directory from the invocation or conversation. If it remains ambiguous, ask one question for the exact task or TDD path and stop.

For , use on the exact directory because it may be a symlink; enumerate that task directory without recursive glob or grep traversal. Read every file in it in full, including the current TDD and any ticket/task, research, design discussion, PRD, mockup, implementation note, or earlier artifact. Read every path or source named in the feedback in full as well.

Before processing feedback or comments, read Feedback intake and resolution. It defines the exhaustive source inventory, artifact-comment retrieval branch, separate design/comment states, and the one-decision resolution loop.

This step is complete when every available input is represented in the feedback inventory, the current TDD is identified, and missing or inaccessible inputs are named.

Select the one open item that blocks the most downstream design work. When it asserts repository behavior, requests detail about existing functionality, or depends on an implementation pattern, read Code research and evidence before proposing or editing anything.

Trace the item to every potentially affected surface: component boundary, data/control flow, public contract, persistence/schema, failure behavior, program structure, product behavior, verification, migration, rollout, and backout. Mark a surface not applicable only after checking it.

This step is complete when the active item is supported by cited evidence, established as a product/design choice, or explicitly blocked on one missing fact.

For direct feedback, test the requested correction against the evidence and discuss any conflict. For artifact comments, preserve the comment thread's identity and state while resolving its design claim. For continued grilling, find the next unresolved or sparse part of System Design or Program Design without expecting a prewritten question list.

When a decision is still open:

Answer clarifying questions without editing. Continue the same decision on the next turn until it reaches an explicit disposition.

This step is complete when the item is accepted, accepted with an evidence-backed adjustment, rejected, superseded, or blocked—or when the single question has been sent and the turn has ended.

Before editing, read TDD design and visual language. It defines document precedence, System Design versus Program Design, selective diagrams and code-shape views, product-document propagation, consistency checks, and Markdown fencing.

Edit the TDD at its original path. Preserve its YAML frontmatter and every metadata value unless the user explicitly authorized a metadata correction. Rewrite the smallest complete affected section so it reads as intentional current design, not appended feedback. Update adjacent prose, diagrams, signatures, examples, and cross-references whenever the changed decision invalidates them.

If the decision changes product scope or UX, update the PRD and/or mockup in the same turn. If Mermaid or plain text cannot communicate the decision clearly, take the HTML branch: read the artifact template, copy its complete block into , add focused realistic content, and link it beside the TDD section it explains. If the current host supports inline previews, it may additionally preview that same file.

For artifact comments, change comment state or post a reply only when the user authorized that action. Design incorporation and comment resolution are separate outcomes.

This step is complete when the resolved choice is woven into every affected document and visual, with no question log or stale alternative left in the current-design prose.

Audit every surface marked affected in step 2. Confirm:

This step is complete when every affected surface passes or is explicitly recorded as an open blocker. Do not declare the design complete with an unaccounted contradiction.

After one incorporated decision, report the changed section and its local path or optional artifact permalink. Ask one specific next-step question, naming the next unresolved decision when one exists, and stop.

When research or an authorized comment operation is blocked, name the missing evidence or failed thread action, state what remains unchanged, ask one question that can unblock it, and stop. A successful design edit does not hide a failed comment operation.

Only when the coherence gate finds the design fully resolved—whether the user said they are done or the design naturally reached closure—read the resolved TDD handoff and follow it exactly. Add no preamble or trailing summary. Use an artifact permalink when the environment provides one; otherwise substitute the local TDD path.

Every turn ends in exactly one of these observable states: