Walkthrough

Walkthrough

Explain a completed change with a few annotated visuals. Run this after final verification. A walkthrough explains proof; it does not replace proof.

Honor The Caller Contract

The caller decides whether the walkthrough is required. Follow the stricter repo rule when one exists.

For UI-gated workflows, treat app pages, websites, components, styles, visual content, and generated or rendered output as UI changes. If the packet changed one of those surfaces, run the walkthrough in the final handoff.

When the caller requires a walkthrough and it cannot be produced, block closeout with the exact missing tool, access, or artifact. Do not waive it silently.

When the caller requires a diff check and no relevant UI or rendered-output change exists, record:

Walkthrough: N/A — no UI or rendered-output change in this packet.

Record A Diff Baseline

For a diff-gated workflow, capture the baseline before the first file mutation, including plan creation:

node .agents/skills/walkthrough/scripts/diff-baseline.mjs capture \
  --output tmp/walkthrough/<slug>/baseline.json

At closeout, compare the final checkout with that baseline:

node .agents/skills/walkthrough/scripts/diff-baseline.mjs compare \
  --baseline tmp/walkthrough/<slug>/baseline.json \
  --output tmp/walkthrough/<slug>/diff-receipt.json

Use producedFileDiff for the file-diff gate. Use changedPaths and the final diff to decide whether UI or rendered output changed. The receipt detects committed clean-tree changes, tracked working changes, executable-bit changes, symlink changes, and untracked files without git status.

Keep receipts local. Do not publish file hashes. If an older packet has no baseline, reconstruct it from the recorded starting commit or base ref and the packet's changed-file ledger. Mark the receipt as reconstructed. New packets must capture the baseline before mutation. The helper excludes its own baseline and receipt paths from the comparison, but the output directory should still be ignored by the repo.

Read The Minimum Evidence

Read only what explains the completed result:

• the latest request and acceptance criteria;
• the baseline, diff receipt, and final diff;
• final screenshots or rendered proof already captured;
• the final route, role, data fixture, viewport, theme, or source artifact.

Reuse valid final-state screenshots. Do not rerun an expensive flow only to capture the same state.

Pick The Shortest Story

Use one to four frames. Each frame should explain one point:

1. where the user acts;
2. what changed or became possible;
3. what consequence appears;
4. what proves the result.

Prefer the shortest sequence a non-developer can understand in under one minute. Do not turn every field or test into a callout.

Capture The Real Artifact

For UI or rendered-output changes:

• capture the real final affected surface in its verified state;
• preserve the correct role, data, viewport, theme, and open or selected state;
• use the repo-required browser or capture tool;
• reuse existing final proof when it shows the required state.

For an explicit walkthrough of non-UI work, render the real final source, diff, report, document, CLI result, or provider read-back. Never invent a product screen to make backend or workflow work look visual.

Prefer light mode when both themes are equally truthful. Keep the verified theme when the change concerns dark mode or switching would misrepresent the result.

Save originals and annotated copies under a repo-approved ignored directory. Default to:

tmp/walkthrough/<slug>/

Use paired names:

01-<step>-original.png
01-<step>-annotated.png