kandev/docs/specs/pr-walkthrough/spec.md

status, created, owner

status	created	owner
building	2026-08-22	kandev

Pull Request Walkthrough Generation

Why

Reviewers can inspect a diff in GitHub, but a large pull request still takes time to understand. Kandev should generate a visual explanation that gives a reviewer the change context, architecture, important code paths, risk, and review focus before they read the full diff.

This increment generates the walkthrough HTML in CI and publishes the HTML to the dedicated Cloudflare R2 walkthrough bucket. The hosted file remains available after the pull request merges and expires through the bucket lifecycle policy.

Decisions: ADR-2026-08-22-pr-walkthrough-r2-hosting, ADR-2026-08-22-agent-owned-pr-walkthrough-rendering, ADR-2026-08-22-pr-walkthrough-description-link

What

• A project skill named pr-walkthrough is available to compatible agents.
• The skill produces one JSON data file and one HTML file for a pull request: docs/pr-walkthrough/pr-<number>.json and docs/pr-walkthrough/pr-<number>.html.
• The JSON describes the pull request, why it exists, an optional architecture diagram, key code changes, data or storage, risk, trade-offs, and review focus.
• The renderer builds the HTML from the JSON and fixed renderer assets. It escapes code and prose, validates required fields, validates node edges, and rejects unreplaced template tokens.
• The generated page contains a vertical reviewer story, a dark and light theme, architecture and data diagrams when supplied, highlighted code, diff tinting, GitHub file links, an interactive code canvas, and a linear fallback list.
• The configured workflow agent generates and renders the walkthrough for a non-draft same-repository pull request when it is opened, reopened, or marked ready for review. OpenCode is the initial runner, but the skill and artifact contract do not depend on it. A maintainer can explicitly retrigger generation by adding the generate-pr-walkthrough label.
• Walkthrough automation lives in .github/workflows/pr-walkthrough.yml and is enabled independently with the PR_WALKTHROUGH_ENABLED repository variable. It does not share the OPENCODE_REVIEW_ENABLED code-review gate.
• The initial runner uses opencode-go/muse-spark-1.2-contributor#high. OpenCode 1.17.7 reports native reasoning support for the model and resolves #high to its built-in high reasoning variant.
• The workflow preserves the generated JSON and HTML as CI artifacts and uploads only the HTML to the kandev-pr-walkthroughs R2 bucket.
• Each published object uses the key pr/<pull-request-number>/<head-sha>.html and is served at https://walkthrough.kandev.ai/pr/<pull-request-number>/<head-sha>.html.
• The initial workflow does not regenerate on synchronize. Future per-push generation can add that event without changing the object contract.
• After public validation succeeds, a separate minimum-permission job prepends a prominent marker-owned walkthrough callout to the pull request description. A rerun replaces only that callout and preserves the rest of the description.

Generation contract

The walkthrough agent compares the exact pull request head SHA with the exact base SHA. It creates the JSON, invokes the trusted renderer, and corrects its data until both outputs pass renderer validation. The generated pr object includes the pull request number, title, URL, repository slug, base branch, head branch, and diff statistics when they are available. The managed runner binds identity and links to trusted event metadata before rendering.

Each code change includes a real repository-relative file path, a concise explanation, and at least one real code or rendered-Markdown block. Code excerpts come from the pull request head or its diff. The agent does not invent source code or present a review verdict.

The walkthrough is an explanation, not a code review. It does not approve, request changes, post findings, or claim that the pull request is safe to merge.

Permissions

• The workflow may read pull request metadata and repository contents.
• The selected agent reads the trusted base checkout and attached diff. A narrow base-controlled tool may read bounded regular UTF-8 files directly from the immutable pull request head Git object. The agent may not run arbitrary shell commands, read outside the trusted worktree, modify source files, invoke subagents, fetch external URLs, commit, push, or publish GitHub changes. A managed runner may expose a narrow trusted-renderer tool that writes only the fixed walkthrough JSON and HTML paths.
• The workflow checks out only the trusted base commit in the secret-bearing worktree. It fetches the event head SHA as a Git object without checking it out, and uses base-commit copies of the walkthrough skill, renderer, managed rendering adapter, and constrained file reader. Pull request changes cannot replace those instructions or executable generation components.
• The agent invokes the fixed renderer before it finishes. The workflow only verifies and packages the ignored walkthrough output directory.
• The R2 publishing job receives only the bucket-scoped S3-compatible R2 credentials required to upload the rendered HTML. The generation job does not receive R2 credentials.
• The PR-link job receives pull-requests: write, but no model or R2 credential. It checks out the immutable base commit and uses a trusted helper that validates the PR number, event head SHA, and exact walkthrough URL before constructing the GitHub API update.
• The public bucket contains only generated walkthrough HTML. It does not publish the JSON source artifact.

