sdd-refine

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 refined
• docs/project.md — project context and constraints
• plan.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.