walkthrough

name	walkthrough
description	Build a linear walkthrough document explaining how a codebase or subsystem works, using Showboat with real command output for every code snippet. Use to get up to speed on unfamiliar or vibe-coded code.

Linear walkthrough

Produce a structured, readable walkthrough that explains how the code works in detail — for onboarding, for code you've forgotten, or for vibe-coded projects you never actually read.

Procedure

1. Read the source first. Explore the target code (a subagent is fine for this) and plan a linear narrative: what order should a reader meet the pieces in so each builds on the last?
2. Run uvx showboat --help to learn the tool.
3. Create walkthrough.md (in the repo root, or notes/ for partial ones) and build the walkthrough in it:
   • showboat note for the explanatory commentary between snippets.
   • showboat exec with sed, grep, cat, etc. to include the code snippets you discuss. Never copy code into the document by hand — going through exec guarantees the snippets match the real source and can't be hallucinated.
4. Cover every significant file. Explain not just what each piece does but why it's shaped that way and how the pieces connect.

The result should teach a competent developer how the whole thing works from a single linear read.