# Walkthrough

> Create a concise, visual walkthrough of a branch, pull request, feature, code path, or architecture topic, with linked code evidence and manual test guidance. Use when the user asks for a walkthrough, change tour, PR explanation, onboarding map, implementation explanation, or help manually testing an affected UI. For UI changes, resolve the relevant application route and prepare an authenticated Chrome page for the user.

- Skill: `josephanson/walkthrough` (Agent Skill)
- Install (CLI): `npx skillmds@latest add josephanson/walkthrough`
- Raw SKILL.md: https://api.skillmd.com/api/skills/josephanson/walkthrough/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: JosephAnson (https://skillmd.com/u/josephanson)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/josephanson/walkthrough

---


# Walkthrough

Explain the real execution flow, generate a small self-contained HTML guide, and leave any affected UI open at the relevant state for manual testing.

## Workflow

1. Define the scope.
   - Use the named feature, files, route, issue, PR, or branch.
   - For a bare `$walkthrough`, explain the current branch changes against its merge base. If there are no changes, give a project overview.
   - Include committed and uncommitted changes. Preserve unrelated user changes.

2. Trace the implementation.
   - Read repository instructions first.
   - Inspect the diff, callers, routes, tests, and nearby existing patterns.
   - Follow the flow end to end; do not describe files independently when they form one path.
   - Keep only the 5–12 concepts needed for a new contributor to understand the change.

3. Identify the user-visible path.
   - Decide whether the scope changes UI or user interaction.
   - Derive every affected page's exact route and setup from router definitions, navigation, tests, fixtures, or the changed code. Do not guess a URL when it can be discovered.
   - Resolve the application origin from the review app, running development server, or repository documentation, then build an absolute URL for each affected page.
   - Write short manual test steps with expected outcomes and important edge cases.

4. Create `.walkthrough/index.html`.
   - Produce one self-contained file with inline CSS and JavaScript; add no dependency or build step.
   - Make it readable directly through a `file://` URL.
   - Include: title and scope, a 2–3 sentence summary, a simple flow/map, ordered explanation, linked file paths with line numbers, small code excerpts, tests or verification performed, and a manual-testing card when UI is affected.
   - When UI is affected, add an "Affected pages" section with a descriptive, clickable absolute `http(s)` link for every affected page. Link directly to the resolved route and preserve any safe query parameters needed to reach the relevant state.
   - Prefer native HTML, CSS, SVG, and `<details>` over a visualization library. Add interactivity only when it improves navigation.
   - Treat `.walkthrough/` as a local generated artifact; do not commit or publish it unless asked.

5. Validate the artifact.
   - Check that the HTML parses, referenced files exist, cited line numbers still match, and every affected-page link uses the resolved application origin and route.
   - Open the walkthrough in a browser and verify its main controls when browser access is approved.

6. Hand off browser testing for UI changes.
   - Invoke and follow `$chrome-cdp`. Treat the user's explicit `$walkthrough` invocation as approval for the browser interaction required by this workflow; do not ask for separate Chrome approval.
   - If this is a Provet Cloud review environment or the repository supports Provet review apps, also invoke and follow `$review-app` to resolve the branch URL, authenticate, and select the relevant organisation. Prefer the review app over starting a local server when it is available.
   - Otherwise, use the repository's documented development command and URL. Reuse an already-running server when possible.
   - Navigate Chrome directly to the affected route and prepare the nearest safe precondition for the test. Do not perform destructive or irreversible steps on the user's behalf.
   - Leave the tab open for manual testing. Report the URL, state prepared, test steps, and anything the user must finish.
   - If approval is denied or the environment is unavailable, still finish the walkthrough and report browser validation as unverified.

## Output

Return the walkthrough file path, one-sentence scope summary, and—when UI is affected—the opened application URL plus the shortest useful manual-test checklist. Do not paste the walkthrough's full contents into chat.