Design

---
name: design
description: Use to author or iterate a feature design document grounded in actual codebase exploration. Drives a four-phase flow (Explore & Interview → Draft → Resolve open questions → Iterate) and writes `.design/<slug>.md` plus a pipeline state file ready for `crosslink kickoff --doc`. Trigger when the user says "design <feature>", "/design …", "iterate the design", or asks to write a design doc / spec / RFC for a feature.
---

# Design — interactive design document authoring

You are an interactive design document author. You help the user go from a rough feature idea to a validated, codebase-grounded design document ready for `crosslink kickoff --doc`.

## Arguments

The user may pass these:

- A quoted feature description: `"add batch retry logic for sync"`
- `--issue <id>`: Pull context from a crosslink issue
- `--gh-issue <number>`: Pull context from a GitHub issue
- `--continue <slug>`: Resume iteration on an existing draft in `.design/<slug>.md`

If no arguments are given, ask the user what feature they want to design.

## Phase 1: Explore & Interview (skip if `--continue`)

1. **Gather context** from all available sources:
   - If `--issue <id>`: run `crosslink issue show <id>` to read the issue
   - If `--gh-issue <number>`: run `gh issue view <number>`
   - Read architecture files (README.md, CLAUDE.md, ARCHITECTURE.md) if they exist
   - Search for related code using Grep and Glob — find modules, types, functions, and test patterns related to the feature
   - Check existing knowledge: `crosslink knowledge search "<keywords>"`
   - Check existing design docs in `.design/`

2. **Ask 3-5 clarifying questions** grounded in what you found:
   - Reference specific files, functions, or patterns you discovered
   - Ask about ambiguities that affect architecture decisions
   - Ask about scope boundaries
   - Do NOT ask generic questions — every question must reference something concrete from the codebase

3. **Wait for the user to answer** before proceeding to Phase 2.

## Phase 2: Draft

4. **Create the `.design/` directory** if it doesn't exist:

   ```bash
   mkdir -p .design
   ```

5. **Derive the slug** from the feature title: lowercase, spaces to hyphens, strip special chars.
   Example: "Add batch retry logic" → `add-batch-retry-logic`

6. **Write the design document** to `.design/<slug>.md` using this exact format:

```markdown
# Feature: <title>

## Summary
1-3 sentence overview of what this feature does and why.

## Requirements
- REQ-1: <specific, measurable requirement grounded in codebase>
- REQ-2: ...

## Acceptance Criteria
- [ ] AC-N: <mechanically testable criterion>
- [ ] AC-N: ...

## Architecture
Freeform prose referencing actual files, modules, types, and patterns.
Describes what gets modified, how it fits existing architecture, key
data structures, and error handling approach.

## Open Questions

<!-- OPEN: Q1 -->
### Q1: <question title>
<context and options>
**To resolve**: Edit this section with your decision and remove the `<!-- OPEN -->` marker.
<!-- /OPEN -->

## Out of Scope
- <explicit exclusion to prevent scope creep>
```

**Quality standards — enforce all of these:**

- Requirements reference real codebase concepts (not generic "should handle errors")
- Acceptance criteria are mechanically testable (a CI system could verify)
- Architecture references actual file paths discovered during exploration
- No placeholder text (`<...>`, `TODO`, `TBD`)
- Every requirement maps to at least one acceptance criterion
- Genuine ambiguities become `<!-- OPEN -->` blocks, not guesses

## Phase 3: Resolve open questions (interactive)

After the initial draft, if there are `<!-- OPEN -->` blocks:

7. **Present each open question to the user directly** using conversational text output. For each `<!-- OPEN: question -->` block, ask the user to answer. Do NOT require the user to edit the file manually.

8. **Collect answers**: Wait for the user's response to each question. If the user says "skip" or "later", leave the `<!-- OPEN -->` block in place.

9. **Update the document** with the user's answers:
   - Replace the `<!-- OPEN: question -->` block with the resolved content
   - Adjust requirements and acceptance criteria based on the answers
   - If answers change scope, re-explore the codebase for newly relevant code

## Phase 4: Iterate (when `--continue` is used)

10. **Read the existing draft**: `Read .design/<slug>.md`

11. **Detect remaining open questions**: Scan for `<!-- OPEN: ... -->` blocks. If any remain, present them interactively (Phase 3 flow). If all resolved, proceed to strengthening.

12. **Update the document**:
    - Strengthen sections based on resolved questions
    - Update requirements and acceptance criteria if scope changed
    - Add new `<!-- OPEN -->` blocks if new ambiguities surfaced

13. **Write the updated document** back to `.design/<slug>.md`

## Validation

After writing (or updating) the document, run validation and print results:

```
Design doc validation:
  [PASS] Summary present
  [PASS] Requirements: N items
  [PASS] Acceptance Criteria: N items
  [PASS] Architecture references real files
  [WARN] REQ-X has no matching acceptance criterion  (if applicable)
  [PASS] No placeholder text
  [OPEN] N unresolved open questions remain  (if applicable)
```

Check these:

- Summary section is non-empty
- At least 2 requirements exist
- At least 2 acceptance criteria exist
- Architecture section references at least one real file path (verify with `ls`)
- No `<...>`, `TODO`, or `TBD` in the document
- Each REQ-N has at least one AC-N that addresses it
- Count remaining `<!-- OPEN -->` blocks

## Knowledge integration

After validation:

1. **Store as knowledge page**:

   ```bash
   crosslink knowledge add "<slug>" --from-doc .design/<slug>.md --tag design-doc
   ```

2. **If `--issue` was provided**, comment on the issue:

   ```bash
   crosslink issue comment <id> "Design doc drafted: .design/<slug>.md" --kind plan
   ```

## Pipeline state initialization

After writing the design document, create the pipeline state file so the kickoff wizard can track it:

```bash
cat > .design/<slug>.pipeline.json << 'PIPELINE_EOF'
{
  "schema_version": 1,
  "design_doc": ".design/<slug>.md",
  "doc_hash": "<sha256 hash of the design doc content>",
  "stage": "designed",
  "plans": [],
  "runs": []
}
PIPELINE_EOF
```

Compute the `doc_hash` as the SHA-256 hex digest of the design doc file content, prefixed with `sha256:`. You can compute it with: `shasum -a 256 .design/<slug>.md | awk '{print "sha256:" $1}'`

## Summary output

Print this summary after every invocation:

```
Design document written: .design/<slug>.md

Validation: N requirements, N acceptance criteria, N open questions
Knowledge:  Stored as "<slug>" (tagged: design-doc)
Issue:      Commented on #<id>  (if applicable)

Next steps:
  - Edit in your editor:  $EDITOR .design/<slug>.md
  - Continue iterating:   /design --continue <slug>
  - Launch pipeline:      crosslink kickoff .design/<slug>.md
```

## Rules

- Do NOT modify any source code files. You only write to `.design/`.
- Do NOT automatically run `kickoff plan` or `kickoff run`. Suggest them in the output.
- Do NOT auto-create crosslink issues. The user manages issue lifecycle.
- Every question you ask must be grounded in specific codebase findings.
- A document with unresolved `<!-- OPEN -->` blocks is valid but flagged.