feat(agents): add PR Walkthrough narrative orientation agent

Summary

Proposing a new PR Walkthrough agent that produces narrative-driven PR orientations: a single continuous essay that walks a reviewer through the diff architecture, surfaces design forks for human judgment, and generates structural appendices (triage map, implicit bets, layer summary).

Motivation

Over the last few months, a pattern has been accelerating on my team and on every team I talk to: agents write most of the code now. The bottleneck of producing code has largely disappeared. What hasn't disappeared is the bottleneck of understanding it. PRs that touch 10, 20, 50 files are becoming routine rather than exceptional, and the person reviewing them still has to build a mental model from scratch every time. I've been experimenting personally for the past couple of months with a "code review as narrative" approach, treating the walkthrough as something closer to a technical blog post than a checklist. It makes the orientation phase engaging instead of menial, and it scales to large diffs in a way that file-by-file scanning does not. This agent is the generalizable distillation of that experiment.

The research aligns. Bacchelli & Bird (ICSE 2013) showed comprehension, not defect detection, is the dominant cost of code review. Zhong et al. (2026, 278K review conversations across 300 GitHub projects) found AI agents miss "understanding, testing, and knowledge transfer feedback" entirely, with over 50% of unadopted AI suggestions being simply incorrect. Cihan et al. (2024, 4,335 PRs) found AI review increased PR closure time by 42% despite most comments being resolved. The tools find surface issues but don't help the reviewer orient. Kamal─▒ et al. (2026) name the gap: "Current AI support in code review remains fragmented, with tools focusing on isolated tasks rather than the end-to-end PR review workflow."

Google's engineering practices formalize this as a deliberate workflow: orient first, then inspect. The existing PR Review agent addresses inspection (findings, bugs, standards). This proposal addresses orientation: a narrative that gives the reviewer the mental model before they start reading diffs, makes the experience educational and interesting rather than robotic, and works for 5-line PRs and 2,000-line PRs alike.

How it differs from existing agents

Modes of operation

• Standalone: Invoked directly against any PR or branch diff.
• Orchestrated: Called as a subagent by PR Review, reading diff-state.json and writing output to the specified findings folder.

Output structure

1. Title + subtitle: Names the technical subject with sharp framing; one-sentence scope/stakes context.
2. Narrative body: Continuous prose organized around decisions (not files). Code quoted inline as evidence. No bullet lists in the body.
3. Design forks: Named judgment calls with explicit "what would settle it" framing.
4. Implicit bets: Assumptions the PR makes that the reviewer should agree with or push back on.
5. Triage map: Must-read / Skim / Trust-the-tests file classification.
6. Layer summary: The diff compressed into 3-5 architectural layers.

Acceptance criteria alignment

Per docs/contributing/custom-agents.md:

• Fills a gap: No existing agent produces narrative orientation output. The PR Review parent and its subagents (functional reviewer, standards reviewer) produce findings, not mental-model construction.
• Non-overlapping: Different output type, different organizing principle, different reader goal.
• Cannot be merged into an existing agent: Structurally incompatible with findings-based review. A narrative essay and a severity-tagged findings list are different artifacts.
• Not in auto-reject categories: Not a research, indexing, planning, or implementation agent.

Example output

Example outputs attached below, generated against merged PRs across repos:

• hve-core #1920: 5 lines, 1 file (demonstrates proportional scaling for small changes)
• vscode #321259: 144 lines, 7 files (demonstrates cross-repo capability and security domain)
• TypeScript #63538: 1,074 lines, 13 files (demonstrates large-PR handling and design fork extraction)

Implementation details

• Single file: .github/agents/hve-core/pr-walkthrough.agent.md
• No subagents, no skills, no instructions files
• Uses pr-reference skill for diff computation (already exists in repo)
• Collection manifest update included in the PR

Acceptance criteria

• Agent passes npm run lint:frontmatter
• Agent passes npm run lint:all
• Registered in hve-core collection manifest
• npm run plugin:generate succeeds with the new entry
• Output demonstrated against at least one small and one large PR on this repo