Write Guide

Write Guide

Generate a comprehensive GUIDE.md for a milestone by analyzing stories, git history, and project setup.

Usage

/write-guide [milestone-name]

Arguments

• milestone-name — Optional. Name of the milestone directory under docs/planning/milestones/. If omitted, present available milestones for selection.

Workflow

Step 1 — Discover Milestones

"🔍 Checking what milestones are available..."

List directories under docs/planning/milestones/:

ls -d docs/planning/milestones/*/

• Skip _orphan and similar utility directories
• If no argument provided, present options to user via AskUserQuestion
• If argument provided, validate the directory exists

Step 2 — Inventory Milestone Artifacts

"📂 Inventorying the milestone folder — stories, progress, gaps..."

Read the milestone directory contents:

ls -la docs/planning/milestones/{milestone-name}/

Look for:

• stories/ directory (primary story source)
• tasks/ directory
• PROGRESS.md (session notes)
• subtasks.json (Ralph build queue)
• gaps-to-implement.md (known gaps between stories and implementation)
• GUIDE.md or step-by-step.md (existing guide)

If GUIDE.md already exists: Warn the user and ask before overwriting. Offer to update in-place or regenerate from scratch.

Preserve existing Validation Progress on regeneration: if the existing GUIDE.md contains a ## Validation Progress section, capture its exact content verbatim before any regeneration. Re-emit it unchanged in the new guide — it represents real validation state the user has accumulated across /run-guide-and-fix runs, and overwriting it would destroy work. If the regeneration adds new Parts that don't appear in the preserved section, append rows for them with ⏸ pending status.

Step 3 — Read All Stories

"📖 Reading the stories — need to understand who wanted what."

Read every STORY-*.md file in the stories/ folder:

ls docs/planning/milestones/{milestone-name}/stories/STORY-*.md

For each story, extract:

• Story number and title
• Narrative (As a... I want... So that...)
• Acceptance criteria (checkboxes)
• Tasks list
• Implementation notes

Fallback: If no stories/ directory exists:

1. Check subtasks.json for storyRef fields
2. Check for story files in alternative locations
3. Ask user where stories live

Step 4 — Check Subtask Completion

"🔍 Checking completion — the guide should be honest about what shipped."

Run the Ralph status command:

aaa ralph status --subtasks docs/planning/milestones/{milestone-name}/subtasks.json

Parse output for:

• Milestone name
• Progress (X/Y completed)
• Completion percentage
• Next subtask in queue

If not 100% complete: Warn user and list incomplete subtasks. Ask whether to proceed (guide will note pending items) or wait.

Read gaps-to-implement.md if it exists — these are known gaps between stories and the actual implementation.

Step 5 — Analyze Git Changes for Unplanned Work

"🔍 Peeking at git history for unplanned work..."

Find the milestone's branch:

# Try standard naming first
git branch -a | grep -i "{milestone-name}"

Try patterns: feature/{milestone-name}, feature/{milestone-name-variant}.

List all commits on the branch:

git log main..{branch} --oneline

Get file-level diff summary:

git diff main...{branch} --stat
git diff main...{branch} --name-only

Cross-reference each commit and changed file against stories to detect:

• Unplanned additions: Commits that don't map to any story (extra features, side-fixes, infrastructure changes). Files changed outside story scope.
• Missing features: Story acceptance criteria with no corresponding commits or changed files.
• Side-fixes: Bug fixes discovered during development that weren't in the original plan.

Flag these in the guide overview as "Additional functionality not in stories."

Step 6 — Gather Setup Context

"🏗️ Gathering setup context — ports, URLs, gotchas..."

Read project setup files:

# Root-level setup
README.md
CLAUDE.md
package.json

# Scripts directory
ls scripts/

Extract:

• How to start services (pnpm dev:start, docker commands, etc.)
• How to reset/seed the database
• URLs and ports (Admin UI, API, Mailpit, etc.)
• Known gotchas (docker ghost containers, migration issues, port conflicts)
• Prerequisites (Docker, Node.js, pnpm, etc.)

Step 7 — Write GUIDE.md

"✍️ Writing the guide..."

Output to docs/planning/milestones/{milestone-name}/GUIDE.md.

Follow this structure — use the reference guides as the gold standard for tone, detail level, and formatting:

Seed Validation Progress

For a fresh guide, emit this template immediately after Overview:

## Validation Progress

_Not yet validated. Run `/run-guide-and-fix` to begin._

| Phase | Status | Notes |
|-------|--------|-------|
| Prerequisites | ⏸ pending | — |
| Fresh Start Bootstrap | ⏸ pending | — |
| Part 1 — {story 1 title} | ⏸ pending | — |
| Part 2 — {story 2 title} | ⏸ pending | — |
| ...                         | ⏸ pending | — |

One row per Part (mirroring the Demo Flow Parts you're about to write). On regeneration, re-emit the previously captured section verbatim instead of seeding (see Step 2 — Inventory).

Narrative Arc

Each section has a narrative job — the guide should read as a journey, not a checklist:

Writing Guidelines

Tone and Voice:

• Open with what the milestone gives you — one sentence hook
• 1-2 sentences of scene-setting before each Part's steps, not more
• Short transitions between Parts ("Now let's try Y")
• After key verifications, one line of payoff ("If you see X, the pipeline works end to end")
• Be honest about gaps — don't hide, don't over-explain

Brevity:

• Context sentences are short. Steps are shorter. Callouts are one-liners.
• Commands first, explanation after, expected output at the end
• No paragraphs of setup narrative before a code block — get to the command

Specificity:

• Use exact URLs (http://localhost:3001/structure), exact button labels ("Create Company"), exact field names
• Each step follows logically from the previous one — number everything
• After each significant action, tell the reader what they should see

Callouts:

• Use > ⚠️ **Gotcha:**, > 💡 **Why?**, > 📝 **Note:** blockquotes for context that helps but isn't a step
• Callouts are one-liners — if you need a paragraph, it's a step

Agent-Browser Awareness:

• Write steps that can be automated — name UI elements by their role/label, not their CSS class
• Think in terms of: navigate, find, interact, verify

Anti-Patterns:

• No dry checklist tone ("Step 1: Do X. Step 2: Do Y.")
• No passive voice ("The button should be clicked" → "Click the button")
• No generic headings ("Test Steps" → "Build with OpenCode")
• No walls of text between commands

Step 8 — Present Summary

"📝 Guide covers [N] stories in ~[N] lines. [N gaps flagged]. Saved to docs/planning/milestones/{milestone-name}/GUIDE.md. Run /run-guide-and-fix to battle-test it — add --headed to watch live, or --theater for dramatic narration + a pause after every step."

Report to user:

• Sections written and approximate line count
• Stories covered (N/total)
• Gaps identified (pending features, unplanned additions)
• File path to the generated guide
• Suggest running /run-guide-and-fix next to validate the guide

Reference Guide (Gold Standard)

This existing guide demonstrates the target quality, tone, and structure:

• docs/planning/milestones/004-MULTI-CLI/TESTING-GUIDE.md — Conversational tone, commands first, honest about what works and what doesn't. The real gold standard.

When writing a new guide, match the tone, detail level, and formatting of this reference.