agentleFS
luanmorenommacielluanmorenommaciel/agentspec/.claude/skills/sdd-iterate/SKILL.md

sdd-iterate

Skill256 starsChanged 2 months agoMITView on GitHub

Update an existing SDD phase document (BRAINSTORM/DEFINE/DESIGN) mid-stream with full cascade awareness: classify the change (additive, modifying, removing, architectural), apply it with a version bump and change note, walk the cascade rules for downstream impact, and confirm with the user before applying any cascading edits. Owns the SDD change-management methodology: cascade rules, version-tracking and status-field obligations, and the iterate-vs-restart thresholds. Use when the user wants to update the requirements or design mid-stream — "requirements changed", "the design needs to change", "cascade the change" — or any existing phase document must change after downstream work has started. Do not use for a brand-new feature or a fundamentally different problem: a different problem, different users, or a change beyond roughly half the document calls for sdd-brainstorm/sdd-define instead of an iterate.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never apply cascading edits silently.

    line 126
  2. Distinctive:

    Every applied change is tracked.

    line 145
  3. Distinctive:

    Add a change note with date, author, and reasoning.

    line 148
  4. Very specific:

    Status fields: document Status values are set by phase completions per status_transitions.update_rules in WORKFLOW_CONTRACTS (for example, …

    line 164
  5. Distinctive:

    Verify before reporting completion:

    line 172

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

SDD Iterate — Mid-Stream Change Management

Requirements change mid-stream; that is normal. This skill owns the methodology for updating any SDD phase document without breaking the chain: classify the change, apply it with version tracking, analyze downstream cascades, and propagate updates only after user confirmation.

Executor: iterate-agent. Entrypoint: /iterate <file> "<change-description>". Contract: the iterate block in .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml owns the command surface, the works_with chain, and the thresholds; per that block's skill entry, this skill owns the rules below.

Document Relationships

/iterate works on the document phases of the SDD workflow:

Phase 0: /brainstorm → BRAINSTORM_{FEATURE}.md ← /iterate can update
Phase 1: /define     → DEFINE_{FEATURE}.md     ← /iterate can update
Phase 2: /design     → DESIGN_{FEATURE}.md     ← /iterate can update
Phase 3: /build      → (code)                  ← update DESIGN, then /build
Phase 4: /ship       → (archive)               ← N/A

Changes ripple downstream:

BRAINSTORM ────► DEFINE ────► DESIGN ────► CODE
     │              │            │           │
     ▼              ▼            ▼           ▼
  Changes      May need      May need     May need
  here         update        update       rebuild
Change InCascades ToExample
BRAINSTORMDEFINENew YAGNI items → update out-of-scope
DEFINEDESIGNNew requirement → add component
DESIGNCODENew file in manifest → create via /build; removed file → delete

To change code during Phase 3, update the DESIGN document first — the cascade to code triggers a rebuild via /build. Editing code directly breaks traceability.

Process

Six steps, in order:

  1. Load Target Document — read the target file and identify the phase by file pattern (BRAINSTORM_*.md → Phase 0, DEFINE_*.md → Phase 1, DESIGN_*.md → Phase 2). Read the downstream documents that exist. Never classify a change before loading current state.
  2. Analyze Change — classify the change type and assess impact (Change Classification).
  3. Apply Changes — make the modification, bump the version, add a change note (Version Tracking).
  4. Assess Cascade Need — walk the cascade rules for each downstream document (Cascade Analysis).
  5. Execute Cascade — when a cascade is needed, confirm with the user first (User Confirmation Before Cascading), then apply.
  6. Save Updates — write the updated target document, plus downstream documents when the user confirmed a cascade.

Change Classification

Classify every change before touching the document:

TypeMarkerImpactExample
Additive+Low — adds to existing scope"Also support PDF"
Modifying~Medium — changes existing scope"Change from X to Y"
Removing−Medium — reduces scope"Remove feature Z"
Architectural!High — fundamental approach change"Use a different pattern entirely"

Confidence assignment drives how to proceed:

SituationConfidenceAction
Additive change, no cascade0.95Apply directly
Modifying change, cascade needed0.85Ask user
Removing change, cascade needed0.80Ask user
Architectural change0.70Full review with user

Cascade Analysis

For each downstream document: check whether the change affects it, calculate the required updates, and present options to the user before applying anything downstream.

BRAINSTORM → DEFINE:

BRAINSTORM ChangeDEFINE Impact
Changed approachMay need different problem focus
New YAGNI itemsOut of scope needs update
Changed usersTarget users section needs update
Changed constraintsConstraints section needs update
New discovery answersMay affect requirements

DEFINE → DESIGN:

DEFINE ChangeDESIGN Impact
New requirementMay need new component
Changed success criteriaMay need different approach
Scope expansionNeeds new sections
Scope reductionCan simplify
New constraintMust be accommodated

DESIGN → CODE:

DESIGN ChangeCODE Impact
New file in manifestCreate file
Removed fileDelete file
Changed patternUpdate affected files
New decisionMay need refactor
Architecture changeSignificant refactor

Code-level cascades are never hand-applied: the DESIGN update is the deliverable here, and the rebuild routes through /build (escalation to build-agent).

User Confirmation Before Cascading

Never apply cascading edits silently. When a cascade is needed, ask the user:

"This change to {DOCUMENT} affects {DOWNSTREAM}. Options:
(a) Update {DOWNSTREAM} automatically to match
(b) Just update {DOCUMENT}, I'll handle {DOWNSTREAM} manually
(c) Show me what would change first"
  • (a) — apply the downstream updates, with a version bump and change note in every touched document.
  • (b) — update only the target; record in its change note that downstream documents are now pending manual updates.
  • (c) — present a preview of the downstream changes, then re-offer (a) and (b).

Architectural changes always get a full review with the user before anything is written.

Version Tracking

Every applied change is tracked. Obligations:

  1. Bump the version in the document's Revision History.
  2. Add a change note with date, author, and reasoning.
  3. Repeat the bump + note in every downstream document updated by a cascade.

Fields: version, date, author, changes. The section shape is owned by the templates (.claude/sdd/templates/DEFINE_TEMPLATE.md, DESIGN_TEMPLATE.md):

## Revision History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2026-01-25 | define-agent | Initial version |
| 1.1 | 2026-01-25 | iterate-agent | Added PDF support |
| 1.2 | 2026-01-26 | iterate-agent | Removed OCR (out of scope) |

Status fields: document Status values are set by phase completions per status_transitions.update_rules in WORKFLOW_CONTRACTS (for example, /design completing marks DEFINE "✅ Complete (Designed)"). A mid-stream change can invalidate that claim — after updating a document whose downstream phase already completed, verify the Status fields still tell the truth, and surface any mismatch in the cascade prompt instead of silently rewriting the flow.

Quality Gate

Verify before reporting completion:

PRE-FLIGHT CHECK
├─ [ ] Target document loaded
├─ [ ] Change classified (additive/modifying/removing/architectural)
├─ [ ] Downstream documents identified
├─ [ ] Cascade impact assessed
├─ [ ] User informed of cascade requirements
├─ [ ] Version bumped in revision history
├─ [ ] Change note added with reasoning
└─ [ ] Downstream updates applied (if cascaded and confirmed)

Contract Gate

Iterate has no contract of its own: after applying the edit, validate the edited document against the contract for its own phase. The artifact is whatever document you just edited, and the --phase is the phase that produced it (define for a DEFINE document, design for a DESIGN document) — repeat this for each document a cascade touched:

# --phase must match the document being validated, not the phase you came from
tools/spec-linter/spec-lint <EDITED_DOC.md> --phase <define|design> \
  --contracts-file .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml

Which phases carry a contract is decided by required_sections in .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml, not by this skill — if the edited document's phase has none, the linter reports that itself; act on what it returns. Run it as tools/spec-linter/USAGE.md documents, and act on the verdict exactly as defined there. The exit-code contract and verdict semantics are owned by that document and by the contract_enforcement block (exit_code_contract, verdict_semantics) of the same contract file — which is also where this binding is declared. Read them there rather than assuming: a contract assigns the severity of its own rules, so never reinterpret a verdict, and never assume one the linter did not return.

Anti-Patterns

Never DoWhyInstead
Skip cascade analysisInconsistent documentsAlways check downstream
Update without versioningLost historyAlways bump version
Apply cascading edits without confirmationUser loses control of scopeAsk with the (a)/(b)/(c) prompt
Apply architectural changes silentlyMajor impactFull review with user
Ignore downstream conflictsBroken workflowResolve conflicts first
Edit CODE directlyBreaks traceabilityUpdate DESIGN, rebuild via /build

When to Use /iterate vs a New /define

Thresholds (contract: iterate.thresholds):

SituationAction
< 30% change/iterate
Add/modify features/iterate
Change constraints/iterate
> 50% differentNew /define
Different problem entirelyNew /define
Different target usersNew /define
Fundamental approach changeNew /define

An architectural change classified in-flow (0.70 confidence) triggers a full review — that review decides between an in-place update and a fresh /define.

Tips

  1. Iterate early — catch changes before coding starts.
  2. Be specific — "Add X" beats "make it better".
  3. Check cascade — changes ripple downstream.
  4. Keep history — version tracking shows evolution.
  5. Don't fight it — requirements change; that is normal.

References

  • Contract: .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml (iterate block: command surface, works_with chain, thresholds; status_transitions.update_rules for Status fields; contract_enforcement for the binding, exit-code contract, and verdict semantics)
  • Contract gate runner: tools/spec-linter/USAGE.md
  • Templates: .claude/sdd/templates/DEFINE_TEMPLATE.md, .claude/sdd/templates/DESIGN_TEMPLATE.md (Revision History shape)
  • Executor: .claude/agents/workflow/iterate-agent.md
  • Entrypoint: .claude/commands/workflow/iterate.md

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.