Skip to content

Ovid/paad / preview/paad/skills/agentic-review

agentic-review

Unverified

Use when reviewing current branch for bugs before pushing or merging, when wanting a thorough multi-agent review of local changes, or when preparing work for human review. Not for codebase structure, not for code style, and not for fixing what it finds.

references/report-template.md

View on GitHub
# Report Template — additional instructions

> **Read this file before writing the per-review report or updating the project backlog.** This is parent-side material for `/agentic-review` Phase 4. The orchestrator (the agent that activated this skill) reads these instructions when entering the report-writing phase — there is no subagent dispatch for this phase. The empty-section rules, failure handling, report template, and backlog file shape below are binding for the Phase 4 deliverable.

**Empty-section rules:**

- If there are zero out-of-scope bug findings of any tier, omit the entire `## Out of Scope` section *and* its handoff block. Review Metadata still records `Out-of-scope findings: 0`.
- If there are zero out-of-scope additions, omit the entire `## Out-of-Scope Additions` section *and* its handoff block. Review Metadata still records `Out-of-scope additions: 0`.
- If there are zero in-scope findings of a tier but out-of-scope findings exist, write each empty in-scope tier section as `None found.` (existing convention) and write the Out of Scope section normally.
- When the Spec Compliance specialist's output begins with the `BAIL: spec-compliance` token (matched tolerantly per the verifier's "Specialist status detection" section), set `Intent sources consulted: none — Spec Compliance skipped` in metadata. No specialist can produce additions in this case (only Spec Compliance emits the OOSA signal, and it didn't run), so the `## Out-of-Scope Additions` section is empty; omit it.
- When the Verifier emits one or more `verifier-warning:` lines (from `references/verifier.md` step 0 for missing-ref specialists, or from the Field-encoding rules section for malformed File/Symbol fields), render them as a **sublist** under the `Verifier warnings:` field of Review Metadata — one bullet per warning, each bullet's content verbatim from the Verifier's emitted line. The Verifier is responsible for ensuring each warning is exactly one line (the Field-encoding rules require it); do not split, rewrap, or comma-join. The `Verifier warnings:` line itself shows the count. When zero warnings, set the field to `none` and do not render a sublist.

**Failure handling:**

- If writing `paad/code-reviews/backlog.md` or `paad/security/backlog.md` fails for any reason (permissions, disk, malformed existing file), surface the error to the user and write the per-review report anyway. Only an **attempted-and-failed** write may skip the backlog, and only with the underlying error text shown to the user. Deferring it because context is short, or because the IDs already appear in the report, is a review defect.
- **Confirm the write before reporting it.** After writing the backlog, re-read each backlog file you wrote and check that every backlog ID printed in the report appears in the file its report names. The counts in Post-Review come from what you read back, not from what the Verifier directed you to write. If they disagree, report the discrepancy rather than the intended numbers.

**Report template:**

```markdown
# Agentic Code Review: <branch-name>

* **Date:** YYYY-MM-DD HH:MM:SS
* **Model:** <the model you are running as — from your environment; "unknown" if unavailable>
* **PAAD version:** <plugin version from your on-invocation announce line>
* **Branch:** <branch> -> <base>
* **Commit:** <full-sha>
* **Files changed:** N | **Lines changed:** +X / -Y
* **Diff size category:** Small / Medium / Large

## Executive Summary

2-3 sentences: overall assessment, highest-severity finding if any, general confidence level. A routed (`Bug class: Security`) finding appears here at most as "security-related, see the security report" — not its class, mechanism, symbol, path, severity beyond that, or the words that name the weakness. If it was the highest-severity finding, say only that the highest-severity finding is in the security report.

## Critical Issues

### [C1] <title>
- **File:** `path/to/file:line`
- **Bug:** What's wrong
- **Impact:** Why it matters
- **Suggested fix:** Concrete recommendation
- **Confidence:** High/Medium
- **Found by:** <specialist> (`<model>`)

(Repeat for each critical issue, or "None found.")

## Important Issues

(Same structure as Critical, or "None found.")

## Suggestions

One-line entries only. If empty, follow the Empty-section rules above.

## Out of Scope

> **Handoff instructions for any agent processing this report:** The findings below are
> pre-existing bugs that this branch did not cause or worsen. Do **not** assume they
> should be fixed on this branch, and do **not** assume they should be skipped.
> Instead, present them to the user **batched by tier**: one ask for all out-of-scope
> Critical findings, one ask for all Important, one for Suggestions. For each tier, the
> user decides which (if any) to address. When you fix an out-of-scope finding, remove
> its entry from the backlog that holds it by ID — `paad/code-reviews/backlog.md`, or
> `paad/security/backlog.md` when this is the security report.

### Out-of-Scope Critical
#### [OOSC1] <title> — backlog id: `<id>`
- **File:** `path/to/file:line`
- **Bug:** What's wrong
- **Impact:** Why it matters
- **Suggested fix:** Concrete recommendation
- **Confidence:** High/Medium
- **Found by:** <specialist> (`<model>`)
- **Backlog status:** new | re-seen (first logged YYYY-MM-DD)

(Repeat for each, or "None found.")

### Out-of-Scope Important
(Same shape — IDs OOSI1, OOSI2, ...)

### Out-of-Scope Suggestions
(One-line entries; each carries a backlog id — IDs OOSS1, OOSS2, ...)

## Out-of-Scope Additions

> **Handoff instructions for any agent processing this report:** The entries below are code this branch added that the spec did not promise. They may be legitimate "while I'm here" fixes for issues exposed by this work, or scope creep that should live in a separate PR. Do **not** assume they should stay on this branch, and do **not** assume they should be reverted. Present them to the user **as a single batched ask**: "These M additions weren't promised by the spec — keep, split into a separate PR, or revert?" The user decides per item.
>
> Out-of-scope additions are flagged for this PR only — they do not persist to either backlog.

### [OOSA1] <title>
- **File:** `path/to/file:line`
- **Addition:** What was added that the spec did not promise
- **Suggested intent source:** What the agent treated as the spec (PR description / plan doc / commits / branch name)
- **Confidence:** High/Medium
- **Found by:** Spec Compliance (`<model>`)

(Repeat for each, or "None found.")

## Review Metadata

- **Agents dispatched:** all six lenses, each listed by name with a status — `findings (N)` | `bailed: <reason token>` | `NOT DISPATCHED: <reason>`. Every lens appears every run; a lens that never ran leaves no other trace, so this field is the only place its absence can surface. Counts only — no finding is described on this line.
- **Scope:** <files reviewed — changed + adjacent. When Phase 1 steps 6-8 traced no adjacent files, write the literal string `no adjacent files traced` rather than listing only the changed files.>
- **Raw findings:** N (before verification)
- **Verified findings:** M (after verification)
- **Filtered out:** N - M <the number only. When a rejected or merged candidate was security-related, or was merged into a routed finding, its reason goes in the security report's copy of this line — which writes the security report even with no routed finding — and the main report says `reasons in the security report`. Otherwise the reasons may follow the number.>
- **Out-of-scope findings:** N (Critical: a, Important: b, Suggestion: c)
- **Out-of-scope additions:** K
- **Backlog:** X new entries added, Y re-confirmed (see `paad/code-reviews/backlog.md`)
- **Security:** N finding(s) written to `paad/security/<file>`; security backlog: X new, Y re-confirmed on this machine <omit this line when no security report was written>
- **Steering files consulted:** <list or "none found">
- **Intent sources consulted:** <e.g., "PR description", "docs/plans/foo-design.md", "recent commit messages", or "none — Spec Compliance skipped">
- **Verifier warnings:** <count, or "none". When > 0, render the warnings as a sublist below this line — one bullet per warning, each verbatim from the Verifier's emitted line. Example:>
  - `verifier-warning: spec-compliance ref-token-missing`
  - `verifier-warning: src/auth/login.py:42 malformed-file`
```

## The Backlog Files

Both backlog files are project-wide, append-only, and use **explicit removal only** — agentic-review never auto-resolves entries.

**Sole writer:** the Phase 4 orchestrator (the agent that activated this skill) is the only writer of both files. The Phase 3 Verifier emits directives (`{id, last_seen, branch, sha, source}` updates, `migrate` copies, and new-entry mints) — it does **not** write either file itself. On first run when `paad/code-reviews/backlog.md` is absent, the orchestrator creates it with the fixed header below — **always, even when the directives list is empty.** A clean review with zero out-of-scope bugs still leaves a header-only committed `backlog.md` behind, so subsequent runs and downstream tooling can depend on the file existing. `paad/security/backlog.md` deliberately follows the opposite rule — created only on the first Security directive, next paragraph. Subsequent runs hit the file-exists path and skip creation. This single-writer rule prevents the Verifier and orchestrator from racing or both no-opping on the assumption the other will create the file.

**Two backlogs, one shape.** `paad/security/backlog.md` holds every entry whose `Bug class:` is `Security`; `paad/code-reviews/backlog.md` holds the rest. Same header, same per-entry shape, same ID format, same removal rule. The orchestrator creates the security file only on the first Security directive of a run — a header-only security backlog is a file that says "look here" for nothing — and applies the `.gitignore` rule from the parent `SKILL.md`'s Security findings paragraph before the first write. An update directive is written back to the file its `source` names. The security backlog is never committed and never shared across clones: a teammate's run mints its own IDs, `git log` on it shows nothing, and "re-confirmed" there means re-confirmed on this machine.

**The security report** at `paad/security/code-review-<branch>-<YYYY-MM-DD-HH-MM-SS>-<short-sha>.md` uses this same template and the same sections, holding only the `Bug class: Security` findings and their backlog IDs. Its Executive Summary, `Filtered out` reasons and every other prose field may say everything about them — it is the only file that does. Rendered as the security report, the metadata `Backlog:` line names `paad/security/backlog.md` and the `Security:` line is omitted — it would point at itself. In the main report, each tier, Out of Scope or Out-of-Scope Additions section that lost a finding to it carries one line: `N security finding(s) written to paad/security/<file>`. Write the security report only when it has something to hold: a routed finding, or a security-related `Filtered out` reason. That count line is the only trace a routed finding leaves in the main report: the Executive Summary, Review Metadata and every other prose field describe it as security-related at most; the weakness, its mechanism and its symbol appear only in the security report.

**Fixed header (preserved across all updates):**

```markdown
# Out-of-Scope Findings Backlog

> **These items were flagged by `/agentic-review` as out of scope for the branch
> on which they were found.** They may be stale, may already have been fixed by other
> means, may no longer apply after refactors, or may simply have been judged not worth
> addressing. Verify each entry against the current code before acting on it. Entries
> are removed only when explicitly addressed — no automatic cleanup.

---
```

**Per-entry shape:**

```markdown
## `<id>` — <one-line title>
- **File (at first sighting):** `path/to/file:line`
- **Symbol:** `<function or class name, or `<file-scope>` for module-level code>`
- **Bug class:** Logic | Error Handling | Contract | Concurrency | Security | Spec Compliance
- **Description:** ...
- **Suggested fix:** ...
- **Confidence:** High | Medium
- **Found by:** <specialist> (`<model>`)
- **First seen:** YYYY-MM-DD on branch `<branch>` at `<short-sha>`
- **Last seen:** YYYY-MM-DD on branch `<branch>` at `<short-sha>`
- **Severity:** Critical | Important | Suggestion
```

**Field-encoding when writing entries.** The Verifier is the primary writer and owns field encoding; the rules live in `references/verifier.md`'s "Field-encoding rules" section. Any agent that rewrites an existing entry must defensively re-apply those rules — do not assume an existing entry is well-formed.

**Update rule on re-discovery:** rewrite only the `Last seen` line. Everything else is immutable so the entry remains a stable historical record. The one exception is a `migrate` copy, whose `Bug class:` becomes `Security (retagged from <old class>)`; the note keeps its `id` derivable.

**Removal rule:** delete the entire `## <id> — <title>` block. No tombstones, no archive.

**ID format:** 8-char hex of `sha1(file + symbol + bug-class + first-seen-iso-date)`. For an entry retagged to `Security`, bug-class is the class it was retagged from.

**Soft size warning:** when the active backlog reaches **≥ 200 active entries**, surface a warning in the post-review message so accumulation stays visible.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall