# Walkthrough

> Present a list of items one at a time for focused, interactive review — each with enough context to act on, then wait for the user before advancing. Use when the user wants to step through items one at a time, or hands over findings / tasks / suggestions / a file of items to review interactively rather than as a wall of text.

- Skill: `otrebu/walkthrough` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add otrebu/walkthrough`
- Raw SKILL.md: https://api.skillmd.com/api/skills/otrebu/walkthrough/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: otrebu (https://skillmd.com/u/otrebu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/otrebu/walkthrough

---


# 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.

2. **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.

3. **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.

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

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

6. **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.

| Input | Does |
|---|---|
| `next` / `n` / `ok` / Enter | Cursor → next item |
| `back` / `b` | Cursor → previous item |
| `goto N` | Cursor → item N |
| `find <term>` | Cursor → next item matching `<term>` |
| `discuss` / `d` / *(free text)* | Dig into the current item; cursor stays put |
| `edit` / `e` | Apply the change this item suggests; cursor stays put |
| `skip` / `s` | Record skipped, cursor → next item |
| `list` / `l` | Show the whole list compact (✓ done · ~ skipped · ● current), then return |
| `done` / `q` | End early and summarize |

## 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.