Iterate

The /iterate command works with document phases of the AgentSpec 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

Use /iterate when you discover something that needs to change mid-stream.

Important: To change code during Phase 3, update the DESIGN document first. The cascade to code triggers a rebuild via /build. This ensures traceability.

What This Command Does

1. Detect Phase - Identify which phase document is being updated
2. Analyze Impact - Determine downstream effects
3. Update Document - Apply changes with version tracking
4. Cascade - Propagate changes to downstream documents if needed

Process

Step 1: Load Target Document

Read(<target-file>)

# Identify document type:
# - BRAINSTORM_*.md → Phase 0
# - DEFINE_*.md → Phase 1
# - DESIGN_*.md → Phase 2

Step 2: Analyze Change

Determine the change type:

Step 3: Apply Changes

Update the document with:

1. Change Applied - The actual modification
2. Version Bump - Increment version in revision history
3. Change Note - What changed and why

Step 4: Assess Cascade Need

Determine if downstream documents need updates based on cascade rules.

Step 5: Execute Cascade (if needed)

If cascade needed, prompt user:

"This DEFINE change affects the DESIGN. Options:
(a) Update DESIGN automatically to match
(b) Just update DEFINE, I'll handle DESIGN manually
(c) Show me what would change first"

Step 6: Save Updates

Write(<target-file>)
# If cascade:
Write(<downstream-document>)

Output

Cascade Rules

DEFINE Changes → DESIGN Impact

DESIGN Changes → Code Impact

Version Tracking

Each document maintains revision history:

## 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 per user request |

Tips

1. Iterate Early - Catch changes before coding starts
2. Be Specific - "Add X" is better than "make it better"
3. Check Cascade - Changes ripple downstream
4. Keep History - Version tracking shows evolution
5. Don't Fight It - Requirements change, that's normal

When to Use /iterate vs Starting Over

References

• Agent: .claude/agents/workflow/iterate-agent.md
• Contracts: .claude/sdd/architecture/WORKFLOW_CONTRACTS.yaml