Write Specs Skill

Prerequisites

STOP. Have you run analyze-context?

1. Check for planning/context-brief.md.
2. If missing: ABORT. Run analyze-context first.
3. If present: Read it. You MUST use the "Reference Pattern" listed there as your guide.

Use this skill after the story description and acceptance criteria are available (from a bead via bd show, a story.md file, or the user's prompt) AND after analyze-context has generated planning/context-brief.md.

Inputs

• Story description and acceptance criteria (required) — from a bead (bd show), a story.md file, or the user's prompt
• planning/context-brief.md (required; the research)

Outputs (created/updated in the same story folder)

• spec.md
• design.md
• edge-cases.md
• planning/requirements.md
• Ensure directories from config ensureDirs exist (defaults include planning/, planning/visuals/, implementation/, verification/).

Workflow

1. Load Context: Read the planning/context-brief.md.
2. Verify Patterns: Open the "Reference Pattern" file found in the brief. Your design.md must mimic its structure.
3. Generate Artifacts: Use the templates in this folder.

Templates (authoritative)

• Template filenames are defined in config.json under templates (defaults map to spec/design/edge-cases/requirements templates in this folder).
• The "Reference Pattern" from context-brief.md governs the architectural approach in design.md.

Configuration

• Defaults live in config.json. Adjust template filenames (templates), required inputs, and ensureDirs when porting to other repositories.

Behavior Rules

• Citation Required: Every design decision in design.md must cite the Reference Pattern or an Instruction.
• No Novelty: Do not invent new architectural patterns. Copy the reference.
• Visuals: Do not generate images. Create planning/visuals/ directory only.
• Keep scope tight to the story acceptance criteria and existing repo architecture.
• Ask concise, numbered clarifying questions before writing if required details are missing.
• Treat this as greenfield with zero active users: avoid backward-compat shims, migration scaffolding, feature flags, or defensive toggles unless explicitly requested.
• Do not create tasks.md in this skill.