code-walkthrough

Code Walkthrough

Use a verified tour: establish the real code and output first, then guide attention through one immutable Navi tour.

Prepare The Session

1. Confirm termctrl, Neovim 0.10 or newer, and navi.nvim are available.

2. Start Neovim in the project root as a visible foreground session:

   termctrl run walkthrough -- nvim
   

3. Use Terminal Control from another process to inspect and drive that same session. Prefer interact through the Terminal Control MCP when available; otherwise use termctrl show, termctrl send, and termctrl wait.

4. Resize before composing the tour if the visible terminal is too narrow. Keep the size stable while presenting or recording.

The session is ready when the human and agent see the same settled Neovim screen and the agent can inspect it through Terminal Control.

Establish The Journey

1. Ask what the viewer should understand or be able to explain afterward when the outcome is unclear.
2. Read the relevant code and run the narrowest command that proves its current behavior.
3. Inspect the actual visible result. Do not write notes from an expected or remembered result.
4. Choose one conceptual journey. A useful journey often moves from public behavior to the mechanism that produces it, then to the observed result.

Do not combine an overview, failure diagnosis, implementation tour, and fix into one sequence. The journey is established when each planned stop is necessary to answer one coherent question.

Author One Immutable Tour

Create a JSON file outside the source tree when the tour is temporary. Use literal patterns when they are unique and stable; use line numbers only when exact positions are the point.

[
  {
    "file": "src/example.test.ts",
    "pattern": "it(\"updates subscribers\"",
    "end_pattern": "expect(runs).toBe(2)",
    "message": "The public contract starts here: one write must cause one additional run."
  },
  {
    "file": "src/example.ts",
    "pattern": "export function notify",
    "end_pattern": "subscriber()",
    "message": "The implementation reaches every subscriber through this loop."
  }
]