# Write Guide > Generate a comprehensive GUIDE.md for a project milestone. Use when user asks to "write guide", "generate guide", "create demo guide", or "write-guide". Analyzes milestone stories, git changes, and project setup to produce a step-by-step demo guide. - Skill: `otrebu/write-guide` (Agent Skill) - Install (CLI): `npx skillmds@latest add otrebu/write-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/otrebu/write-guide/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: otrebu (https://skillmd.com/u/otrebu) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/otrebu/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/`: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash # 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: ```bash git log main..{branch} --oneline ``` Get file-level diff summary: ```bash 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: ```bash # 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: | # | Section | Content Source | |---|---------|---------------| | 1 | **Overview** | Stories table (number, feature, status, notes), branch name, what's implemented vs pending, unplanned additions | | 2 | **Validation Progress** | Seeded empty for fresh guides; preserved verbatim on regeneration. Tracks resume state across `/run-guide-and-fix` sessions. See "Seed Validation Progress" below for the template. | | 3 | **Prerequisites** | Setup commands from README/package.json, explanatory callouts (`> **Why X?**`), URLs/ports table | | 4 | **Fresh Start Bootstrap** | Numbered reset-to-running sequence. Order of operations from clean slate to working app. | | 5 | **Demo Flow** | One **Part** per story. Numbered sub-steps (N.1, N.2...). Each step is actionable: navigate/click/type/verify. Include exact URLs, UI labels, expected outcomes. Add `> **Gotcha**` callouts for non-obvious behavior. | | 6 | **Verification Checklist** | Per-story checkboxes derived from acceptance criteria. Unchecked `- [ ]` format. | | 7 | **Key Features Demonstrated** | Feature matrix table mapping features to where they appear in the demo. | | 8 | **Troubleshooting** | Problem/solution pairs from known issues, gaps doc, and common failures. | | 9 | **Agent-Browser Automation Gotchas** | Selectors and labels that need special handling. Timing tips (where to add waits). Session management notes. Refs that go stale. | | 10 | **Gap Analysis** | Stories vs implementation matrix. Columns: Story, Feature, Implemented?, Notes. | #### Seed Validation Progress For a fresh guide, emit this template immediately after Overview: ```markdown ## 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: | Section | Narrative Role | |---------|---------------| | πŸ—ΊοΈ Overview | **The hook** β€” what this milestone gave you, in one sentence | | 🧰 Prerequisites | **The preparation** β€” get your tools ready | | πŸš€ Fresh Start Bootstrap | **The ritual** β€” clean slate to running app | | 🎬 Demo Flow | **The journey** β€” explore each feature, one Part per story | | βœ… Verification Checklist | **The scorecard** β€” did it all work? | | πŸ”‘ Key Features Demonstrated | **The map** β€” what lives where | | πŸ› οΈ Troubleshooting | **The safety net** β€” when things go wrong | | πŸ€– Agent-Browser Gotchas | **The automation tips** β€” selectors, timing, sessions | | πŸ“‹ Gap Analysis | **The honest accounting** β€” what shipped, what didn't | ### 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.