git:20260507.d7f31b8 to git:20260911.22df896

---

name: step-through

description: >-

Walks the user through a long enumerated response (numbered findings, audit

list, refactor plan, bug list, PR review, recommendations, action items)

one item at a time. For each item, lets the user dive deeper, take action,

defer, or skip — instead of staring at the whole wall of text. Learns the

user's per-severity defaults from feedback. Use when an assistant has just

produced a long list and the user says "let's go through these one by one",

"step me through", "walk me through", "let's triage", "next item", or

otherwise wants interactive per-item review of a previous response. Works

on any enumerated content — not just PR reviews.

disable-model-invocation: true

allowed-tools:

- AskUserQuestion

- Read

- Glob

- Grep

- Bash

- Edit

- Write

- WebSearch

- WebFetch

---

# /step-through

Take a long enumerated response and walk through it interactively, one item at a time, with a decision per item — and learn the user's per-severity habits over sessions.

## Preferences

_On startup, use the `Read` tool to load `~/.claude/skills/step-through/preferences.md`. If missing, treat as first-run (see First-time detection below)._

Defaults when no preferences exist:

- **default-depth:** `concise` — one paragraph plus 1–2 references on dive deeper

- **show-outline:** `yes` — print the outline before starting

- **persist-session-log:** `yes` — append decisions to `sessions/<date>.md`

- **auto-pick-source:** `most-recent` — most recent enumerated assistant message

- **action-confirmation:** `destructive-only` — confirm before file deletes / branch ops / pushes / external posts; everything else proceeds

- **resume-on-stop:** `yes` — when a session is stopped mid-way, save resume state so the next invocation can pick up where it left off

- **per-severity-defaults:** none yet (filled by Learned over time)

## Context

_Do NOT pre-load anything on startup. The skill works against the current conversation's recent assistant messages. Run Bash/Read only when the user picks "dive deeper" or "take action" on a specific item — at that point, fetch only what's needed for that item._

## Command routing

Check `$ARGUMENTS`:

- **`help`** → display help, then stop

- **`config`** → interactive setup, then stop

- **`reset`** → delete `~/.claude/skills/step-through/preferences.md` AND `feedback-journal.md` AND `sessions/`, confirm, stop

- **`feedback`** → collect thumbs-up/down on the most recent walkthrough (see Feedback & learning), stop

- **`resume`** → continue the most recent stopped walkthrough using saved resume state, stop if none

- **anything else** (including empty) → run the skill

### Help

```

/step-through — Walk through a long enumerated response item-by-item

Usage:

/step-through Walk through the most recent enumerated response

/step-through --filter blockers Only walk through items in that section/severity

/step-through --start 3 Resume from item N

/step-through --from "<hint>" Pick a different message by short description

/step-through resume Continue the most recent stopped walkthrough

/step-through feedback Rate the last walkthrough (improves future defaults)

/step-through config Set preferences

/step-through reset Clear preferences + feedback journal + sessions

/step-through help This help

Per-item options:

Dive deeper Pull code / docs / context to better understand

Take action Edit, run, research, or fix right now

Note & defer Capture decision (e.g. "address with AIS-XXXX"), move on

Skip Drop without action

Stop End the walkthrough, summarise

Examples:

/step-through After a long PR review

/step-through --filter blockers Only critical items

/step-through --start 7 Resume mid-list

Current preferences:

(loaded from ~/.claude/skills/step-through/preferences.md)

```

### Config

Use `AskUserQuestion` to collect 5 preferences in one batch:

1. **Default depth on Dive deeper** — `concise` (one paragraph + 1–2 refs) vs `thorough` (open files, web, full context)

2. **Show outline first** — `yes, always show outline` vs `skip, jump to item 1`

3. **Persist session log** — `yes, write to sessions/<date>.md` vs `no, summary in chat only`

4. **Source selection** — `auto: most-recent enumerated message` vs `always ask which message`

5. **Confirmation policy on Take action** — `destructive only` (file deletes, pushes, external posts) vs `every action` (confirm any edit/command)

Save to `~/.claude/skills/step-through/preferences.md` in this format:

```markdown

# /step-through preferences

Updated: YYYY-MM-DD

## Defaults

- default-depth: concise

- show-outline: yes

- persist-session-log: yes

- auto-pick-source: most-recent

- action-confirmation: destructive-only

- resume-on-stop: yes

## Profile (optional — edit freely)

- preferred severity to start with: blockers

- usual filter: none

- typical action style: minimal-edit, prefer linking a Linear ticket over inline fix

## Learned

- (populated by feedback over time — e.g. "follow-up severity → defer by default")

```

After save, print a one-line summary: `Saved. /step-through will use these defaults from now on.`

### Reset

Delete:

- `~/.claude/skills/step-through/preferences.md`

- `~/.claude/skills/step-through/feedback-journal.md`

