| name | sdd-define |
| description | Phase 1 of the SDD workflow: capture and validate requirements in one pass. Owns the full Define methodology — classify the input (BRAINSTORM document, meeting notes, email thread, conversation, or direct request), extract entities (problem, users, MoSCoW goals, success criteria, acceptance tests, constraints, out of scope, assumptions), gather technical and data engineering context, calculate the clarity score against the 12/15 gate, fill gaps with targeted questions, and generate the DEFINE document from the shared template with correct status transitions. Use when the user wants to capture requirements, define the feature, structure project scope, or compute a clarity score — "capture requirements", "define the feature", "clarity score", "Phase 1", /define. Do not use for open-ended exploration of ideas and approaches (that is sdd-brainstorm, Phase 0) or for architecture and technical specification (that is sdd-design, Phase 2).
|
SDD Define — capture and validate requirements (Phase 1)
Transform unstructured input into validated, actionable requirements with explicit scope boundaries and measurable success criteria. This skill owns the Phase 1 methodology; the define-agent executes it and the /define command is its entrypoint.
Workflow position
Phase 0: /brainstorm → .claude/sdd/features/BRAINSTORM_{FEATURE}.md (optional)
Phase 1: /define → .claude/sdd/features/DEFINE_{FEATURE}.md (THIS SKILL)
Phase 2: /design → .claude/sdd/features/DESIGN_{FEATURE}.md
Phase 3: /build → Code + .claude/sdd/reports/BUILD_REPORT_{FEATURE}.md
Phase 4: /ship → .claude/sdd/archive/{FEATURE}/SHIPPED_{DATE}.md
Define combines what used to be Intake + PRD + Refine into a single, iterative phase. When fed a BRAINSTORM document, extraction is streamlined because discovery questions are already answered, approaches have been evaluated, YAGNI has been applied, and the user has validated the direction.
Knowledge architecture
Follow KB-first resolution — it is mandatory, not optional, because the Design phase depends on the KB domains selected here.
┌─────────────────────────────────────────────────────────────────────┐
│ KNOWLEDGE RESOLUTION ORDER │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. KB DISCOVERY (identify applicable domains) │
│ └─ Read: .claude/kb/_index.yaml → List available domains │
│ └─ Match requirements to available KB domains │
│ └─ Document selected domains in DEFINE output │
│ │
│ 2. TEMPLATE LOADING (ensure consistent structure) │
│ └─ Read: .claude/sdd/templates/DEFINE_TEMPLATE.md │
│ └─ Read: .claude/CLAUDE.md → Project context │
│ │
│ 3. CONFIDENCE ASSIGNMENT │
│ ├─ All entities extracted clearly → 0.95 → Proceed │
│ ├─ Some gaps, clarification needed → 0.80 → Ask questions │
│ └─ Major ambiguity, unclear scope → 0.60 → Block, clarify │
│ │
└─────────────────────────────────────────────────────────────────────┘
Clarity score thresholds
| Score | Status | Action |
|---|
| 12-15/15 | HIGH | Proceed to /design |
| 9-11/15 | MEDIUM | Ask targeted questions |
| 0-8/15 | LOW | Cannot proceed, clarify |
Process
Step 1: Load Context
Read(.claude/sdd/templates/DEFINE_TEMPLATE.md)
Read(CLAUDE.md)
# If file provided:
Read(<input-file>)
Step 2: Classify Input
Identify the input type to guide extraction:
| Input Type | Pattern | Focus |
|---|
brainstorm_document | BRAINSTORM_*.md from /brainstorm | Pre-validated, extract directly |
meeting_notes | Bullet points, action items | Decisions, requirements |
email_thread | Re:, Fwd:, signatures | Requests, constraints |
conversation | Informal language | Core problem, users |
direct_requirement | Structured request | All elements present |
mixed_sources | Multiple formats | Consolidate, deduplicate |
Step 3: Extract Entities
Pull structured data from the input using these patterns:
| Entity | Look For |
|---|
| Problem | "We're struggling with...", "The issue is...", "Pain point:" |
| Users | "For the team...", "Customers want...", "Users need..." |
| Goals | "We need to...", "Must have...", "Should have..." |
| Success Criteria | "Success means...", "We'll know when...", "Measured by..." |
| Acceptance Tests | "Given/When/Then", "Test case:", "Scenario:" |
| Constraints | "Must work with...", "Can't change...", "Limited by..." |
| Out of Scope | "Not including...", "Deferred to...", "Excluded:" |
| Assumptions | "Assuming that...", "We expect...", "If X then...", "Depends on..." |
Classify every goal with MoSCoW priority:
| Priority | Meaning |
|---|
| MUST | MVP fails without this (non-negotiable) |
| SHOULD | Important, but a workaround exists |
| COULD | Nice-to-have, cut first if timeline is tight |
Formalize assumptions into a trackable risk register (ID, statement, impact if wrong, validated checkbox). BRAINSTORM captures exploratory assumptions; DEFINE turns them into trackable risks.
Step 4: Gather Technical Context
Ask three questions (skip any the input already answers):
- Where should this live? (src/, functions/, deploy/)
- Which KB domains apply? (list available from .claude/kb/)
- Does this need infrastructure changes?
Why these three:
- Location → Prevents misplaced files
- KB Domains → Design phase pulls correct patterns
- IaC Impact → Catches infrastructure needs early
Step 5: Extract Data Engineering Context (when triggered)
Trigger: the requirements mention data pipelines, ETL, analytics, warehouses, data quality, schemas, or data sources.
| Entity | Look For |
|---|
| Source Systems | "from Postgres...", "Kafka topic...", "S3 bucket...", "API endpoint..." |
| Volumes | "~1M rows/day", "500GB total", "10K events/sec" |
| Freshness SLAs | "within 15 minutes", "daily by 6am UTC", "real-time" |
| Completeness Metrics | "99.9% of records", "no nulls in PK", "all sources present" |
| Schema Contracts | "order_id is INT", "status ENUM", "amount DECIMAL(18,2)" |
| Source Inventory | "3 Postgres tables + 1 Kafka topic + S3 clickstream" |
Record the findings in the DEFINE document's "Data Contract (if applicable)" section — source inventory, schema contract, freshness SLAs, completeness metrics, lineage requirements. The section's shape lives in the template; do not invent a parallel format.
Step 6: Calculate Clarity Score
Score each element 0-3 points:
| Element | Score | Meaning |
|---|
| Problem | 0-3 | Clear, specific, actionable |
| Users | 0-3 | Identified with pain points |
| Goals | 0-3 | Measurable outcomes |
| Success | 0-3 | Testable criteria |
| Scope | 0-3 | Explicit boundaries |
Scoring guide:
- 0 = Missing entirely
- 1 = Vague or incomplete
- 2 = Clear but missing details
- 3 = Crystal clear, actionable
Total: 15 points. Minimum to proceed: 12/15 (80%). Record the per-element breakdown with notes in the document's Clarity Score Breakdown section.
Step 7: Fill Gaps (if score < 12)
Use AskUserQuestion with specific options, targeting the lowest-scoring elements first:
Example questions:
- "Who is the primary user: (a) internal team, (b) customers, (c) both?"
- "What's the timeline: (a) this sprint, (b) this quarter, (c) no deadline?"
Re-score after each round of answers. Never pad entities to reach the gate — a fabricated requirement is worse than an honest "Needs Clarification".
Step 8: Generate Document
Write the structured document following the template, then save:
Write(.claude/sdd/features/DEFINE_{FEATURE_NAME}.md)
Then update statuses (see Status transitions) and hand off (see Handoff).
Output obligations
| Obligation | Value |
|---|
| File | .claude/sdd/features/DEFINE_{FEATURE_NAME}.md |
| Feature name | SCREAMING_SNAKE_CASE (e.g., USER_NOTIFICATIONS) |
| Structure | .claude/sdd/templates/DEFINE_TEMPLATE.md — the template owns the document format; follow it rather than re-creating sections here |
| Status values | Draft, In Progress, Needs Clarification, Ready for Design |
Required sections (per WORKFLOW_CONTRACTS.yaml): metadata, problem statement, target users, goals (MoSCoW), success criteria, acceptance tests, out of scope, constraints, assumptions, clarity score breakdown, open questions, revision history.
Status transitions
Completing Define carries two status obligations, per .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml (status_transitions and update_rules). Skipping them leaves stale "Ready for X" statuses that break the workflow.
- Own document: set the DEFINE document's
Status field to Ready for Design when clarity >= 12/15, or Needs Clarification when below the gate.
- Upstream document: when the input was a BRAINSTORM document, edit
BRAINSTORM_{FEATURE}.md and set its Status field to ✅ Complete (Defined).
Quality gate
Before generating the DEFINE document:
PRE-FLIGHT CHECK
├─ [ ] Problem statement is one clear sentence
├─ [ ] At least one user persona with pain point
├─ [ ] Goals have MoSCoW priority (MUST/SHOULD/COULD)
├─ [ ] Success criteria are measurable (numbers, %)
├─ [ ] Acceptance tests are testable
├─ [ ] Out of scope is explicit (not empty)
├─ [ ] Assumptions documented with impact if wrong
├─ [ ] KB domains identified for Design phase
├─ [ ] Technical context gathered (location, IaC impact)
└─ [ ] Clarity score >= 12/15
The clarity gate is hard: below 12/15 the phase does not complete — ask, iterate, or mark the document Needs Clarification and state what is missing.
Contract gate
Before handing off to /design, validate the document just written against this phase's contract — artifact DEFINE_{FEATURE_NAME}.md, phase define:
tools/spec-linter/spec-lint .claude/sdd/features/DEFINE_{FEATURE_NAME}.md --phase define \
--contracts-file .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml
Run it as tools/spec-linter/USAGE.md documents, and act on the verdict exactly as defined there. The exit-code contract and verdict semantics are owned by that document and by the contract_enforcement block (exit_code_contract, verdict_semantics) of .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml — which is also where this phase's binding is declared. Read them there rather than assuming: a contract assigns the severity of its own rules, so never reinterpret a verdict, and never assume one the linter did not return.
Anti-patterns
| Never Do | Why | Instead |
|---|
| Vague language ("improve", "better") | Unmeasurable | Use specific metrics |
| Skip clarity scoring | Proceed with gaps | Always calculate score |
| Assume implementation details | That's DESIGN phase | Keep requirements-focused |
| Empty out-of-scope | Scope creep risk | Explicitly list exclusions |
| Skip KB domain selection | Design lacks patterns | Always identify domains |
| No identified users | Requirements without an audience | Name at least one persona with a pain point |
| Untestable success criteria | Cannot verify done | Rewrite until measurable |
Tips
- Be Specific — "Improve performance" → "Reduce API latency to <200ms"
- Use Numbers — "Handle many users" → "Support 1000 concurrent users"
- Test Criteria — If you can't test it, it's not clear enough
- Scope Ruthlessly — What's OUT is as important as what's IN
Handoff
Once the DEFINE document is saved with clarity >= 12/15 and statuses are updated, suggest the next phase:
/design .claude/sdd/features/DEFINE_{FEATURE_NAME}.md
Design (Phase 2, design-agent) turns the validated requirements into architecture and a technical specification.
