Kartik-Doye/Ravengard-AI-Recruiter / .agents/skills/referee
referee
VerifiedReviews a change against intent, design, correctness, complexity, security, tests, maintainability, and repository conventions. Use for code, diffs, pull requests, or implementation reviews that should produce only evidence-backed actionable findings.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| references/finding-format.md | markdown | 4.5 KB |
| references/research.md | markdown | 805 B |
| references/review-protocol.md | markdown | 2.0 KB |
references/finding-format.md
View on GitHub# Findings: severity, format, the quality checklist
## Severity definitions (with the line between them)
| Sev | Definition | Example |
| --- | --- | --- |
| **Blocker** | Ships a defect: data loss, security hole, broken acceptance criterion, crash on a real path | authz check missing on new endpoint |
| **Major** | Will hurt soon and shouldn't merge as-is: missing tests for new behavior, silent error swallowing, misleading naming on a core concept, perf foot-gun on a hot path | new money path has no test for the failure branch |
| **Minor** | Real but safely fixable forward: missing edge case that's unlikely, small duplication, doc drift | error message promises format the code doesn't produce |
| **Nit** | Preference and polish: naming, order, subjective style | `d` vs `durationMs` |
Judgment calls: **a preference is a nit.** Reserve major for things that
will demonstrably cost the next person time or the users something.
Nits never block; if you're listing more than a handful of nits, you're
reviewing style, not the change.
## Finding format (every finding, all five parts)
```text
<sev> <file:line>: <what is wrong>
why it matters: <the concrete consequence>
fix direction: <the change, one line>
confidence: certain | likely | possible
```
A finding without "why it matters" is an opinion; without a fix
direction it's a complaint; without confidence it claims certainty it
didn't earn. `possible` findings say what would confirm them. All three
halves or delete it.
## Quality checklist (walk per diff: skip what doesn't apply)
**Correctness**
- Logic handles the edges the behavior names: empty, zero, max, negative,
malformed, concurrent, repeated.
- Error paths do something deliberate (typed, logged, surfaced): no
silent catches.
- Resource handling: files/connections/cursors closed on every path,
including error paths.
- Concurrency: shared state identified; races either impossible
(constraints) or handled (locking/idempotency).
**Intent & scope**
- Every acceptance criterion: met, partially met, or missing: named.
- No scope creep: refactors/rename/dead-code removal that the criteria
didn't ask for (note as findings, however well-intentioned).
- No dead code, debug leftovers, commented-out blocks, or console
noise introduced.
**Tests**
- New behavior has tests at the boundary that matters (proof's map).
- The tests would fail if the implementation were reverted.
- No test-only backdoors in production code (or they're documented and
gated).
**Security**
- New inputs validated at the boundary; new object access authorized per
resource.
- No secrets/PII in logs, errors, or test fixtures.
- Queries parameterized; no string-built SQL/commands.
**Performance** (obvious-level only; measurement belongs to hotpath)
- No N+1 in new loops over queries; no unbounded growth (arrays, maps,
listeners).
**Conventions & clarity**
- Project conventions followed (naming, structure, patterns): reviewer
taste loses to house style.
- Names say what things are for; the complex part has the comment
explaining *why* (not *what*).
- Complexity proportionate: is there a simpler version that meets the
criteria? If yes, that's a major with a sketch.
**API/DB surface changes**
- Breaking changes flagged and versioned; migration has a down-path.
- **Context Verification:** If a signature changed, were all upstream callers verified/updated? Reviewing the signature change without searching the repo for callers is an invalid review.
## The empty review vs. LGTM Syndrome
"No blocking findings": stated with the review scope and mode: is a
professional verdict, not a failure of effort. Manufacturing findings
to look thorough is worse than an honest clean pass. However, beware **LGTM Syndrome**: do not approve a PR just because it lacks syntax errors. The code must actually solve the business intent. An honest clean pass means both syntax AND intent are verified clean. Density of real findings varies with the diff; say so when a clean diff was genuinely clean.
## Self-review discipline (when fresh-context is unavailable)
1. Wait for the **complete** diff: reviewing slices hides the seams.
2. Reread the written acceptance criteria before line one of code,
memory of them is author-bias fuel.
3. Read the diff twice: once as intent-auditor, once as quality checklist.
4. For every "looks fine", ask what evidence would prove it isn't.
5. Disclose the mode; recommend a fresh-context pass before merge for
anything touching auth, money, or data loss paths.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |