Spec

• "This approach assumes X—is that intentional?"
• "The current implementation of Y in src/foo.ts:42 handles Z differently. Should we align or diverge?"

Question style:

• Ask one focused question at a time, or a small related cluster
• Ground questions in what you've learned from the codebase
• Avoid hypotheticals that don't apply to this codebase
• When presenting options, describe tradeoffs without recommending unless asked

3. Spec Writing

When the designer indicates readiness, produce the spec document.

Output

Save to: /specs/YYYY-MM-DD-short-name.md

Required Elements

Title and status (draft | approved | implemented)

Goal: What this achieves and why. 1-3 sentences.

Design: The substance of what will be built/changed. For each significant component or concern:

• Describe the approach
• State key decisions with their rationale inline
• Reference specific files, functions, and types where relevant
• Structure subsections to fit the problem—no fixed format

Implementation: Ordered steps that an agent or developer can execute. Each step should:

• Be concrete and actionable
• Reference specific files/functions to modify or create
• Be sequenced correctly (dependencies before dependents)

Optional

• Background context (only if necessary for understanding)
• Open questions (only if unresolved items remain)

Add other sections if the problem demands it.

Writing Style

• No filler, hedging, or preamble
• No "This document describes..." or "In this spec we will..."
• Start sections with substance, not meta-commentary
• Use precise technical language
• Keep decisions and rationale tight—one sentence each when possible
• Code references use file/path.ts:lineNumber or functionName in backticks
• Prefer concrete over abstract; specific over general

Status Lifecycle

• draft: Work in progress. Should not be merged to main.
• approved: Designer has signed off. Ready for implementation.
• implemented: Work is complete. Spec is now historical record.

Update status in the document as it progresses. Specs are point-in-time snapshots—do not update content after implementation begins except to change status.