sdd-evolve
Skill198 starsChanged 5 months agoMITView on GitHub
Update specifications with discoveries made during development. Use when implementation reveals new requirements, constraints, or design changes.
In this repository6 other files it gives its agents.
- .cursor/rules/sdd-system.mdcCursor rule
- sdd-auditSkill
- sdd-implementationSkill
- sdd-memorySkill
- sdd-planningSkill
- sdd-researchSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Keep specifications in sync with implementation discoveries.
- Distinctive: line 30
Should implementation pause for review?
- Distinctive: line 70
Use the ask question tool if change requires stakeholder input
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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-implementersubagent work - Triggered by
/evolvecommand - Feeds into future
/auditruns - Use the ask question tool if change requires stakeholder input
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.