Two-axis senior reviewer. Axis 1 (standards, "is it built right?") runs 6 specialized parallel sub-agents (Security, API/CRUD, Pattern enforcement, Simplicity, Reuse/DRY, Test hygiene) producing a severity-based report. Axis 2 (spec & behavior, "is it the right thing?") runs a 7th fresh-context sub-agent producing a behavior-change confirm-list for the human. Axes are never merged. Scoped to the current branch's diff against `main`. Adapted from zora-pantheon `.claude/commands/review-pr.md`.
73%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Fix and improve this skill with Tessl
tessl review fix ./.agents/skills/review-pr/SKILL.mdPerforms a rigorous code review focused on Security, API consistency, pattern conformance, simplification, and test hygiene — followed by a collaborative GitHub commenting process.
CRITICAL RULE: You MUST ONLY review code from the $ARGUMENTS branch's — or the CURRENT branch's if no arguments were given — commits that diverge from the target branch (usually main).
Steps:
git fetch origin first to refresh remote refs, so the scope is computed against the real target tip and not a stale local main. Do NOT rebase or modify the current branch.git branch --show-current to identify the current branch.git merge-base origin/main HEAD to find the common ancestor (fall back to git merge-base main HEAD if there is no origin remote).git log --oneline <merge-base>..HEAD to list ONLY the commits unique to this branch.git diff <merge-base>..HEAD --name-only to get the list of changed files.This ensures the review is focused, actionable, and doesn't generate noise from pre-existing code.
Action: Scan the repository to identify existing tools and architectural patterns. For this repo specifically, read CLAUDE.md and docs/diary.md (the live ADR record).
Goal: Determine established conventions (export styles, error handling, the in-repo pipe() / Result<T,E> helpers per ADR-024, security-header stack per ADR-013).
Also build a reuse catalog the Reuse & DRY auditor (Agent 6) will match new code against: the shared helpers, utilities, VOs, and repository methods that already exist near the diff. Note the barrels/index files that export them (e.g. packages/domain/src/index.ts, packages/http/src/, packages/application/src/) and any workspace-level shared packages, so "this could have called an existing helper" findings cite the exact export that should have been reused.
Action: Summarize the branch's changes (scoped to commits from step 0), focusing on new endpoints, DB queries, security-critical code paths, and any cross-cutting concerns.
Agents 1–6 are Axis 1 — Standards ("is it built right?"). Agent 7 is Axis 2 — Spec & Behavior ("is it the right thing?"). The two axes answer orthogonal questions and their findings are never merged, co-ranked, or interleaved: Axis 1 feeds the severity report (§5); Axis 2 emits its own confirm-list (§5b). A change can pass one axis and fail the other.
All agents MUST only analyze code within the branch scope defined in step 0.
Audit for injection of every kind the stack admits (SQL/NoSQL, command, template, prompt). Ensure strict input validation and output encoding at every trust boundary; check authentication, authorization, and secret handling on each changed path. Then check the diff against whatever security decisions this repo has recorded in docs/adr/ — for this repo at minimum ADR-013 (security-header stack on every viewer response), ADR-014 (service-worker block at the edge), ADR-015 (SVG rejection), ADR-016 (API-key scopes) — and cite them by number.
Agentic skill surface audit — OWASP Agentic Skills Top 10. When the diff touches an agent-facing surface — skills, prompts, hooks, the constitution/AGENTS.md, agent settings or tool configuration (at minimum the set BEHAVIOR_DELTA_SURFACES in scripts/guards.config.sh enumerates, plus any agent-facing prompt text living outside that list — that policy file is consumer-owned, so treat it as a floor, never the boundary) — the changed instruction text itself is attack surface and gets this additional audit. Cite findings by AST number the same way ADRs are cited. Review the semantics of instruction text, never keywords: pattern-matching scanners are exactly what AST08 documents as trivially bypassed, so the question for every changed instruction is "what would an agent following this actually do, and on whose authority?"
curl | sh, unpinned installs, or setup that executes before/without user consent in a skill's scripts or hooks (CRITICAL); version-unpinned or hash-unverified dependencies a skill relies on, where a later upstream change silently changes what runs (HIGH).AGENTS.md, constitution, settings, other skills or memory files) that the skill's purpose does not require. A skill that edits the rules future sessions run under is privilege escalation, not convenience — least-privilege applies to instructions exactly as it does to code.description that under-states or misrepresents what the body does (the description is what decides the skill gets loaded, so the mismatch is the vulnerability), and any frontmatter or manifest built from untrusted input.Shell-hazard audit — when the diff touches shell code or operator-facing command snippets. Two shapes with reproduced data-loss incidents in this framework's own history; judge each changed command by what it does on FAILURE, not success, and cite constitution/shared-code-craft.md §11–§12 by number the way ADRs and AST numbers are cited:
> aimed at a file the repo or operator cannot lose, fed by a command that can fail — the redirect empties the target before the producer runs. Scratch-then-move is the fix; flag the bare form even when today's producer "cannot fail", because the next edit changes the producer, not the redirect."$REF:x" forms). The finding is the unpinned form itself, never whether the author's own shell happens to bite today — the operator's shell is not the author's.Verify CRUD symmetry, HTTP status codes, and DTO data leaks. For this repo, also check OpenAPI contract changes (docs/api/openapi.yaml) when API routes change.
Check adherence to existing patterns. Identify code that can be simplified or modularized. For this repo, specifically: ADR-024 (no fp-ts/Effect/Remeda — vanilla TS + in-repo pipe() and Result<T,E>), ADR-020 (hexagonal — domain has no I/O), readonly on domain types.
Actively look for ways to reduce code complexity and volume. For every piece of new code, ask: "Is there a simpler way to achieve the same result with less code?" Prioritize:
The goal is: less code to read, less code to maintain. Simpler code is easier to review, test, and debug.
The single most important lens for this repo: new code must reuse what already exists before it reinvents it. Using the reuse catalog from step 1, for every new function, type, constant, query, or block of logic in the diff, ask: does an equivalent already exist in the codebase, and should this have called it instead?
Flag, with the exact existing export/file:line that should have been reused:
pipe()/Result<T,E> helper that's already exported (ADR-024). Cite the existing one.canWrite checks, pagination/has_more handling) pasted across two or more changed files, or pasted from an existing file the diff clearly mirrors. Recommend extracting once and calling it from both sites.resource mapper.Distinguish genuine duplication worth removing from incidental similarity (two short blocks that look alike but are coupled to different concerns and would be wrongly fused by a shared abstraction). Do NOT recommend a premature shared abstraction for a single occurrence — that contradicts Agent 4. The bar is: an existing reusable thing is right there, OR the same non-trivial logic appears in ≥2 places in this diff. When in doubt about whether extraction is worth it, state the trade-off rather than asserting.
When the PR includes test files, this agent MUST:
vitest.config.ts) and check for setupFiles or setupFilesAfterFramework entries.it() block.it('should [expected behavior] when [condition]').Common examples of duplication to flag:
setupFiles.console, fetch) already stubbed in setup files.beforeAll / beforeEach hooks that mirror global setup behavior.Cite surviving mutants, not taste, whenever packages/domain source changed. Points 5–7
ask you to judge whether a test is load-bearing, and an opinion on that ("this assertion
looks weak") is cheap for an author to argue with. There is a machine answer, so use it:
scripts/mutation-delta.shIt scopes a Stryker run to the pure-domain source files this branch changed and prints
the mutation score plus every surviving mutant with file:line and the mutator — a mutant
that survives is production behavior Stryker deleted or inverted with no test failing
(ADR-0081). When the branch changed no domain source it says so in under a second and runs
nothing, which is the common case. If this PR is stacked on another branch, pass that
base — scripts/mutation-delta.sh <base-branch> — because the origin/main default would
scope the run to everything since main and credit the branch underneath's mutants to this
PR.
How to use its output:
[file:line] <Mutator> survives — <what the mutant changed>, no test failed. HIGH
when the mutant sits in code this branch added or changed (the branch shipped behavior
nothing checks); MEDIUM when it is pre-existing (real, but not this PR's regression).thresholds.break is null on purpose:
this is a diagnostic, not a gate, and the score drifts run to run (the property tests
seed from the clock — ADR-0081 §5). Report mutants, which are reproducible; a score
movement of ~0.1 pp is noise.packages/domain only (ADR-0081 §2), so
points 1–8 still apply across every other tree in the diff.The one agent whose job is the question the other six never ask: did anything change that nobody asked for?
Context isolation (non-negotiable): this sub-agent runs with a fresh context and receives ONLY:
merge-base...HEAD) scoped to the contract artifacts below.Part of #N references) and any ADRs the diff touches. When reading a PR description, stop at the marker line <!-- explain-diff-appendix --> where present: /implement appends the author's /explain-diff narrative below it, and the implementer's narrative is exactly what this agent's context isolation exists to exclude. A body without the marker is read whole — an ordinary --- rule is formatting, never a boundary.scripts/behavior-delta.sh (the deterministic candidate list) and of
scripts/mutation-delta.sh (the mutation delta over the changed domain source).It must NOT receive the other six agents' findings, the implementation conversation, or this skill's earlier summarization — anchoring on the implementer's narrative is exactly what it exists to avoid.
The contract artifacts. Behavior lives in them, so behavior changes are machine-visible in them. This repo's list is data, not prose: it is BEHAVIOR_DELTA_SURFACES in scripts/guards.config.sh, and scripts/behavior-delta.sh inventories exactly that set. Read the policy file rather than assuming the table below; it is a starting shape, not the authority.
| Behavior surface | Artifact | Red flag |
|---|---|---|
| Observable behavior | existing *.test.ts / tests/e2e/features/*.feature | an edited existing assertion is by definition a behavior change (new tests are additions; edits are the signal) |
| API surface | docs/api/openapi.yaml | any delta: fields, params, status codes |
| Error semantics | packages/http problem+json model (ADR-0040) | changed problem types / status mappings |
| Domain events | docs/events.md + emit sites | payload/name changes |
| Persistence | packages/db migrations + docs/db-design.md | column meaning, defaults, constraints |
| Configuration | packages/env Zod schemas (ADR-0043) | new/changed defaults, removed vars |
| Security posture | packages/headers (CSP, Trusted Types) | any header delta |
| Agent-facing surface | apps/mcp instructions / tool descriptions / packaged SKILL.md (ADR-0072) | any prompt-surface delta |
| Process & agent surfaces | .agents/skills/** (and its .claude/skills/ symlink bridge), constitution/**, root and nested AGENTS.md, .husky/**, scripts/** | skills/hooks/gates/standing instructions change how every future session behaves — same confirm treatment; an edited constitution rule with no spec reference is an unapproved policy change, not a docs tidy-up |
Procedure: run scripts/behavior-delta.sh for the grounded candidate list and
scripts/mutation-delta.sh for the mutation delta, read each candidate's diff hunk, then
classify every behavior delta against the originating spec:
Missing requirements (spec asked, diff doesn't deliver) are also Axis-2 findings, tagged ❌ MISSING.
Commit separation (shared-invariants.md §10 — refactoring and behavior never share a commit) is the one Axis-2 finding class that is about the history rather than the diff, so it is classified per commit, not per surface. scripts/behavior-delta.sh emits it as its own Commit separation section: commits whose Conventional Commit type claims structure-only work (refactor, style) while that commit's own diff touches a contract artifact. Each listed commit is a confirm-list item tagged 🔀 MIXED COMMIT. The script has already established the fact — do not re-derive it and do not resolve it yourself; report the commit, the artifacts it touches, and let the human choose between splitting the commit and relabelling it. An empty section is the normal result and needs no mention.
The mutation delta closes the list with the one thing the other tags cannot state: whether the behavior above is actually enforced. scripts/mutation-delta.sh mutates the pure-domain source this branch changed and reports the score plus every surviving mutant (ADR-0081 §1 — the diagnostic that feeds this list). Emit its result as exactly one 🧬 MUTATION line, always — including the skip, because "this branch changed no domain source" is itself information the human wants confirmed. It is not a classification and takes no ✅/⚠️: it is a measurement of the list, so it goes last, after the tagged items it qualifies. Never assign it a severity, never let a score decide anything, and do not restate the individual mutants here — Agent 6 owns those as Axis-1 findings (a surviving mutant is a standards problem: the tests are not load-bearing). Axis 2's use of the number is narrower and specific: a ⚠️ UNSPECIFIED behavior change in a file that also carries survivors is unrequested behavior that nothing is checking, and the human should see those two facts on the same screen.
Constraint: Ignore nitpicks. Focus on vulnerabilities, broken contracts, major pattern deviations, code duplication / missed reuse of existing helpers, duplicated test setup, missing tests, redundant tests, and simplification opportunities that meaningfully reduce code volume or complexity.
Justified vs. unjustified deviations (borrowed from /review-and-evaluate): before reporting any deviation from an existing pattern, decide whether it is intentional and better or accidental. A deviation that is an improvement over the pattern it mirrors — stronger typing, better error handling, an ADR that explicitly sanctions it — is not a finding; drop it or, at most, note it as a deliberate improvement. Only surface deviations that are accidental, that break consistency without benefit, or that contradict an ADR. When you cite an ADR (from CLAUDE.md, docs/adr/, or docs/diary.md), include its number so the reasoning is auditable. This keeps the report free of noise where the author already made a considered call.
(High-signal filtering applies to Axis 1 findings only — Axis 2's confirm-list is exhaustive by design: every behavior delta appears, tagged, because "small note nobody flagged" is precisely how unrequested behavior changes slip through.)
After all agents complete, you MUST present the Axis 1 (standards) findings as one report following the output contract below. The report is GitHub-flavored markdown and nothing else — the same bytes render in the terminal and as PR-comment text wherever a host posts them (§6 says what this skill itself posts, and Axis-1 findings go inline there), so: no ANSI escapes ever, no raw HTML beyond the <details>/<summary> fold, tables kept to two or three columns so a phone does not scroll them.
Summary first. The reader decides "is this blocked, and what do I fix first?" in the first screenful, before any finding detail:
### Review Summary
**Verdict:** <one line — blocking or not, and what to fix first; "no findings" is a valid verdict>
Clean audits: <the lenses that found nothing, comma-separated — one line, never sections of nothing>
| | Severity | Count |
|---|----------|-------|
| 🔴 | CRITICAL | X |
| 🟠 | HIGH | X |
| 🟡 | MEDIUM | X |
| 🔵 | LOW | X |The badge is redundant encoding: the text label always accompanies it, because color is never the only channel a reader has. The count table is the exhaustive record — all four buckets always appear, zeros included. The severity buckets keep their meanings: CRITICAL is vulnerabilities, data leaks, broken functionality, divergent duplicate logic already drifted into a latent bug; HIGH is missing tests, broken contracts, major pattern violations, a reimplemented helper duplicating an existing export; MEDIUM is redundant tests, unnecessary complexity, copy-paste blocks worth extracting once; LOW is minor simplifications and style.
Then the findings — all four severity sections, always, in this order, headed by badge + label: #### 🔴 CRITICAL, #### 🟠 HIGH, #### 🟡 MEDIUM, #### 🔵 LOW. An empty section carries exactly one line — — none found. — so absence is stated, never inferred, and the reader's eye learns where each bucket lives. Each finding uses this anatomy:
#### 🟠 HIGH
**H-1** `path/to/file:42` — one line: what is wrong, readable in isolation
↳ cites: <the decision record, audit item, or craft rule that makes this a finding>
↳ fix: <the change the review wants, one line>
<details><summary>evidence</summary>
the longer proof — a mutation transcript, a failing command, an excerpt
</details>
**H-2** `path/to/other:7` — next finding, same anatomyAnatomy rules:
file:line anchor (clickable in both mediums), one line that makes sense in isolation.↳ cites: and ↳ fix: appear only when the review actually has them — never padded with filler.Immediately after the severity report — separated by a horizontal rule and under its own header, so the axes are unmistakable on the page — present Agent 7's output verbatim in this shape, 🔀 items first, then ⚠️. The list's inner shape is a machine contract, not a style: glyph + TAG at the start of the line, one item per line, so the human-only items can be lifted verbatim by whatever reads this report next. Presentation may improve around these lines, never inside them — and in particular they never become table cells, which would break the lifting.
### Behavior changes in this PR — confirm before merge
🔀 MIXED COMMIT <short-sha> <commit subject>
→ claims refactor/style but touches <artifacts>. Split or relabel?
⚠️ UNSPECIFIED <surface>: <what changed, one line>
→ no spec reference found. Desired?
✅ SPECIFIED <surface>: <what changed, one line>
→ <PRD/ticket/ADR citation>; <artifact updated>
❌ MISSING <spec line the diff does not deliver>
🧬 MUTATION <score> over <N> changed domain source file(s) — <M> surviving mutant(s)
→ the branch's domain behavior, as enforced by its tests (ADR-0081)The 🧬 line when the branch touched no pure-domain source — still printed, never omitted:
🧬 MUTATION no domain source changed — mutation run skippedRules: never assign severities to these items, never mix them into the C/H/M/L lists, never omit a ✅ (the human should see the whole behavioral footprint, not just the suspects). 🔀 items come first — they are the cheapest to act on and the reason the rest of the list is hard to read. 🧬 comes last and appears exactly once: it measures the list rather than joining it, and it is the only line that is never a question for the human. If Agent 7 found no behavior deltas, say exactly that — an empty confirm-list is a meaningful result (the 🧬 line is still printed under it).
After presenting the summary, you MUST ask:
"Which categories or specific items do you want me to post as comments on the PR? (e.g., 'all H', 'C-1 and H-3', 'all')"
gh api repos/{owner}/{repo}/pulls/{number}/reviews with the comments array. (Axis 1 findings only.)gh api) if the diff changes.line (line number in the file at HEAD) and side: "RIGHT" for each comment.gh api call using the comments array, so they appear as a cohesive review rather than scattered individual comments.gh api call using the comments array. Never post a summary comment — only inline comments per finding.Closing: Restate the verdict in one line — the reader answers the question below without scrolling back up — and then you MUST end the response with: "Review complete. Which severity categories or specific items should I post as GitHub comments?"
agranado2k/ai-report-platform
caeb0da
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.