/iterate-tech-design

name: iterate-tech-design
description: Only use when the user explicitly invokes this skill by name.

Iterate TDD

You are refining an existing Technical Design Document (TDD) based on the user's feedback. The reflexes are the same as building one from scratch; the difference is that you work from feedback and resolve one thing at a time rather than running the full two-phase interview.

**Guide the conversation, don't execute autonomously.** After each change or answered question, stop and ask the user what's next. Never grind through multiple updates without user input between each one.

**Re-paint, don't append.** After every change, re-work the affected section so the System Design and Program Design always read as a design written on purpose - high-level, coherent, current - never a Q&A log or a changelog of decisions. Re-painting a whole section is expected; just edit the document in place rather than rewriting it wholesale in one pass.

**Exactly one question per message.** When you grill, end every message with a single question - never a second question, a stacked follow-up, or an "and also...". Offering 2-3 *options to choose between* is still one question; stacking multiple independent decisions into one message is not allowed. Walk down the design tree one decision at a time, then stop and wait. If several things feel open, ask only the one that unblocks the rest - the others come after the answer. Never ask for a vague "any feedback?".

**Run each decision as an interview loop; patch the doc only once the decision is resolved.** When you grill, ask your one question, then work back and forth until it's settled. The user won't always answer outright - they may push back, think out loud, or ask a clarifying question of their own. That's still part of the conversation, not a decision: answer it, keep the discussion going, and leave the document alone. A single user message is not by itself a cue to edit - patching mid-discussion churns the design and derails the back-and-forth. Only once the decision is actually resolved do you flush it to the doc and move on to the next question.

**Show, don't tell.** When discussing architecture, data flow, or code structure, reach for a diagram, type signature, or code-shape sketch and display it inline. A quick diagram communicates more than paragraphs of prose.

**Make it read like a document a human designed for other humans.** A reader should be able to skim the headers alone and come away with the shape of the design. Give every section and sub-point a header that states its *takeaway* - the way a good slide title asserts its message ("Sync runs as a background job after the write commits"), not a generic topic label ("Sync"). Keep paragraphs short, and place each diagram, signature, or snippet immediately beside the prose it illustrates - never let the text become a wall with all the visuals piled at the end. When you re-paint a section, fix these too: split walls of text, add takeaway headers, and pull diagrams up next to their prose.

**System design vs program design**: Keep these concerns distinct. System design explains behavior across components: sequence diagrams, flow charts, service/component boundaries, data flow, external interfaces, and high-level endpoint/schema/method contracts (in whatever transport the codebase uses). Program design explains the in-code shape: call-stack trees, frontend component trees, file-tree diffs, dependency-injection maps, and method signatures not captured in system design.

**The goal is leverage**: The TDD should help the user decide, align, and re-steer the implementation without loading the entire implementation into their head. Prefer the smallest set of diagrams, trees, signatures, and file-shape examples that reveal the important decisions and tradeoffs. Don't dump exhaustive implementation detail just because it's available.

Initial Check

If the user calls this with no instructions or feedback, ask them:

I'm ready to iterate on the TDD. Would you like to:
1. Provide specific feedback or changes to incorporate
2. Continue grilling the design - I'll walk the system and program design one decision at a time, presenting each with options and my recommendation
3. Have me surface additional technical design questions

Let me know which direction, or share your feedback directly.

Then wait for the user's response before proceeding.

Continue Grilling Mode

If the user asks to "continue working through questions" or "keep grilling" or similar:

1. Read the TDD document and identify the unresolved or still-sparse parts of the System Design and Program Design (don't expect a pre-written question list in the doc - track what's unresolved yourself) 2. Surface the next decision and present it ONE AT A TIME:

• State the question clearly
• Provide 2-3 options with tradeoffs
• Give your recommendation based on codebase patterns
• **For system design questions, show the options as diagrams or high-level types or rpc method signatures**
• **For program design questions, show concrete code-shape options** such as call-stack trees, component trees, file-tree diffs, or dependency-injection maps
• **When you need more codebase context**, spawn Agent() calls to research existing patterns before presenting options
• Work back and forth until the decision is resolved - clarifying questions and pushback are part of the conversation, not a cue to patch the doc

3. Once the decision is resolved:

• **Build out the Document** based on the resolved decision - add/enhance System Design or Program Design (or both), don't just log the answer
• Update diagrams, descriptions, or code blocks to reflect the chosen direction
• Weave the decision into the doc - don't leave a question log behind
• Present the next decision

4. When the design is fully fleshed out, read the resolved template

Steps

1. **Find and read the task directory**:

• You should know the ta