- `~/.claude/skills/step-through/sessions/` (entire directory if exists)

- `~/.claude/skills/step-through/resume-state.md` (if exists)

Confirm: `All cleared. Starting fresh next time.`

## First-time detection

If no preferences file exists, show a warm one-liner (do not block):

> First time using `/step-through`? I'll walk you through the most recent long response one item at a time. After your first walkthrough, run `/step-through feedback` so I can learn your defaults. Or run `/step-through config` first to tune behaviour.

Then proceed with defaults.

---

## Workflow

### Step 0 — Load learning context

Before anything else:

1. Read `preferences.md` — carry **Defaults**, **Profile**, and **Learned** forward into the session.

2. Read `feedback-journal.md` if it exists — scan for any "Signal" lines that match the current source (e.g. severity terminology, source style). These quietly bias the per-item pre-selection in step 4b.

3. If `--filter`, `--start`, or `--from` are present in `$ARGUMENTS`, parse them now.

If any file fails to read, continue silently with defaults — never block on missing learning state.

### Step 1 — Locate the source response

Default behaviour: **the most recent assistant message in this conversation that contains an enumerated list.** Look for any of:

- Numbered items (`1.`, `2.`, …) at line start

- Markdown bullets at the same indent level (3 or more)

- Section headers like `### N. Something` or `🔴 Blockers` / `🟠 Major` / `🟡 Follow-up`

- Lists under headings like "Findings", "Issues", "Recommendations", "Items", "Tasks", "Next steps"

If `--from "<hint>"` is set, scan back for an assistant message whose contents loosely match the hint (substring or theme) and use that.

If preference `auto-pick-source` is `always-ask`, list up to 3 candidate messages with one-line summaries and ask which one to use.

If nothing enumerable is found in recent context: stop and tell the user — `I can't see a long enumerated response in this conversation. Paste it, or tell me which message to use.` Do **not** fabricate items.

### Step 2 — Parse items

Extract a structured list. For each item capture:

- `index` — 1-based position in the list

- `severity` — if the source uses sections like Blockers / Major / Follow-up / Nice-to-have, capture the section as severity. Otherwise leave blank.

- `title` — short label (first line / heading)

- `body` — the full text of the item (verbatim, do not paraphrase)

- `references` — any `path/to/file.ts:LN` citations, URLs, or doc links found in the body

If `--filter <severity>` is passed (e.g. `blockers`, `major`, `follow-up`), keep only matching items. Match case-insensitively against the section the item came from.

If `--start <n>` is passed, drop items with `index < n`.

### Step 3 — Show the outline (unless preference says skip)

Print a single compact outline so the user knows the scope:

```

14 items found in the last response. Walking through:

1. [BLOCKER] Client Sentry init missing environment + release

2. [BLOCKER] global-error.tsx was deleted

3. [BLOCKER] Triple Sentry ingestion via structuredLog

…

```

Titles only — never reproduce the full bodies here. Then say one line: `Starting with item 1.` and move on (no permission prompt — the user invoked the skill).

### Step 4 — Per-item loop

For **each item in order**:

#### 4a. Present the item

Print the item exactly as it appeared in the source response — verbatim body, references included. Add one header line:

```

Item N of M — [SEVERITY] — Title

```

Do **not** rewrite, summarise, or "improve" the item text on first presentation. The user already chose to walk through this content as-is.

#### 4b. Ask what to do — single AskUserQuestion

Use `AskUserQuestion` with these 5 fixed options (in this order):

1. **Dive deeper** — pull supporting context (read referenced files, fetch docs, web search)

2. **Take action** — fix it / run a command / draft a change right now

3. **Note & defer** — capture a one-line decision and move on

4. **Skip** — drop without action

5. **Stop** — end the walkthrough early and summarise

Header: `Item N of M`.

**Pre-selection logic** (apply in priority order, top wins):

1. If preferences `Learned` has a per-severity rule matching this item's severity, pre-select that.

2. Else if the item has file/URL references, pre-select **Dive deeper**.

3. Else pre-select **Note & defer**.

#### 4c. Execute the choice

- **Dive deeper:**

- Pull every referenced file/path. Use `Read` for paths, `Bash(git *)` for blame/log if relevant, `WebFetch` for URLs in the item, `Grep`/`Glob` for symbol lookups.

- Respect the user's `default-depth` preference (concise vs thorough).

- After presenting findings, ask the user **the same 5 options again** for this item — they may now want to take action, defer, or skip.

- **Take action:**

- Use the smallest set of tools needed: `Edit`/`Write` for code, `Bash` for commands, `WebSearch`/`WebFetch` for verification.

- Confirmation: if `action-confirmation: every`, confirm in chat before any edit/command. If `destructive-only`, confirm only before file deletes, branch operations, pushes, or external posts. Auto mode does **not** bypass destructive-only confirmation.

