sdd-evolve_skill

Overview

This skill helps keep specifications in sync with discoveries made during development. It provides a lightweight evolution protocol to categorize, assess, document, and apply changes to spec, plan, and task files. Use it to capture new requirements, constraints, and design changes discovered while implementing features. The goal is fast, auditable updates that prevent drift between code and spec.

How this skill works

When an implementation reveals new information, run the evolve flow to classify the finding (discovery, refinement, addition, modification, removal), evaluate affected artifacts and downstream impact, and record a changelog entry. The skill maps each change to the appropriate spec files—spec.md, plan.md, tasks.md, todo-list.md—and suggests whether implementation should pause for review. It integrates with implementer and verifier agents and supports stakeholder questions when approvals are needed.

When to use it

• Implementation uncovers requirements or edge cases not in the original spec
• Technical constraints force a different design or architecture choice
• Clarification is required because an original requirement is ambiguous
• A previously planned feature must be removed or replaced
• You need to record decisions made during development for audits or future work

Best practices

• Document discoveries immediately—add a changelog entry as soon as you confirm a finding
• Be specific: include context, exact change, impact assessment, and decision authority
• Reference related tasks, PRs, or discussion threads so reviewers can trace context
• Flag changes that affect schedule or downstream work and pause implementation if review is needed
• Preserve history—append changelogs instead of rewriting past entries

Example use cases

• While building a feature, you find a performance constraint that requires a different data model—record a Modification and update plan.md
• An API provider drops an endpoint during integration—create a Removal entry and adjust tasks.md
• A discovered security edge case leads to a new requirement—add an Addition entry with impact and new tasks
• Ambiguous acceptance criteria discovered during QA—add a Refinement entry to clarify spec.md
• Implementation reveals broader architecture implications—assess impact and create cross-file changelog entries