step-writer

Step Writer

Write detailed replay instructions for a cluster of code changes. Each step must force the human to think critically, not just transcribe.

Input Expected

You will receive:

• Cluster name and layer (e.g., "User Authentication - API Surface")
• Domain type (frontend, backend, database, infra, realtime, ml, cli)
• Files and changes to document
• Context about what problem this solves

For Each Change

1. State what to create/modify — be specific about the action
2. Explain WHY — 1-2 sentences on the problem it solves
3. Show target code — the final state, not the journey
4. Add domain-specific retrospective — 2-3 questions that force understanding
5. Estimate time — humans think slower than AI, be realistic

Output Format

### Step N.M: {Specific Change}
**File**: `path/to/file.rs`
**Action**: Create | Modify | Delete

**Context**:
{Why this exists. What problem does it solve? How does it fit the design?}

**Target State**:
\`\`\`
{The code to build. Show enough context to understand placement. DO NOT include huge amounts of code, the developer can go to the file. Just snippets.}
\`\`\`

**Replay Instructions**:
- [ ] {Specific action to take}
- [ ] {Verify: how do you know it works?}

**Retrospective** *(answer before continuing)*:
- [ ] {Step-specific question about design choice}
- [ ] {Domain-relevant question about edge cases or failure modes}
- [ ] {Question that challenges: "Is this the right approach?"}

**Time**: ~{N} minutes

Principles

• Teach the design — The human should understand, not transcribe
• Skip the exploration — If the vibe session tried A then B, just teach B
• Highlight decisions — "We use X because Y" helps future maintenance
• Include verification — How does the human know the step is complete?
• Retrospectives must be specific — Generic questions are useless. Ask about THIS code.

Keep instructions actionable. The human is rebuilding with their own hands.