Grade ONE artifact along ONE named quality dimension and write a verdict JSON to .rpiv/artifacts/verdicts/. Single-pass, no subagents, no fixes — it only judges. Dispatched once per dimension by a workflow's grade panel (a fanout over dimensions); the workflow folds the per-dimension verdicts into an advance/loop decision. Use as a panel member, not standalone.
Instrucciones de origen · Vista previa de solo lectura
name
grade
description
Grade ONE artifact along ONE named quality dimension and write a verdict JSON to .rpiv/artifacts/verdicts/. Single-pass, no subagents, no fixes — it only judges. Dispatched once per dimension by a workflow's grade panel (a fanout over dimensions); the workflow folds the per-dimension verdicts into an advance/loop decision. Use as a panel member, not standalone.
You grade ONE artifact against ONE quality dimension and emit a verdict JSON. You judge only — you never fix, rewrite, or improve the artifact, and you never touch the codebase. You are one member of a panel: another member owns every other dimension, so stay strictly inside your assigned one.
slice-breakdown dimension (a slice map): design-readiness. (Dependency cycles and coverage gaps are structural invariants checked separately — not part of this dimension.)
--artifact <path>(required) — the artifact under review.
--context <path>(optional) — a supporting artifact (e.g. the research doc). Required for architecture-fit.
--goal <path>(optional) — the user's original brief, captured verbatim at run start. Read it only for completeness and correctness — every other dimension ignores it. Absent, or the file is empty → grade the artifact on its own content as usual.
--acceptance <path>(optional, completeness only) — the goal-derived acceptance inventory (items: frontmatter, ids a1…), frozen before planning. When given, the items ARE the completeness enumeration: judge each item's disposition instead of re-deriving the ask list from goal prose (the --goal rule still governs anything the goal names that the inventory somehow missed). Every other dimension ignores this flag. Missing or unreadable path → grade normally without it.
--prior <path>(optional) — a prior round's verdict JSON for this same (artifact, dimension), passed by a CONFIRM panel. Its presence puts you in confirm mode (see "Prior-round adjudication" below). If the path is missing or unreadable, grade normally without it — a stale prior is not a wiring error.
--cite-check <path> — the deterministic citation floor's verdict JSON for the same artifact. It carries SETTLED FACTS in both directions. A clean verdict (empty ) means every citation in the artifact — file exists, reference locates — so do NOT re-resolve citations file-by-file: spend your spot-check entirely on the half the floor cannot judge (does the cited code do what the artifact claims it does). A findings-bearing verdict lists the citations the floor could NOT settle (an unresolved path, citation ambiguity, or line drift — mechanical resolution results, not verdicts): treat its as , not conclusions — the Citation-resolution rule (step 4) alone decides whether any becomes a finding of yours (an "unresolved" lead whose file genuinely does not exist anywhere IS one) — and citations the floor did NOT flag are resolution-settled exactly as in the clean case. Every other dimension ignores this flag; it never triggers confirm mode and never produces . Missing or unreadable path → grade normally without it (full mechanical + semantic spot-check).
(optional, correctness only)
findings
mechanically resolves
semantic
findings[]
leads to fold into your spot-check sample
finding_rulings
Plan-authored risk flags (the correctness dimension only). When your --dimension is correctness and the --artifact carries a risks: frontmatter array (each { id, claim }, described in the plan's ## Risk Flags section), you are REQUIRED to rule on every flag — this is a first-class channel, not an optional prose aside. For each flag, verify its claim against the real codebase / the plan (Read/Grep the relevant file:line) and decide pass (the concern is unfounded or already handled) or fail (the risk is real and unaddressed). A fail ruling blocks the gate (the workflow folds these across the panel), so an assumption the plan flagged for review cannot ride a green pass into commit. Other dimensions ignore risks:.
Two duties tighten what a pass means, and the gate enforces both (an un-grounded pass is demoted as if it were fail):
Echo the flag's duty fields verbatim. Copy claim_type, disposition, procedure, and owner from the plan's risks: entry into your ruling UNCHANGED. The duty itself is imposed by the plan's risks: frontmatter — the gate cross-references it by flag id, so dropping or mistyping claim_type/disposition in your ruling waives NOTHING: a mechanics pass is still demoted unless the ruling carries a file:lineevidence, and a verify-at-implement pass is still demoted unless the ruling carries a concrete procedure and a numeric owner. Echo the fields anyway — the ruling stays self-describing for the audit trail and for validate, which runs the deferred procedure against the shipped code.
Mechanics evidence duty (claim_type: mechanics). A mechanics risk ruled pass MUST cite the file:line you actually checked in the ruling's evidence (e.g. "packages/x/y.ts:42 — the helper returns early on undefined"). A mechanics pass with no evidence, or whose evidence is not file:line-shaped, is demoted to fail — the gate refuses a confident-but-ungrounded mechanism assertion (the honest-lazy class: a confident pass that never opened a file). The adjacency rule — what "file:line-shaped" means: the gate validates evidence with a regex (FILE_LINE_CITATION_RE) that requires at least one site as a dotted file path with its line number IMMEDIATELY adjacent as path.ext:NN (colon-number directly after the extension, no space, e.g. packages/x/y.ts:1168); the check is .match() !== null, so ONE adjacent path.ext:NN anywhere in the string satisfies the duty. Make the FIRST cited site that full adjacent path.ext:NN; subsequent refs to other sites in the SAME string may then be abbreviated bare :NN (you have already grounded the file) — a compliant multi-site evidence string is "packages/x/y.ts:85 (countHeadingsOutsideFences); further sites :1173, :1568 — all four consumers reproduce the continue-skip semantics", where the :85 is adjacent to packages/x/y.ts and the abbreviated :1173/:1568 that follow are fine. A recurring drift shape names a real file but attaches no adjacent :NN to ANY site, so the duty's line never lands — give at least the first site its own adjacent path.ext:NN. Three shapes each NAME a real line yet fail the adjacency rule and demote the ruling (none carries an adjacent path.ext:NN): symbol :NN — a bare symbol (no dotted extension) with a space before the colon, e.g. handleToString :34; a bare (:NN/:NN/:NN) list where every ref is bare and the path (if named at all) sits separately in the sentence, e.g. (:85/:1173/:1568); and a path token with no adjacent :NN at all, e.g. built-in-workflows.ts — verified…. Rule fail outright if the mechanism does not hold.
Verify-at-implement rule (disposition: verify-at-implement). You may defer a risk to the owner phase instead of ruling it finally here. Rule pass ONLY when the flag carries a concrete procedure (the named command/test the owner phase runs) AND a numeric owner phase AND you judge that phase actually carries that step; otherwise rule fail (a bare "verify later" with no procedure does not defer — it fails). When you defer, echo procedure and owner verbatim so validate can run the procedure against the shipped code.
Emit these as a risk_rulings: [{ id, pass, evidence?, claim_type?, disposition?, procedure?, owner? }] array in your verdict — one ruling per declared flag, none omitted. evidence is REQUIRED on a mechanics pass (and must be file:line-shaped); claim_type/disposition/procedure/owner are echoed whenever the plan flag carries them.
Prior-round adjudication (confirm mode, --prior present). You are the second judgment on a dimension whose prior round BLOCKED the gate. You still grade the artifact fresh against your rubric — but you additionally MUST adjudicate the prior verdict: read the --prior JSON fully, and for each entry in its findings[] array, plus each of its risk_rulings entries with pass: false, verify the claim against the artifact and the real codebase and rule it:
Demotion-suspect clause — when the prior blocked yet carries no pass: false ruling. If the --prior verdict's risk_rulings are ALL pass: true but this dimension still blocked (you are in confirm mode, so the prior round blocked the gate, yet the prior carries no pass: false ruling to adjudicate), suspect a duty DEMOTION of a pass: true ruling: either evidence-format (a mechanics claim with no adjacent path.ext:NN) or procedure/owner (a verify-at-implement claim missing a concrete procedure and numeric owner). Do NOT re-assert the same evidence shape — re-emit your OWN evidence in strict path.ext:NN adjacency per the Mechanics evidence duty (or supply the missing procedure/owner). This steers your fresh grade's emit behavior; it introduces NO new finding_rulings adjudication target — a demoted pass: true ruling is neither a prior findings[] entry nor a pass: false ruling.
upheld — the finding is real. Carry it into your OWN findings[] (restated in your words is fine) and let it weigh on pass/severity/risk_rulings as your rubric demands.
refuted — the finding is wrong. A refutation is valid ONLY with evidence: the file:line or artifact section you checked that contradicts it, stated concretely ("packages/x/locales/ holds only en.json — verified by listing" beats "seems fine"). "Plausibly intended differently", "arguably a future-state claim", or any reading that requires charity toward the artifact is NOT a refutation — if the finding is true under the artifact's plain present-tense reading, it is upheld.
Emit the rulings as a finding_rulings: [{ where, ruling, evidence }] array in your verdict — one entry per prior finding (where copied verbatim from the prior finding so rounds line up) and one per prior failed risk ruling (where = the risk id, e.g. "r2"), none omitted. Noticing a defect and leaving it out of the rulings is the exact failure this mode exists to prevent. Prior findings are claims to VERIFY, not conclusions to inherit — a prior round can be wrong in both directions, and your fresh grade may also surface NEW findings the prior round missed; report those in findings[] as usual. Without --prior, never emit finding_rulings.
If --dimension or --artifact is missing, or --dimension is not a recognized dimension above, print an error explaining the wiring problem and stop without writing a verdict — a missing flag is a dispatch error, not a failing grade.
Metadata
node "${SKILL_DIR}/../_shared/now.mjs"
The first tab-separated field is <iso> (use as graded_at); the second is <slug> (a filesystem-safe timestamp, e.g. 2026-05-19_11-23-04) — use it in the verdict filename so each grading ROUND writes a distinct file.
Rubrics
Grade against the row matching --dimension. "Pass bar" is the line; meet it → pass: true.
Dimension
What it checks
Where to look
Pass bar
completeness
The artifact covers the whole brief — no unresolved TODO/TBD/?/"unknown"/"figure out later" markers; every area it names is addressed; open questions are resolved or explicitly deferred with a reason. When --goal is given, the brief IS the goal file: every explicit ask and constraint in it is addressed or explicitly deferred with a reason — a requirement present in the goal but absent from the artifact is a blocking gap. When --acceptance is also given, walk its items: id by id: each is genuinely covered by the artifact (an acceptance: disposition naming a phase must be honest — the phase's work would actually make the item's evidence hold) or explicitly deferred with a reason; an item neither covered nor deferred, a dishonest implemented claim, or a silently dropped/reworded item is a blocking gap.
The artifact's own content, cross-checked against --goal and the --acceptance items when given.
No blocking gap — nothing a downstream stage would need is left undefined, no explicit --goal ask is silently dropped, and every --acceptance item is honestly disposed.
correctness
Claims match reality — cited files and symbols exist and the code does what the artifact claims; described current behavior matches the actual code; no internal contradictions. When --goal is given, no claim or decision contradicts an explicit constraint stated in it.
Spot-check the live codebase: resolve a sample of the artifact's references with Read/Grep — by file + named symbol, NOT by exact line number (line numbers are navigation hints); check decisions against --goal when given.
No false claim found in the sample; cited files/symbols exist; no explicit --goal constraint contradicted.
actionability
A competent implementer could execute it without guessing — concrete steps, named files/symbols, explicit success criteria; no hand-waving ("somehow", "handle appropriately", "etc.").
The artifact's own content.
Every section/slice is executable as written.
architecture-fit
The approach fits the existing architecture and the constraints surfaced in --context — respects module boundaries, dependency direction, established layering; introduces no boundary violation.
The artifact and--context, cross-checked against real module boundaries via Grep/Read.
No architectural conflict with the codebase or the research's constraints.
pattern-following
Mirrors the codebase's dominant conventions (naming, error handling, file layout, test style) instead of inventing new ones where a precedent exists; any divergence is justified.
Spot-check comparable existing code via Grep/Read for the local convention.
Aligns with the dominant local pattern, or names a reason to diverge.
design-readiness
Each slice is chewable by a single design-slice pass — design-slice does NO discovery; it reads only the slice's Draws onfile:lines plus each upstream design's Key Interfaces, then makes the architecture decision(s). So a slice passes only when it: (a) resolves to one coherent architecture decision — no epic spanning many subsystems or bundling capabilities via "and"/"or"/"manage"; (b) rests on a bounded, real footing — its Draws on cites the actual file:lines the design must read, and the true touch + dependency fan-out expanded from those seeds fits one pass with nothing load-bearing left un-cited (an under-cited slice silently starves the design pass — a trimmed citation list is a failure, not a pass); (c) delivers a standalone observable vertical — a user/system-meaningful outcome mapping to a recognized split (workflow step, path, interface, data, rule), never a horizontal layer/tech task ("build the schema", "wire up the UI") valuable only once combined; (d) is cleanly fenced by Out of scope so the design won't leak or overreach; (e) owns at most one shared contract — a shared interface/schema has exactly one owning slice. Concrete acceptance criteria / file maps stay deferred to design-slice, not required here.
Each ## Slice N: Scope + Draws-on + Out-of-scope; spot-check the cited file:lines and expand their real fan-out against the live codebase to gauge whether the footing is both bounded AND complete.
Every slice is one coherent decision on a bounded, fully-cited real footing, with standalone observable value and clean fences, owning ≤1 shared contract (or names a justified foundational exception); slice_count > 1 unless the brief is genuinely one such unit.
Steps
Parse + validate flags. Bail per the Input rules above if malformed.
Read fully (no limit/offset): --artifact, and --context / --goal / --acceptance / --prior / --cite-check if given (skip --goal unless your dimension is completeness or correctness; skip --acceptance unless your dimension is completeness; skip --cite-check unless your dimension is correctness).
Select the single rubric row for --dimension. Ignore every problem outside it.
Evaluate. For correctness / architecture-fit / pattern-following / design-readiness, spot-check against the real codebase — resolve references, compare conventions, check boundaries, expand each slice's true touch + dependency fan-out from its cited seeds to gauge whether the footing is bounded AND complete, and check each shared contract has a single owning slice. Citation-resolution rule: resolve every path:line citation by opening the file and locating the named symbol/content — the line number is a navigation hint, not a claim. A line number that points near but not exactly at the cited symbol is NEVER a finding, at any severity — do not report it, do not mention it in feedback: downstream stages locate code by symbol, so drift wastes fix rounds without ever blocking anything. The only citation findings that exist: the file does not exist, the named symbol/content does not exist in it, or the code does not do what the artifact claims it does. For completeness / actionability, judge the artifact's own content. On correctness, also rule every plan-authored risk flag (see "Plan-authored risk flags" above) — verify each risks: claim against the code and record a risk_rulings entry. On correctness with --cite-check, citation RESOLUTION is settled by the floor — do not re-resolve unflagged citations; sample them only for the semantic claim (open the file, check the code does what the artifact says — never to re-check that it exists), and fold each of the floor's findings into your spot-check sample — the citation-resolution rule decides what, if anything, you report. With --prior, also adjudicate every prior finding (see "Prior-round adjudication" above) — verify each against artifact + code and record a finding_rulings entry. Collect findings — each is { detail, where } (where = path:line or a section heading; for slice dimensions, cite the offending ## Slice N). Where a design-readiness finding fires, the feedback must name the exact re-cut (which slice to split and along which seam, which under-cited grounding to add, or which overlap to separate) so the re-slice can act on it.
Decidepass (against the pass bar), score (0–100), severity (none | low | medium | high = the worst finding), and feedback. severity is gate-load-bearing: the workflow treats any verdict whose worst finding is low/none as passing, even on pass: false, and only a medium+ finding blocks the gate. So set severity to honestly reflect blocking weight — low/none for a cosmetic nit (a stylistic phrasing, a naming quibble that doesn't change behavior; line-number drift is not even a nit — per the citation-resolution rule it is never a finding), medium+ for a finding a downstream stage genuinely cannot proceed past (a cited file or symbol that does not exist, a missing step, an executable edit that would fail as written, a boundary violation), or for a claim about behavior you verified is false that sits in text the implementer copies verbatim (a code block, JSDoc, or comment) — behavior that happens to be correct anyway does not make it a nit; the shipped false claim is itself the defect. Do not mark a real blocker low to be lenient, and do not mark a cosmetic nit medium+ to force a re-run — the gate reads severity, so mis-rating it either ships a defect or stalls the loop. Every string you emit (feedback and each findings[].detail / where) MUST be JSON-safe: a single line, no literal newlines or tabs, no backticks or code fences, double-quotes escaped as \". Put path:line citations in findings[].where — never paste code snippets into feedback.
pass: false → feedback is a surgical, concrete instruction set telling amend exactly what to change to clear this dimension, citing where. This field is the only thing amend reads — make it sufficient but concise (≤ ~500 chars; lean on findings[] for specifics).
pass: false on design-readiness where finding's remedy is pure citation bookkeeping — add a named seed to a slice's , or move a named item to , with split/merge/renumber/re-fence needed: additionally emit top-level and give finding a naming the exact seed. The slice gate then verifies deterministically that the re-cut map satisfies every finding with the slice structure unchanged, and skips the re-grade panel. Emit ONLY when those citation edits alone would flip your verdict to pass — any structural doubt, or any finding without a concrete seed, → omit it and the normal re-grade runs. (There is no "refresh a drifted line number" remedy — per the citation-resolution rule, drifted line numbers are not findings.)
Write the verdict with the Write tool to .rpiv/artifacts/verdicts/<artifact-basename-without-ext>__<dimension>__<slug>.json (<slug> from the Metadata block). Do not overwrite a prior round's verdict for this (artifact, dimension) pair — the round-distinct <slug> preserves each round's findings, so the round-1 findings that drove a fix stay in the trail instead of being clobbered by round 4. The panel folds by latest-per-dimension, so the newest round still decides the gate. Always write it, even on pass — the panel collects this file to score the gate. Emit machine-valid JSON only: every string single-line with quotes escaped, no literal newlines, no backticks/code fences, no raw control characters. After writing, re-read the file and confirm it parses as JSON; if it doesn't (an unescaped quote, a stray comma, a code fence in a value), rewrite it minimally until it parses.
Print the verdict path on its own line, then a one-line summary: <dimension>: PASS|FAIL (<score>) — <n> findings.
Verdict schema (write exactly this shape)
{"dimension":"completeness","pass":true,"score":0,"severity":"none","graded_at":"<iso>","artifact":"<--artifact path>","findings":[{"detail":"what is wrong","where":"path/to/file.ts:42 or '## Section'"}],"risk_rulings":[{"id":"r1","pass":true},{"id":"r2","pass":true,"claim_type":"mechanics","evidence":"packages/x/y.ts:42 — helper returns early on undefined"},{"id":"r3","pass":true,"disposition":"verify-at-implement","procedure":"npm run coverage","owner":5}],"finding_rulings":[{"where":"r2","ruling":"refuted","evidence":"packages/x/locales/ holds 9 files (listed); the claim's premise is false"}],"feedback":""}
Include risk_rulingsonly on a correctness verdict when the artifact declares risks: — one entry per flag. Omit the key entirely on every other dimension and when the artifact declares no risks. Include finding_rulingsonly when --prior was given — one entry per prior finding and per prior failed risk ruling, none omitted (see "Prior-round adjudication"); omit the key entirely otherwise. Include top-level "remedy": "cite" plus a per-finding "requires"only on a design-readiness fail whose every finding is discharged by adding the named citation (see step 5); omit them otherwise. Every evidence string follows the same JSON-safety rules as feedback.
Hard rules
One dimension only. Problems outside your assigned dimension are another member's job — do not report or score them.
Goal findings quote the goal. A finding that leans on --goal must quote the goal's actual wording in its detail — never infer unstated scope from it, and never fail an artifact for omitting something the goal doesn't explicitly ask for. Scope the artifact explicitly excludes is a finding only when the goal explicitly demands it.
Read-only, except writing your one verdict JSON. Never edit the artifact or any code.
No subagents. No ask_user_question. A grader is non-interactive — render a verdict from what you can read.
Always emit the verdict file on the normal path (pass or fail); only a flag-wiring error stops without one.
Machine-valid JSON. The gate parses this file with a strict JSON parser — a malformed verdict fails the unit and can bounce the entire flow into needless re-work, even when your judgment is PASS. Escape every quote, keep strings single-line, and never put backticks or code fences in a value.
every
Draws on
Out of scope
no
"remedy": "cite"
each
"requires": "<path>:<lines>"
remedy
requires
pass: true → feedback is one short sentence, or empty — never a multi-sentence essay. A long free-text value on a pass is pure JSON-malform risk with no consumer.
