gistfile1.txt

# Walk through changes in vim, one function at a time

Vim should be in another tmux pane in this tmux window. If not, open a new tmux pane in the current window and start vim there. Name the pane "vim-walkthrough" so you have a stable way to reference it.

Use `tmux send-keys -t vim-walkthrough` to control vim and `tmux capture-pane -t vim-walkthrough -p` to read its state. **Never assume a result — always capture-pane after send-keys.**

**Pane width check:** At the start, check the vim pane width. If it's less than ~160 columns (too narrow for side-by-side diff), suggest to the user: "The vim pane looks narrow for side-by-side diffs. Want me to move other panes to a separate tmux window to free up space? (I can use `tmux break-pane`.)" Only do it if the user agrees.

## Determine which changes to walk through

1. Run `sl diff` to check for uncommitted changes.
2. If `sl diff` is non-empty, ask the user:
   - "committed only" → walk through `sl show` (the current commit)
   - "uncommitted only" → walk through `sl diff`
   - "both" → walk through `sl diff -r .~1` (committed + uncommitted combined)
3. If `sl diff` is empty, walk through `sl show` (the current commit) without asking.

## Prepare the walkthrough

1. Parse the diff to extract all modified files and the specific functions/hunks changed in each.
2. Build a static callgraph of the modified functions (callers and callees among the changed set).
3. Order the callgraph top-down: entry points and callers first, then the helpers/callees they use. The reader should understand the high-level algorithm before seeing implementation details.
4. For each file involved, prepare a one-line summary of what that file does at a high level.

## Walk through changes

**For modified files**, use vim's diff view:

1. Save the parent version to a temp file: `sl cat -r .^ <filepath> > /tmp/<filename>_parent.<ext>`
2. Open vimdiff in the tmux pane: `vim -d /tmp/<filename>_parent.<ext> <filepath>`
3. **Never zoom or resize the pane** — the user controls their own layout.
4. Use `]c` to jump between diff hunks.
5. Parent (before) is on the left, current (after) is on the right.

**For new files** (entirely added in this commit), just open the file normally in vim — no diff view needed since there's no parent version to compare against.

**Interface/header files:** When walking through a new module, check for interface or header files (e.g., `.mli`, `.h`, `.d.ts`, trait definitions) and show those first before the implementation. They define the public API and give the reader the contract before the details.

For each function/hunk in **top-down pedagogical order** (entry points and high-level algorithm first, then drill into implementation details):

**Important:** Follow the pedagogical order, NOT the file's line order. Jump to each function by name or line number — do not just scroll linearly through the file. For diff views, use `]c` only when the next diff hunk happens to be the next item in order; otherwise navigate directly. Start with public entry points / callers so the reader understands the overall algorithm before seeing the helpers they call.

1. **When entering a new file**, explain: what this file does in the context of the larger system, and which other files reference it (callers, importers). This is especially important for new files — the reader needs to know why this file exists and where it fits before seeing the code.
2. Tell the user which function you're about to show, what it does, and where it sits in the call chain (one sentence).
2. Use tmux send-keys to navigate to the function (e.g., `/functionname` or `:N` for line number).
3. Capture-pane to confirm vim is showing the right location.
4. **Leave the code on screen. Do NOT send any more keys to vim until the user says "next" or "n".** The user needs time to read the code in vim. Your job is to navigate once, then explain — not bounce around the file.
5. Explain the change clearly, assuming very little codebase knowledge:
   - What the function does
   - What specifically changed and why it matters
   - How it relates to other changes already discussed
6. **Stop and wait for the user to say "next" (or "n")** before moving to the next change.

"next" / "n" means **next change** (the next diff hunk), NOT next file. Stay in the current file until all its hunks are exhausted, then move to the next file. Never show multiple changes in a single turn — one navigation, one explanation, then stop. Do not skip ahead or batch explanations.

When moving to a new file, do NOT close vim or kill the pane — killing panes changes pane ordering and disrupts the user's layout. Instead, load the new files into the existing vim instance:
1. Close both diff buffers without quitting vim: `:windo bdelete`
2. Open the new diff: `:edit <new_file>` then `:vert diffsplit /tmp/<new_parent>`
For new files (no parent version), just `:edit <new_file>` — no diff needed.

## Additional instructions from the user (if any)

Apply these as overrides or extra focus areas for the walkthrough:

$ARGUMENTS