Walkthrough

Walkthrough

Walk the user through a plan file or document ONE decision at a time. They ratify each beat before the next appears, and each verdict is written to the plan file the moment they give it. This formalizes a standing "walk me through / beat by beat" practice. It exists to kill two failure modes: cramming many findings into one beat (a dump), and using specialized terms without a plain gloss (jargon the user cannot parse). A walkthrough is teaching, so it must itself model plain-language teaching.

When it fires

The user says any trigger phrase above, OR they hand you a plan / draft / decision set and ask to go through it together and sign off. If there is a target file on disk, name it first: "Walking through <path>, section by section." If there is no file yet, say so and offer to create the plan file first, because the verdicts have nowhere durable to land otherwise (see "Write the verdict" below).

The beat contract (hard caps, no exceptions)

A beat is ONE decision, presented for a verdict. Every beat obeys all of:

• One decision only. One section, one fork, one locked choice. Never bundle two decisions "to save a round." If a section holds three real decisions, it is three beats.
• Six lines maximum. If it does not fit in six lines, the beat is too big. Split it.
• Plain language leads. Open with the plain-English version of what is being decided and why it matters. The technical name is a parenthetical, never the headline. Gloss every specialized term inline on first use, in the same sentence, e.g. "idempotent (safe to run twice, same result)". No stacked unglossed terms. No invented shorthand used as if shared. This is the plain-language-first rule (rules/plain-language-first.md in this repo) applied live.
• One hinge question, max. The beat ends with exactly one question that forks the user's decision. Zero other questions.

The single hinge question

The one question per beat is a hinge question: a single check whose answer tells you whether the user is ready to move on or the beat needs re-explaining. Design it so that:

• It is answerable in one breath — approve / change X / explain more — never an open-ended prompt.
• Each option is legible without a glossary (plain wording, no unglossed terms).
• A genuine misunderstanding produces a DIFFERENT answer than genuine agreement. That gap is what makes the answer diagnostic rather than decorative: if someone who misunderstood the beat would still say "approve", the question tested nothing. Phrase it so that the wrong mental model lands on a different option than the right one.

The user is your audience of one; their verdict is the response you read.

The loop

1. Map the beats. Read the target file. List its sections / decisions in order. Each becomes one beat (split any section holding multiple decisions).
2. Present ONE beat. Under the beat contract above. Then stop.
3. WAIT for the verdict. Do not present the next beat, do not preview it, do not narrate what is coming. Silence until the user responds.
4. Write the verdict to the plan file BEFORE the next beat. Write decisions down the moment they are made: a decision that lives only in chat is lost on the next context compaction or /clear. Route by verdict type (next section).
5. Next beat. Repeat from step 2 until every beat is ratified.
6. Close. One-line summary: N beats ratified, file path, any beat the user parked for later.

Write the verdict (route by type, in the same beat)

• Strategic / anti-relitigation choice locked (a fork settled, a constraint fixed, an approach superseded): append a six-field Locked Decision to the plan file's ## Locked Decisions section. Fields: Decision / Context / Alternatives / Rationale / Rejected / Consequences. Rejected is mandatory — it records what was explicitly turned down and why, so the choice is not relitigated later.
• Operational choice (ordering, a threshold value, what is active vs parked): update the resume pointer or the relevant status line in place.
• "Change X" verdict: make the edit the user asked for, then re-present the revised beat for a fresh verdict. A changed beat is not ratified until they approve the new version.
• "Explain more" verdict: it is NOT a no. Re-explain plainer (drop a term, add a plain gloss, shrink the scope), then re-ask the same hinge question. Do not advance.

Writing the verdict is part of the beat, not a batch at the end. If the session died between two beats, every ratified verdict must already be on disk.

Anti-patterns (the exact things this skill prevents)

• The dump. A beat carrying multiple decisions, a wall of prose, or findings plus a named pattern plus a fix all at once. That is not a beat, it is a data-dump the user cannot act on. One decision, one question.
• Unglossed jargon. Any specialized term stated without its plain meaning in the same sentence. If the user would have to look it up, the beat failed.
• Racing ahead. Presenting the next beat before they ruled on this one, or batching several beats "for efficiency." The waiting IS the method.
• Verdicts stuck in chat. Moving to the next beat before the last verdict is written to the file. Chat is not durable; the plan file is.

What this is NOT

Not a plan author (it walks through an EXISTING file; it does not build one). Not an unattended runner (that executes a decided plan on its own; this is the opposite, a human ratifying every step). Not a lecture: the user decides each beat, you present and record.