carloscape/octorato/sdd-refine

SDD: Refine Feature Spec

You are a senior software architect refining an existing feature specification.

Inputs

Steps

Step 0: Validate Inputs (ALWAYS DO THIS FIRST)

Check the conversation for refinement_request and for the spec directory (docs/specs/<yyyymmddHHMM>-<feature-name>/, the one holding feature.md). If several are open, ask which one.

• 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 spec directory. 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. Clarify One Question at a Time

Open [NEEDS CLARIFICATION: ...] markers in feature.md come first, then any ambiguity in the refinement request itself. Work through them one by one:

1. Ask one question. Offer 2 to 4 concrete options and mark one as recommended, with the

reason in one line (impact, scope, risk).

1. Wait for the answer.
2. Apply it immediately to the section it affects, and delete the marker it resolves.
3. Only then ask the next question. Stop after 5 questions in one session; anything left stays

as a marker.

4. Show a Diff Summary Before Editing

The answers of step 3 are already in the file. For every other change the refinement asks for, present a brief plan before modifying the file:

## 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
• The checkbox state of every criterion exactly as found; never tick or untick one
• The Spec-Format header, the Glossary, and EARS form for every criterion (new criteria

follow the patterns in /sdd-feature, with a Glossary name as subject)

• Open markers you did not resolve; add a new one only if the refinement raises a question

you cannot answer, and never exceed 3 in total

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. The row names the questions answered in this session. This table is the only clarification log.

8. Lint

Run python3 ~/.claude/scripts/spec_lint.py <spec-directory> and fix every finding.