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.