- After the action, briefly state what was done in 1–3 lines, then move to the next item without asking again. Do not loop on the same item.

- **Note & defer:** ask one short follow-up — `Note?` — capture the user's reply (or accept empty) and move on.

- **Skip:** record as skipped, move on.

- **Stop:** break the loop, jump to step 5. If `resume-on-stop: yes`, write resume state (see step 6) before summarising.

#### 4d. Track the decision

Maintain an in-memory record per item:

```

{ index, severity, title, decision: "deeper|action|defer|skip", note?: string, action_summary?: string }

```

If `persist-session-log: yes`, also append to `~/.claude/skills/step-through/sessions/YYYY-MM-DD-HHMM.md` after each decision (incremental write, not at the end). Header line on first write should include the source — message hash, date, and total item count.

### Step 5 — Final summary

When the loop ends (all items processed, or user picked Stop), print one compact block:

```

Walkthrough complete — N items.

Action taken: [list of indices + 1-line action summaries]

Deferred: [indices + notes]

Skipped: [indices]

Not reached: [indices, if Stop was used]

```

Then ask **one** follow-up question via `AskUserQuestion`:

- **Open a Linear ticket for deferred items?** (only if any deferred)

- **Open a PR for action-taken items?** (only if files were edited)

- **Done** — exit cleanly.

Do not auto-create tickets/PRs without explicit confirmation.

### Step 6 — Save resume state (only if Stop was used)

If the user picked Stop and `resume-on-stop: yes`, write `~/.claude/skills/step-through/resume-state.md` with: source identifier, processed indices, remaining indices, decisions so far. Tell the user: `Run /step-through resume to continue from item N.`

If the loop completed normally, delete any stale `resume-state.md`.

### Step 7 — Invite feedback

End with one short line:

> When you're done, run `/step-through feedback` — even one rating helps me sharpen per-severity defaults for next time.

Do not ask interactively here. Feedback is opt-in via the dedicated subcommand.

---

## Feedback & learning

When invoked as `/step-through feedback`:

1. Find the most recent session log (`sessions/YYYY-MM-DD-HHMM.md`). If none, say `No recent walkthrough found.` and stop.

2. Print a one-line summary of that session (item counts by decision).

3. Ask via `AskUserQuestion` (4 questions, one batch):

- **Did the per-item flow feel right?** — `yes, smooth` / `too slow` / `too fast` / `wrong defaults`

- **Which decisions felt wrong, if any?** — free text (item indices + what should have happened)

- **For follow-up severity items, what's your usual call?** — `defer by default` / `skip by default` / `dive deeper first` / `varies`

- **For blocker severity items, what's your usual call?** — `dive deeper first` / `take action immediately` / `defer with ticket` / `varies`

4. Append to `~/.claude/skills/step-through/feedback-journal.md`:

```markdown

## {session slug} — {date}

- Pace: {smooth|too-slow|too-fast|wrong-defaults}

- Wrong calls: {indices + user text}

- Follow-up default: {answer}

- Blocker default: {answer}

- Signal: {one-line generalization, e.g. "user defers all follow-ups, dives deeper on blockers"}

```

5. **Promotion rule:** when 3+ sessions show a consistent answer for the same severity, promote it to `## Learned` in `preferences.md` as a rule like `follow-up severity → defer by default`. Mention once: `Noticed you consistently defer follow-up items. Saved as standing default.` These rules feed step 4b's pre-selection.

6. **Drift correction:** if a Learned rule is contradicted in 2 newer sessions, demote it (remove from Learned, log in journal as `## Demoted: {rule} — too unstable`). Never leave stale rules.

---

## Principles

1. **Preserve the source.** Show item bodies verbatim on first presentation. The user trusts the original wording — don't paraphrase, condense, or "improve" it.

2. **One decision at a time.** Never batch decisions across multiple items, never ask "should I handle 1, 2, and 5?". Single item, single question, single action.

3. **The skill orchestrates — it doesn't review.** Not a re-review of the source. No new findings, severity downgrades, or "your reviewer was wrong about #6" commentary. The user owns judgement; the skill provides flow.

4. **No fabricated structure.** If the source response isn't actually enumerated, stop and ask — don't invent items.

5. **Destructive actions still need confirmation.** `disable-model-invocation: true` makes the skill user-triggered, but file deletes, branch ops, pushes, and external posts always require an explicit yes — auto mode does not bypass that.

6. **Stop means stop.** When the user picks Stop, do not continue any in-flight per-item work. Skip to the summary, save resume state.

7. **Learn quietly.** Promote a rule only after 3+ consistent feedback signals. Mention once when promoting, never lecture. Demote unstable rules instead of accumulating clutter.

8. **Graceful degradation.** If `preferences.md` or `feedback-journal.md` can't be read, continue with built-in defaults — never block on missing learning state.