Failure modes

• If the selected agent command fails, exits non-zero, or does not produce both required walkthrough files, generation fails and the workflow records the diagnostic output in its CI artifacts.
• If the JSON is missing required fields, contains invalid edges or risk data, includes a reserved renderer token, or otherwise violates the renderer contract, the renderer fails and no HTML is treated as generated.
• If the renderer cannot read its fixed shell or cannot write the output file, the workflow fails rather than exposing a partial page.
• If optional browser validation is unavailable on the runner, the workflow still validates the generated file structurally and reports live browser rendering as unverified. HTML generation itself remains a required check.
• If the R2 upload, object metadata validation, or bounded-retry public URL check fails, the workflow fails and does not report the walkthrough as published.
• If the PR body contains malformed, duplicate, or non-leading walkthrough markers, the link job fails closed and does not rewrite contributor content.

Persistence guarantees

Generated JSON and HTML are ignored working-tree artifacts. They do not merge into main or become Kandev application state. The HTML is also published to R2 independently of GitHub artifact retention, so it remains available after the pull request merges. The initial lifecycle deletes objects under pr/ after 180 days from upload; this is intentionally measured from generation, not from merge time.

Scenarios

• GIVEN a non-draft same-repository pull request is opened, reopened, or marked ready for review, WHEN the walkthrough job runs, THEN it creates non-empty JSON and HTML artifacts and publishes the HTML under the current head SHA in R2.
• GIVEN a maintainer adds the generate-pr-walkthrough label, WHEN the label-triggered walkthrough job runs, THEN it regenerates the current PR head and updates the corresponding R2 object and job-summary URL.
• GIVEN a pull request receives a new head commit, WHEN the walkthrough workflow runs for the synchronize event, THEN no walkthrough generation occurs in the initial increment.
• GIVEN two pull requests use different numbers, WHEN both jobs run, THEN each output filename and R2 object key is distinct and neither run overwrites the other's result.
• GIVEN two walkthrough triggers target the same pull request, WHEN the newer workflow starts, THEN per-PR workflow concurrency cancels the older pipeline so publication and PR linking cannot race across runs.
• GIVEN the agent submits malformed JSON or a review verdict instead of the walkthrough contract, WHEN the managed renderer rejects it, THEN the agent must correct the data; the job fails without publishing if no valid output is produced.
• GIVEN a generated code excerpt contains HTML characters or a Mermaid label contains unsafe markup, WHEN the page is rendered, THEN the source is escaped or sanitized and no executable PR-controlled markup is inserted by the renderer.
• GIVEN a draft pull request or an unauthorized fork event, WHEN the workflow is triggered, THEN no walkthrough agent job runs.
• GIVEN a successfully generated HTML file, WHEN the publishing job uploads it, THEN a public GET to the reported URL returns the same HTML with an HTML content type.
• GIVEN a validated public walkthrough URL, WHEN the link job runs, THEN the first block in the PR description is a prominent walkthrough callout and all existing contributor content remains below it.
• GIVEN the walkthrough label regenerates the same or a newer PR head, WHEN the link job runs again, THEN it replaces the owned callout without duplicating markers or changing the remaining description.

Out of scope

• Publishing walkthrough screenshots or using the screenshot media branch.
• Generating a new walkthrough on every push. The initial synchronize path remains disabled to control model usage.
• Retaining a walkthrough for an exact period measured from merge time. The initial lifecycle is measured from upload time.
• Adding a Kandev UI page for externally generated PR walkthroughs.
• Replacing Kandev's existing in-app changes-walkthrough behavior.
• Adding a merge-approval or automated code-review verdict to the page.