review-map
Skill315 starsChanged 31 days agoApache-2.0View on GitHub
On-demand visual walkthrough of a pull request for a reviewer — projects the diff onto the system architecture map (changed components highlighted, before/after flows, suggested reading order) and publishes it as a private HTML artifact. Use when a diff is too large or system-touching to hold in your head while reviewing.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- wyeworks/accountable-reviewtheir own version, first seen Oct 2, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- wyeworks/accountable-review★ 42same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- frontend/AGENTS.mdAGENTS.md
- llms.txtllms.txt
- agent-capabilitySkill
- agent-specSkill
- alembic-migrationSkill
- backend-testsSkill
- background-taskSkill
- channel-botSkill
- dev-agentSkill
- e2e-testsSkill
- frontend-featureSkill
- mcp-connectionsSkill
- permissions-rbacSkill
- pr-commentsSkill
- pr-descriptionSkill
- project-docsSkill
- rag-knowledgeSkill
- resolve-changelog-conflictSkill
- ste-writingSkill
- vault-secretsSkill
- vstorm-code-reviewSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Locate it on the map: Read docs/architecture.md (routes → services → repositories, DI, the request transaction, background dispatch) and …
- Distinctive: line 79
Accuracy over polish: Every box you light up and every "before" you draw must match the actual code and the doc's diagram — a confident but …
- Very specific: line 83
Reuse the doc's diagram: Do not redraw the whole system.
- Distinctive: line 85
Ephemeral and private: Never post the artifact URL to the PR, commit it, or treat it as a deliverable.
- Distinctive: line 90
If a diff is trivial, say so and skip the artifact rather than manufacturing one.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill: Review Map
Turn a hard-to-hold-in-your-head pull request into a private, visual walkthrough so a reviewer can grasp what changed and how it moves through the system before reading the diff line by line.
This is a per-reviewer comprehension aid, not part of the PR record: the artifact is
private to whoever runs the skill and is meant to be discarded after the review. It changes
nothing in the repo or the PR. Contrast with pr-description (durable, for everyone) — this is
scaffolding for one review, today.
Inputs
PR number — optional. With one, review that PR (
gh pr diff <n>,gh pr view <n>). Without one, review the current branch against its own base, which is not necessarily the repository default: a stacked branch targets its parent, and comparing it againstmainfolds the parent's whole change into this walkthrough, corrupting the components, the risk and the reading order.BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null) \ || BASE=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name) git fetch origin "$BASE" git diff "origin/$BASE"...HEAD
Steps
- Gather the change. The diff, the commit log, the PR body if it exists, and the list of changed files with hunk locations.
- Locate it on the map. Read
docs/architecture.md(routes → services → repositories, DI, the request transaction, background dispatch) and themermaiddiagrams embedded in it. For a frontend-only diff, also checkdocs/frontend.md; for RAG/ingestion,docs/rag-knowledgetopics viadocs/file-processing.md. Identify which components (boxes) and interactions (edges) the diff touches. There is no separate ADR log in this repository — the closest record of why a boundary exists isdocs/about/design.md("the six decisions that shape the codebase") and the Hard boundaries section ofAGENTS.md; cite those where relevant instead of an ADR number. Prefer reusing the existing diagrams over inventing a new topology. - Build the walkthrough as a self-contained HTML page. Load the
artifact-designskill first where the session has it; it comes from the host, not from this repository. It must contain, in this order:- Changed components on the system map — the architecture diagram with the boxes and
edges this PR touches highlighted; everything else dimmed. Redraw the touched slice as
inline SVG in the page (the source lives as a
mermaidfence indocs/architecture.md— use it as the reference topology). The reader must see "this PR lights up these parts of the system." - Before → after flows for each changed interaction — a small side-by-side (or
annotated) sketch of the sequence/topology as it was and as it becomes. The diagram in
docs/architecture.mdgives you the "before" to derive from. - Suggested reading order — the changed files grouped by layer (routes → services → repositories, or the frontend's data layer → store → component), ordered so the reviewer reads foundations before callers, with risky hunks flagged (a new permission gate, a transaction-boundary change, a spec/schema change, a migration, a vault/credential path) and a one-line "why read this next" per group.
- Anchors back to the code — link each file/group to its path (and line where useful)
and cite the governing rule under
.claude/rules/or the hard boundary inAGENTS.mdit touches.
- Changed components on the system map — the architecture diagram with the boxes and
edges this PR touches highlighted; everything else dimmed. Redraw the touched slice as
inline SVG in the page (the source lives as a
Publish it with the
Artifacttool, where that tool is available to the session (it starts private). Hand the reviewer the URL and a two-line orientation: where the change lands on the map, and where to start reading.Neither the
Artifacttool nor theartifact-designskill ships in this repository - both come from the host session - so a clean checkout has to be able to finish without them. Where they are absent, write the same page as a self-contained HTML file in the scratchpad directory (one file, inline CSS and inline SVG, no external requests) and hand over that path instead of a URL. The deliverable is the walkthrough, not the hosting.
Rules
- Accuracy over polish. Every box you light up and every "before" you draw must match the
actual code and the doc's diagram — a confident but wrong map is worse than no map. When the
diff and a diagram disagree, say so: the diagram may be stale (worth flagging via
scripts/docs_drift.pyor a follow-up), or you may have misread the diff. - Reuse the doc's diagram. Do not redraw the whole system; start from the
mermaiddiagram indocs/architecture.md(or the relevant topic page) and mark the delta. - Ephemeral and private. Never post the artifact URL to the PR, commit it, or treat it as a deliverable. It is a lens for one reviewer.
- Scale to the diff. A small, single-layer PR may only need the reading order and one before/after; reserve the full map for genuinely large or cross-cutting changes (touching routes, services, repositories, and the frontend together, or a migration plus a spec change). If a diff is trivial, say so and skip the artifact rather than manufacturing one.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

