user-walkthrough

name	user-walkthrough
description	Attended, operator-driven acceptance of a just-built tool or feature. Establishes a persistent operating contract on entry, then YIELDS each turn to the operator — you ask questions or point at problems, the agent answers from primary source, fixes small things in-tree on the spot, logs big ones without rabbit-holing, marks UAT coverage as a byproduct, and hands the turn back. Use for post-/build-phase exploration where the operator wants to drive. Invoke as "/user-walkthrough <tool/feature>".
user-invocable	true

User walkthrough

Attended, operator-driven UAT. You (the operator) drive; the agent rides along. Each turn you ask a question or point at a problem; the agent answers from PRIMARY SOURCE (reads the actual code/artifact, cites file:line — never vibes), marks any coverage the exchange earned, routes issues to fix-now or log-for-later, then stops and hands the turn back. Coverage accrues as a byproduct of poking the build, not as a script you march through.

The ledger it reads and writes is defined once in .claude/references/shakedown-engine.md — this skill never redefines the row grammar, slug rule, or status vocabulary; it cites the engine.

When to use / not

• Use: a tool or feature was just built (post-/build-phase, post-/build-step, or a fresh /user-debug) and you want to poke it yourself — ask how it works, try things, surface issues — with the agent answering from source, fixing small breakage live, and tracking what got covered. You want to be in the driver's seat.
• Don't use when you want the agent to close out UAT autonomously (that is /user-shakedown), to execute an already-written UAT block for you (/user-uat), or to refine a fuzzy UAT script (/review-uat). If you have no build to poke yet, there is nothing to walk through.

Invocation

/user-walkthrough <tool/feature>     # attended walkthrough of the named build
/user-walkthrough export-button      # slug resolves the ledger per the engine's slug rule

Flow

1. Entry — orient, establish the contract

1. Resolve or derive the ledger per the engine reference: compute the feature-slug, resolve the ledger path via git rev-parse --show-toplevel, and load it if it already exists (never re-seed — a prior walkthrough or shakedown may have started it). If absent, derive it per the engine's checklist-derivation rules (seed from the plan's ## Manual UAT / Type: operator M-steps when present; else a lightweight derived expectation set).
2. State the operating contract once, then yield: "I'll answer from source with file:line, fix small things in-tree and show you, log big ones, and mark coverage as we go. You drive — ask or point at anything." Optionally kick off the tool and show its output to seed the first turn.

2. Loop — one operator turn at a time

Per turn the operator asks a question or reports a problem. The agent:

1. Answers from PRIMARY SOURCE. Read the actual code/artifact and cite file:line. Never answer a "does it / how does it" question from memory or inference — open the file. A confidently-wrong answer from vibes is worse than "let me check."
2. Marks coverage earned this turn. If the exchange exercised a behavior matching a ledger row, mark that row satisfied with concrete evidence (the command output / observed result / file:line) per the engine's coverage-marking rule — never a bare status flip.
3. Routes any issue by size, per the engine's two paths:
   • Small + unambiguous → fix it now, in the live tree. Edit in place (uncommitted), run the NARROWEST test, mark the row fixed with evidence. Do not spin a /build-step worktree; the fix must be visible to the running tool immediately. Never block on a (y/n) for your own small fix — just make it and report what you did.
   • Big → log it, don't rabbit-hole. Append the row logged with a one-line diagnosis and move on; it becomes a sibling issue at wrap.
4. STOP and hand the turn back. One operator ask → one agent response → stop. Do not keep working, do not chain into the next check unprompted, do not march a script. Yielding is the whole point of the attended mode.

3. Wrap — "did I miss anything?"

When the operator signals they're done (or asks for a wrap), report coverage in three buckets: satisfied (with evidence), still-open, and logged bigs. Then offer — do not execute — three closers:

1. Batch-commit the live fixes as one reviewable diff, using scoped git add <paths> of only the files this walkthrough touched (never git add -A).
2. File the logged bigs as GitHub sibling issues (via gh with --body-file) that feed /plan-feature or /build-step.
3. Emit the canonical /goal string from the engine to hand autonomous closure to /user-shakedown: /goal "shakedown ledger for <feature-slug> has zero open items"

The operator picks which closers to run — this is the attended mode; the operator decides.

Constraints

• MUST NOT arm a /goal DURING the loop. A /goal arms a Stop hook that re-prompts the agent every turn until its condition holds — which makes the session agent-paced and destroys the operator-driven dynamic (the agent would keep working instead of yielding to you). The /goal string is emitted at wrap only, opt-in, for the operator to paste. This is the single hardest rule in this skill.
• Never block on a (y/n) for the skill's own small fixes. Make the fix, run the narrowest test, report it. The operator is already in the loop every turn; a confirmation gate is noise.
• Never write into any plan's ## Manual UAT block. That block is append-only and owned by /build-phase. The ledger is a SEPARATE task-state artifact (per the engine's path formula) — status lives there, never in plan.md.
• Answer from primary source, always. Every substantive claim cites file:line. No vibes.
• Small fixes stay in the live tree, uncommitted until wrap. No worktree; scoped commit at wrap only.

Limitations — four-mode disambiguation

Four sibling UAT modes; pick by who drives and what shape the input is:

Skill	What it does
/user-uat	EXECUTES an already-clear UAT script FOR you (mechanical tier auto-judged).
/review-uat	REFINES a fuzzy UAT script until every step is unambiguous.
/user-walkthrough	This skill. The operator DRIVES exploration; the agent answers, fixes small, logs big.
/user-shakedown	The agent AUTONOMOUSLY CLOSES the ledger to zero open items (same engine).

/user-walkthrough and /user-shakedown share the same ledger file (same slug rule → same path), so a walkthrough can hand a half-filled ledger to a shakedown mid-stream.

Canonical example — one loop turn

Operator: "Does the CSV export respect the active date filter?"

Agent: Reads src/export/csv.py:41-58 — the query is built from request.filters and the date range is applied at line 47. Cites it: "Yes — csv.py:47 folds filters.date_range into the WHERE clause before serialization." Marks ledger row M1 satisfied with evidence csv.py:47 applies date_range. Stops, hands the turn back.

Operator: "The export button label says 'Exprot'."

Agent: Small + unambiguous → fixes it in the live tree (templates/export.html:12), runs the narrowest test (pytest tests/test_export_template.py -k label → 1 passed), marks the row fixed with that evidence. No (y/n). Stops.

Operator: "Export of a 2M-row table times out."

Agent: Big → does NOT rabbit-hole. Appends a logged row with the one-line diagnosis "streaming/pagination needed for large exports; synchronous path blocks." Stops.

At wrap: reports M1 satisfied, the label fixed, the timeout logged; offers to batch-commit the label fix, file the timeout as a sibling issue, and emit the /goal string for shakedown.