Read the source and produce a linear walkthrough that explains how the code works in detail. Use showboat to build an executable walkthrough.md in the repo root.
Workflow
- Read the source — Understand structure, entry points, dependencies, and data flow before writing anything. If a scope/focus argument is given, limit source reading and coverage to that area.
- Plan the order — Decide what to cover and in what sequence. Start from entry points and follow the call chain.
- Initialize — if
walkthrough.md already exists in the repo root, ask the user whether to overwrite it (fresh start) or resume/extend the existing one before doing anything else. Otherwise run uvx showboat init walkthrough.md "<Project> Walkthrough". If uvx/showboat is missing or init fails, run uvx --from showboat showboat --version to check the install, retry once, and if it still fails tell the user showboat is unavailable and offer a plain markdown walkthrough instead.
- Build — Alternate
showboat note (commentary) and showboat exec (code snippets) to walk through the codebase linearly.
- Verify —
uvx showboat verify walkthrough.md to confirm all code blocks produce the expected output. If verify reports diffs: when the failing entry is the most recent one, uvx showboat pop walkthrough.md, fix the command, and re-add with showboat exec; for a mid-document entry (pop only removes the last entry), run uvx showboat verify walkthrough.md --output walkthrough.md to refresh captured output in place — and if the command itself is wrong, rebuild from that entry onward.
Walkthrough structure
- Overview — What the project does, key technologies, entry points
- Architecture — Directory layout, module boundaries, data flow
- Core walkthrough — Step through the code linearly, starting from entry points and following the call chain through modules
Snippet selection
Show the most important 5–20 lines per concept. Prefer function signatures, key logic, and configuration over boilerplate. Use sed -n, grep, cat, or similar via showboat exec to include snippets. Every snippet should earn its place — if it doesn't clarify the narrative, cut it.
Example
uvx showboat note walkthrough.md <<'EOF'
## Configuration
The app reads config from `config.yaml` at startup. The `load_config`
function validates required fields and falls back to defaults.
EOF
uvx showboat exec walkthrough.md bash "sed -n '10,25p' src/config.py"
This produces the following section in walkthrough.md:
## Configuration
The app reads config from `config.yaml` at startup. The `load_config`
function validates required fields and falls back to defaults.
```bash
sed -n '10,25p' src/config.py
```
```output
def load_config(path: str = "config.yaml") -> Config:
"""Load and validate configuration, applying defaults for missing fields."""
with open(path) as f:
raw = yaml.safe_load(f)
for field in REQUIRED_FIELDS:
if field not in raw:
raise ConfigError(f"missing required field: {field}")
return Config(
host=raw.get("host", DEFAULT_HOST),
port=raw.get("port", DEFAULT_PORT),
debug=raw.get("debug", False),
)
```
Showboat reference
Showboat creates executable markdown documents where every fenced code block is re-runnable and verifiable.
Commands
uvx showboat init <file> <title> — Create a new document
uvx showboat note <file> [text] — Append commentary (plain markdown, not executed). Use heredoc for multi-line: uvx showboat note file.md <<'EOF' ... EOF
uvx showboat exec <file> <lang> [code] — Run code, capture output. Appends a lang block (the command) and an output block (the result)
uvx showboat pop <file> — Remove the most recent entry (useful after a failed exec)
uvx showboat verify <file> — Re-run all code blocks and diff against captured output
uvx showboat verify <file> --output <file> — Re-run and update output blocks in place
Gotchas
- Every fenced block is executable. Showboat treats all code blocks as runnable — there is no "display only" mode. Static content (trees, diagrams) must use a command that produces the output, e.g.
cat <<'HEREDOC' ... HEREDOC
- Non-deterministic output breaks verify. Timing, dates, and random values will differ across runs. Avoid capturing commands like
bun test whose output includes wall-clock time. Use deterministic alternatives (e.g. grep -c to count tests)
- Code fences in output. If the captured output contains triple backticks, showboat uses quadruple-backtick fences automatically — no special handling needed
- Do not run prettier on
walkthrough.md. Showboat manages its own formatting; prettier would break verified output blocks. (The user-level auto-format hook only fires on Edit/Write/MultiEdit tool calls — since uvx showboat writes via shell, the hook never sees the file. Be careful not to bypass that protection by editing walkthrough.md directly with Edit or Write.)
Do not use when
- The user just wants an explanation in conversation — a walkthrough produces a
walkthrough.md file in the repo; don't create an artifact for a chat-only "explain this" request
- Reviewing code for bugs or design issues — use
code-audit or /code-review
- Explaining why the system is shaped as it is, rather than how it runs — use
codebase-theory
- Auditing harness customizations — use
cc-release-review
- Auditing or trimming CLAUDE.md — use
/doctor
1---2name: walkthrough3description: Reads source code and produces a linear, executable walkthrough document. Use when explaining how code works, creating walkthroughs, onboarding to a project, or giving a code tour. Generates structured showboat documents with annotated code paths.4---56Read the source and produce a linear walkthrough that explains how the code works in detail. Use showboat to build an executable `walkthrough.md` in the repo root.78## Workflow9101. **Read the source** — Understand structure, entry points, dependencies, and data flow before writing anything. If a scope/focus argument is given, limit source reading and coverage to that area.112. **Plan the order** — Decide what to cover and in what sequence. Start from entry points and follow the call chain.123. **Initialize** — if `walkthrough.md` already exists in the repo root, ask the user whether to overwrite it (fresh start) or resume/extend the existing one before doing anything else. Otherwise run `uvx showboat init walkthrough.md "<Project> Walkthrough"`. If `uvx`/`showboat` is missing or `init` fails, run `uvx --from showboat showboat --version` to check the install, retry once, and if it still fails tell the user showboat is unavailable and offer a plain markdown walkthrough instead.134. **Build** — Alternate `showboat note` (commentary) and `showboat exec` (code snippets) to walk through the codebase linearly.145. **Verify** — `uvx showboat verify walkthrough.md` to confirm all code blocks produce the expected output. If verify reports diffs: when the failing entry is the most recent one, `uvx showboat pop walkthrough.md`, fix the command, and re-add with `showboat exec`; for a mid-document entry (`pop` only removes the last entry), run `uvx showboat verify walkthrough.md --output walkthrough.md` to refresh captured output in place — and if the command itself is wrong, rebuild from that entry onward.1516## Walkthrough structure17181. **Overview** — What the project does, key technologies, entry points192. **Architecture** — Directory layout, module boundaries, data flow203. **Core walkthrough** — Step through the code linearly, starting from entry points and following the call chain through modules2122## Snippet selection2324Show the most important 5–20 lines per concept. Prefer function signatures, key logic, and configuration over boilerplate. Use `sed -n`, `grep`, `cat`, or similar via `showboat exec` to include snippets. Every snippet should earn its place — if it doesn't clarify the narrative, cut it.2526## Example2728```bash29uvx showboat note walkthrough.md <<'EOF'30## Configuration3132The app reads config from `config.yaml` at startup. The `load_config`33function validates required fields and falls back to defaults.34EOF3536uvx showboat exec walkthrough.md bash "sed -n '10,25p' src/config.py"37```3839This produces the following section in `walkthrough.md`:4041````markdown42## Configuration4344The app reads config from `config.yaml` at startup. The `load_config`45function validates required fields and falls back to defaults.4647```bash48sed -n '10,25p' src/config.py49```5051```output52def load_config(path: str = "config.yaml") -> Config:53 """Load and validate configuration, applying defaults for missing fields."""54 with open(path) as f:55 raw = yaml.safe_load(f)5657 for field in REQUIRED_FIELDS:58 if field not in raw:59 raise ConfigError(f"missing required field: {field}")6061 return Config(62 host=raw.get("host", DEFAULT_HOST),63 port=raw.get("port", DEFAULT_PORT),64 debug=raw.get("debug", False),65 )66```67````6869## Showboat reference7071Showboat creates executable markdown documents where every fenced code block is re-runnable and verifiable.7273### Commands7475- `uvx showboat init <file> <title>` — Create a new document76- `uvx showboat note <file> [text]` — Append commentary (plain markdown, not executed). Use heredoc for multi-line: `uvx showboat note file.md <<'EOF' ... EOF`77- `uvx showboat exec <file> <lang> [code]` — Run code, capture output. Appends a `lang` block (the command) and an `output` block (the result)78- `uvx showboat pop <file>` — Remove the most recent entry (useful after a failed exec)79- `uvx showboat verify <file>` — Re-run all code blocks and diff against captured output80- `uvx showboat verify <file> --output <file>` — Re-run and update output blocks in place8182### Gotchas8384- **Every fenced block is executable.** Showboat treats all code blocks as runnable — there is no "display only" mode. Static content (trees, diagrams) must use a command that produces the output, e.g. `cat <<'HEREDOC' ... HEREDOC`85- **Non-deterministic output breaks verify.** Timing, dates, and random values will differ across runs. Avoid capturing commands like `bun test` whose output includes wall-clock time. Use deterministic alternatives (e.g. `grep -c` to count tests)86- **Code fences in output.** If the captured output contains triple backticks, showboat uses quadruple-backtick fences automatically — no special handling needed87- **Do not run prettier on `walkthrough.md`.** Showboat manages its own formatting; prettier would break verified output blocks. (The user-level auto-format hook only fires on `Edit`/`Write`/`MultiEdit` tool calls — since `uvx showboat` writes via shell, the hook never sees the file. Be careful not to bypass that protection by editing `walkthrough.md` directly with `Edit` or `Write`.)8889## Do not use when9091- The user just wants an explanation in conversation — a walkthrough produces a `walkthrough.md` file in the repo; don't create an artifact for a chat-only "explain this" request92- Reviewing code for bugs or design issues — use `code-audit` or `/code-review`93- Explaining why the system is shaped as it is, rather than how it runs — use `codebase-theory`94- Auditing harness customizations — use `cc-release-review`95- Auditing or trimming CLAUDE.md — use `/doctor`