| name | kata-review |
| description | Grade a single artifact (spec, design, plan, or implementation diff) against quality criteria and return findings by severity. Use when another skill spawns a fresh sub-agent for an independent review of its work. This skill never spawns sub-agents — it produces findings only — which structurally prevents the spec/design/plan/implement review loop from recursing.
|
Review Artifacts
Independent grading skill for artifacts produced by kata-spec, kata-design,
kata-plan, and kata-implement. Returns severity-graded findings; takes no
action. Never spawns sub-agents.
When to Use
- A
kata-spec, kata-design, kata-plan, or kata-implement workflow has
reached its clean sub-agent review step and you have been spawned with no
prior context to grade the artifact.
- Any time another agent needs an independent quality grade on a spec, design,
plan, or diff without changing it.
Invariant: never spawn
This skill's Process has no step that launches a sub-agent. That is the
property that prevents the spec / design / plan / implement review loop from
recursing —
if you find yourself wanting to make an Agent tool call from inside this
skill, stop and return findings instead.
Severity Vocabulary
This is the canonical definition of review severity for the spec → design →
plan → implement arc. Grade every finding using exactly one level:
- Blocker — The work is broken, dangerous, or materially wrong. Must fix
before advancing (approving the spec, advancing status, merging code).
- High — A correctness or clarity problem that will cause rework, confusion,
or bugs downstream if shipped. Fix before advancing.
- Medium — A real quality or consistency issue worth fixing now while the
context is fresh. Fix before advancing.
- Low — Nit or preference. Optional; document if dismissed.
The caller is required to verify every finding against the actual artifact
before acting on it — sub-agent reviewers operate without prior conversation
context and can misread intent, miss surrounding code, or flag false positives.
After verification, the caller must address every confirmed blocker,
high, and medium finding before advancing. Low findings are
optional.
Process
Step 1: Identify the artifact type
The caller tells you whether the input is a spec.md, a design-a.md, a
plan-a.md (plus any decomposed parts), or a code diff
(git diff origin/main...HEAD). You are spawned cold with no back-channel to
the caller — if the artifact type or path is genuinely ambiguous, return a
single Blocker finding asking for clarification and stop. Do not guess.
Step 2: Build context before grading
Read in this order:
- The artifact itself. Read fully before anything else.
- Upstream documents. For a design, read the spec. For a plan, read the
spec and design. For a diff, read the spec, design, plan, and
CONTRIBUTING.md § Core Rules.
- Codebase files the artifact references or modifies. When the artifact
names files, functions, classes, or APIs, read those source files. When a
plan lists files to create or change, read the current versions. Verify
that the artifact's assumptions about existing code are accurate.
Step 3: Grade against criteria
Apply the artifact-specific criteria in the section below and any
domain-specific review criteria defined by your agent profile. For each gap or
risk, write one finding with:
- File path and line number (or commit hash)
- The criterion violated, in one short phrase
- Severity per the vocabulary above
- One-sentence explanation
Step 4: Return findings only
Do not modify the artifact, do not open PRs, do not invoke other skills, do not
spawn sub-agents. Group findings by severity and report.
Artifact Criteria
Grade each artifact against its skill's DO-CONFIRM checklist. The deltas below
are review-specific additions on top of the checklist.
For every artifact except spec.md, grade whether the artifact faithfully
represents the constraints and decisions established in the prior phase(s). A
design that satisfies its own checklist but contradicts a spec constraint, a
plan that ignores a design decision, or a diff that silently departs from the
plan are each at minimum a High finding. Process Step 2 has you read the
upstream artifacts — use them.
spec.md
Skill: kata-spec. No review-specific deltas.
design-a.md
Skill: kata-design. Delta: over 200 lines is a
Blocker.
plan-a.md (and parts)
Skill: kata-plan. No review-specific deltas.
Implementation diff
Match
kata-implement § Final verification
and CONTRIBUTING.md § Core Rules. Look for:
- Diff implements every spec success criterion
- Old path deleted in the same change — no shims, aliases, fallbacks, or
compat flags unless the spec requires them
- No scope creep (refactors, features, cleanup beyond the plan)
- Atomic, conventional-style commits on the branch
- Plan deviations noted in commit messages where present
- No security regressions (input validation at boundaries, secrets, dangerous
shell)
You may run the repository's check and test commands yourself to verify the head
commit, or trust the caller's assertion that they pass — the caller's Step 7
already requires green checks before delegating to you. Treat any test or lint
failure you observe as at minimum a High finding.
Output Format
Return findings grouped by severity exactly in this shape:
### Blocker
- <file:line> — <criterion> — <one-sentence reason>
- ...
(or "none")
### High
- ...
### Medium
- ...
### Low
- ...
Each finding is one line: file:line — criterion — one-sentence reason. No
preamble, no summary, no conclusion. The severity headers are the only prose. Be
honest and specific. Do not invent findings to look thorough. Do not
rubber-stamp.
What NOT to Do
- Do not spawn sub-agents. This skill must remain a leaf in the call graph;
spawning would re-introduce the recursion this skill exists to prevent.
- Do not modify the artifact. Reviewers grade; they do not edit.
- Do not open PRs, comments, or commits. Findings are returned to the
caller, who decides what to act on.
- Do not invoke
kata-spec, kata-design, kata-plan, or
kata-implement. Their Process steps would spawn another reviewer and loop.
