design

Parse the user's input:

• First argument is the task name (matches the docs directory, e.g., offline-sync)

Phase 1 — Gather existing context

Look for prior work in docs/{task-name}/:

• facts.md — codebase implementation facts (from /facts)
• questions.md — generated questions (from /questions)
• research.md — research findings (from /research)

Read every file that exists. If none exist, tell the user: "No prior research found in docs/{task-name}/. You can run /facts, /questions, and /research first, or we can start from scratch — just tell me what you're thinking."

Also check if docs/{task-name}/design.md already exists. If it does, this is a resume — read it and skip to Phase 3.

Phase 2 — Start the conversation

Do NOT generate a full document before talking. Instead:

1. Summarize what you understand so far from the gathered context — a few sentences, not a wall of text.
2. Say what you think the hardest or most interesting part is.
3. Ask the user what they're thinking. What's the goal? What's bugging them? What have they already ruled out?

Once the conversation gets going and things start to take shape, create docs/{task-name}/design.md with whatever sections are relevant. The format below is a starting point — skip sections that don't apply, add sections that do.

# Design: {Task Name}

## Where we are

*What exists today and why it matters for this work.*

{The relevant parts of the system as they are now. Not a full inventory — just what you need to understand to talk about the change.}

## Where we want to be

*What's different when this is done.*

{What changes for the user, the system, or both. What stays the same.}

## How we get there

*The rough approach. What happens first, what's tricky, what patterns to follow or break.*

{Implementation direction, not a step-by-step plan. That's what /structure is for.}

## Still figuring out

*Things we haven't resolved yet.*

{Just the questions that actually matter for the design. Not an exhaustive list.}

- {question} — {why it matters}

## What we decided

*Decisions we made and why. Captured as we go.*

{Each decision is a short paragraph: what we chose, why, and what we considered instead. No tables — just write it out.}

**{Decision topic}**: {What we decided}. We went with this because {reason}. We also considered {alternative} but {why not}.

Don't force all sections to exist from the start. "What we decided" starts empty. "Still figuring out" might be the only section after the first pass. That's fine — the document grows as the conversation progresses.

Phase 3 — Keep talking

If resuming an existing document, read it, then:

• Summarize where we left off
• Pick up the most important unresolved thing
• Ask the user if that's still the right thread or if something changed

During the conversation:

• Think out loud. Propose rough ideas, say when you're unsure. "I think X because Y, but I'm not confident about Z" is better than presenting everything as settled.
• Update the doc periodically — not after every single exchange, but when a meaningful chunk of the conversation has landed. Batch a few related decisions together.
• When the user answers a question, capture it under "What we decided" and remove it from "Still figuring out."
• If something needs more research, say so and suggest /facts or /research for that specific gap rather than guessing.

Conversation guidelines

• Lead with what you know, not what you don't. Share your understanding first, then ask questions.
• Be direct about what you think, but hold it loosely. "I'd lean toward X" is better than "What do you want to do?"
• Push back when something seems off. "That could work, but have you thought about {consequence}?" is useful.
• When you don't know, say so. Don't fill gaps with generic advice.
• Add sections as needed (e.g., "Migration concerns", "Performance budget", "What we're deliberately not doing"). The template is a starting point.
• The document is shared notes from our conversation, not a formal deliverable. It should read like something you'd hand to a teammate to get them up to speed, not a design review artifact.

When the user is done

The user may say they're done, or the conversation may naturally wind down. At that point:

• Skim the document for anything we discussed but didn't capture
• Flag anything still under "Still figuring out" that could bite us during implementation

Then, before the design is ready for /structure, run a consistency check (do not skip it — a design that contradicts itself or the codebase poisons every step downstream):

• Internal — re-read the doc end to end. Do "What we decided" items contradict each other or "How we get there"? Is anything left in "Still figuring out" actually a blocker for structure (resolve it or call it out)? Does the design conflict with facts.md / research.md, a wiki/decisions/ entry, or docs/objective.md?
• Against the codebase — Glob/Grep the files, types, and components the design says it builds on or touches; if reality differs, fix the design to match. (Greenfield → confirm nothing it assumes already exists actually conflicts.)
• Fix what you find; surface anything you can't resolve rather than papering over it.

The document at docs/{task-name}/design.md feeds into /structure once this check passes.