Walkthrough

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

1. Read the source — Understand structure, entry points, dependencies, and data flow before writing anything.
2. Plan the order — Decide what to cover and in what sequence. Start from entry points and follow the call chain.
3. Initialize — uvx showboat init walkthrough.md " Walkthrough"
4. Build — Alternate showboat note (commentary) and showboat exec (code snippets) to walk through the codebase linearly.
5. Verify — uvx showboat verify walkthrough.md to confirm all code blocks produce the expected output. If verify reports diffs, use uvx showboat pop walkthrough.md to remove the failing entry, fix the command, and re-add with showboat exec.

Walkthrough structure

1. Overview — What the project does, key technologies, entry points
2. Architecture — Directory layout, module boundaries, data flow
3. 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  ` — Create a new document
- `uvx showboat note  [text]` — Append commentary (plain markdown, not executed). Use heredoc for multi-line: `uvx showboat note file.md   [code]` — Run code, capture output. Appends a `lang` block (the command) and an `output` block (the result)
- `uvx showboat pop ` — Remove the most recent entry (useful after a failed exec)
- `uvx showboat verify ` — Re-run all code blocks and diff against captured output
- `uvx showboat verify  --output ` — 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

- Reviewing code for bugs or design issues — use `code-audit` or `diff-review`
- Auditing harness customizations — use `cc-release-review`
- Auditing CLAUDE.md — use `claudemd-audit`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [philoserf](https://github.com/philoserf)
- **Source:** [philoserf/claude-code-config](https://github.com/philoserf/claude-code-config)
- **License:** MIT

Install and usage instructions live in the source repository linked above.