| name | sdd-refine |
| description | SDD step 2 (optional, repeatable). Read an existing feature.md and refine it by updating or enhancing requirements based on user input. Use when requirements have changed, new edge cases are discovered, or the spec needs clarification before planning or re-planning. Run before /sdd-plan if plan.md already exists.
|
| argument-hint | <what to change or enhance (optional)> |
SDD: Refine Feature Spec
You are a senior software architect refining an existing feature specification.
Inputs
| Input | Required | Description | Example |
|---|
refinement_request | Optional | What to change or add to the spec | "Add rate limiting — max 5 login attempts per minute" |
Steps
Step 0: Validate Inputs (ALWAYS DO THIS FIRST)
Check the conversation for refinement_request and for feature.md in the project root.
- If
feature.md does not exist → stop and tell the user to run /sdd-feature first.
- If
refinement_request is present → proceed to Step 1.
- If
refinement_request is missing → ask:
"What would you like to change or add to the spec? Is this a scope change, a clarification, or new edge cases?"
Do NOT proceed until the user provides it.
Pre-conditions
Verify feature.md exists in the project root.
If it does not exist, tell the user to run /sdd-feature first.
1. Read Current State
Read these files before doing anything:
feature.md — the existing spec to be refineddocs/project.md — project context and constraintsplan.md — if it exists, note which parts of the plan may be invalidated by changes
2. Understand the Refinement Request
The refinement input is: refinement_request (collected in Step 0).
Analyse refinement_request against the current feature.md and identify:
- What sections are affected
- Whether the change expands scope, reduces scope, or clarifies existing scope
- Any knock-on effects (e.g., changing a requirement may invalidate other ACs)
3. Ask Clarifying Questions if Needed
If the refinement request is ambiguous or incomplete, ask targeted questions before editing.
Keep questions to 3 or fewer. Wait for answers.
4. Show a Diff Summary Before Editing
Before modifying the file, present a brief plan of changes:
## Proposed Changes to feature.md
### Additions
- FR-04: <new requirement>
- AC-05: <new acceptance criterion>
### Modifications
- FR-02: Updated to clarify that X also applies to Y
- AC-02: Strengthened — must complete within 200ms, not 500ms
### Removals
- FR-03: Removed — out of scope per user confirmation
### No Change
- All other sections remain as-is
Ask the user to confirm before applying.
5. Apply the Refinements
Update feature.md in place. Preserve:
- Existing section structure and numbering where possible
- Completed checkboxes on ACs if any exist
- The
## Open Questions section — resolve any questions answered by this refinement,
and add new ones if this refinement raises them
Increment requirement IDs sequentially (do not reuse deleted IDs).
6. Impact Assessment
After updating feature.md, check if plan.md exists.
If it does, analyse the impact:
## Impact on plan.md
plan.md exists and may be partially invalidated. Here is what needs revisiting:
- Step 2 (Domain Layer): FR-04 adds a new value object not currently planned
- Step 6 (Tests): 2 new ACs require additional test cases
- Step 3 is unaffected
Recommendation: Run /sdd-plan again to regenerate the plan before implementing.
If plan.md does not exist, simply confirm the spec is updated and prompt the user to run /sdd-plan.
7. Changelog Entry
Append a refinement record at the bottom of feature.md:
---
## Revision History
| Date | Change Summary |
|------|----------------|
| <date> | Initial spec |
| <date> | <One-line summary of this refinement> |
If a revision history table already exists, append a new row — do not recreate the table.
