Step Through

/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/.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 ""    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/.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:

# /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 "" 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 is passed (e.g. blockers, major, follow-up), keep only matching items. Match case-insensitively against the section the item came from.

If --start is passed, drop items with index 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

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

## {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"}

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

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mostafa-drz
• Source: mostafa-drz/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.