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:

   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:

# 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-1: <mechanically testable criterion>
- [ ] AC-2: ...

## 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:

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

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

   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:

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.