| name | finding-format |
| description | Required fields and severity rubric (CRITICAL/HIGH/MEDIUM/LOW) for review findings, with file:line evidence convention. Owned by the reviewer. |
finding-format
Purpose
Standardize every reviewer's finding so it is machine-parseable, actionable, and
carries enough evidence for the builder to fix the issue without re-investigation.
Eliminates vague output like "this looks wrong" and grounds every severity call in
the rubric defined in the F-016 reviewer reference spec §6 (the canonical verdict
system — cited, not restated, in this skill).
When to use
Every time the reviewer produces a finding — plan review (plan-critic),
change review (quality-review, security-review), scope-compliance check, or
acceptance verdict (acceptance-decision). If the agent is the reviewer, the
finding runs through this format.
Procedure
For every issue found, capture the six required fields in this order:
- Location — the exact
file:line reference (repo-relative path, line
number; use path:start-end for a range).
- What — one sentence stating what is wrong, no hedge.
- Why — which FR / SC / system rule (R-###) it violates, or what concrete
harm it causes. Name the rule ID, do not restate it.
- Severity — assign per the rubric in the F-016 reviewer ref spec §6:
CRITICAL → always REJECTED · HIGH → always CHANGES-REQUIRED ·
MEDIUM → blocking by default, deferrable only with an explicit note ·
LOW → never blocking, always a note.
- Fix — the specific correction (function name, regex change, test to
add), not "fix it" or "consider improving."
- Evidence — test output, diff line range (
git diff HEAD~1:L138-L150),
gate failure message, or rule ID. "No evidence = no verdict" — if any
field cannot be filled, withhold the verdict and request the missing
evidence from the delegating lead.
Outputs
A finding with all six fields above, ready to fold into the review report and
route to the build lead (HIGH / MEDIUM-blocking) or committer (LOW notes).
Anti-patterns
- Vague findings without
file:line — the builder cannot locate the issue.
- Severity inflation — marking everything CRITICAL to force a reject.
- Severity deflation — downgrading a HIGH to MEDIUM to avoid blocking.
- Findings without evidence ("trust me, this is broken") — withhold verdict.
- Generic fix suggestions ("refactor", "improve naming") — name the actual
change.
- Restating the rubric in the skill body — cite the F-016 reviewer ref spec §6
once and link it; do not duplicate the table here.
