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 changelogs

• references/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