walkthrough

Move a cursor over a list, one item per turn. You present the item under the cursor with enough context to judge it, the user reacts, the cursor advances. The win is focus: the user processes and pushes back on each item instead of drowning in a dump.

The list is pinned — built once, held in context for the whole walkthrough. Each turn restates where the cursor is; never assume the user still sees the previous item.

Steps

1. Find the items. In priority order:

- A file the user named (walk me through subtasks.json) → read it; treat array entries / list items / top-level sections as the items. - The conversation — findings, suggestions, tasks, options just produced → enumerate those. - An inline list in the user's message → parse it directly.

If it's ambiguous what to walk through, ask once, then proceed.

1. Pin the list. Enumerate the items as a stable, ordered list and hold the full text in context — back, goto N, and find all read from it. Do not re-derive it each turn.

1. Announce, then present item 1. One line: Found N items. I'll go through them one at a time — ready for the first? Present item 1 in the same turn unless the user's request didn't already imply go.

1. Present the item under the cursor, then stop and wait. One item per turn — never advance the cursor twice in one turn.

1. Act on the response (see Controls), move the cursor, present the new item with a fresh header.

1. Finish when the cursor runs off the end or the user says done.

Controls

Anything unrecognized is discuss — the user is reacting to the current item.

Presentation format

─── Item 3/7 · [Type] ───

**<title or one-line summary>**

<the detail — enough to understand and judge it on its own>

<suggested action, if the item implies one>

[ next · back · discuss · edit · skip · goto N · find <term> · list · done ]

• [Type] is whatever the items are — Finding, Task, Option, Diff, Risk. Drop it if untyped.
• The control hint line is the only menu the user sees — keep it on every item.
• For a file walkthrough, quote the relevant slice (the array element, the section) rather than making the user open the file.

State to keep

Track across turns; reflect it in the header and wrap-up:

• Position — cursor index out of total.
• Skipped — items passed with skip.
• Discussed — items that got a discuss turn.
• Edited — items where edit changed something (note what changed).

Finishing

Close with one line:

Walked through N items — X discussed, Y edited, Z skipped.

If anything was edited, list those changes as bullets so the user has a record. If items were skipped and the list came from a file, offer to re-run over just the skipped ones.

Notes

• edit is real work, not a note-to-self. Actually apply the change (file edit, rewrite, whatever the item implies), confirm it landed, then leave the cursor put so the user advances deliberately.