mostafa-drz/code/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/<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:

# /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:

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