| name | sdd-evolve |
| description | Update specifications with discoveries made during development. Use when implementation reveals new requirements, constraints, or design changes. |
SDD Evolve Skill
Keep specifications in sync with implementation discoveries.
When to Use
- Implementation reveals new requirements
- Technical constraints discovered during development
- Design changes needed based on learnings
- Edge cases found not in original spec
Protocol
Step 1: Categorize the Discovery
- Discovery: New information that was unknown
- Refinement: Clarification of existing requirement
- Addition: New requirement not in original scope
- Modification: Change to existing requirement
- Removal: Requirement no longer needed
Step 2: Assess Impact
- Which spec files are affected?
- Does this change the plan?
- Are there downstream impacts?
- Should implementation pause for review?
Step 3: Document the Change
## Changelog
### [Date] - [Category]: [Brief Description]
**Context**: [Why this change is needed]
**Change**: [What specifically changed]
**Impact**: [How this affects existing work]
**Decision**: [What was decided]
Step 4: Update Specs
Modify the appropriate files: spec.md, plan.md, tasks.md, todo-list.md.
Best Practices
- Document immediately — don't wait until end of implementation
- Be specific — include enough detail to understand later
- Link to context — reference related tasks
- Assess impact — flag if review is needed
- Preserve history — never delete, always add changelog
- Propagate downstream — mark stale docs when upstream spec changes
References
references/changelog-format.md — Standard changelog formats for briefs, specs, and standalone changelogsreferences/propagation-guide.md — How to detect and flag stale downstream documents when a spec changes
Scripts
scripts/check-staleness.sh <task-id> — Compare spec modification dates against plan, tasks, and todo-list
Integration
- Called during
sdd-implementer subagent work
- Triggered by
/evolve command
- Feeds into future
/audit runs
- Use the ask question tool if change requires stakeholder input
