amirbena / amirbena/code-review-skill
Define review output schema
- Dominant language
- Python
- Stars
- 7
- Forks
- 2
- Avg merge
- 27m
- Merged PRs (30d)
- 188
Description
## Problem
The semantic content of a machine-readable review result already exists,
but scattered across canonical sources with no single machine-readable
serialization: finding fields in `shared/templates/finding.md` (backed by
`tests/reference/review/finding_contract.py`), decision derivation in
`shared/policies/severity.md` + `tests/reference/review/decision_semantics.py`,
review-level metadata (reviewed SHA, counts, decision code) in
`shared/templates/review-summary.md`'s "Machine metadata is subordinate"
section + `docs/findings/reviewed-sha-state-contract.md`, and finding
identity in `docs/findings/finding-stable-identity.md`,
`docs/findings/finding-identity-requirements.md`, and
`docs/findings/finding-matching-strategy.md`. No JSON Schema (or
equivalent), no `schema_version` field, and no term "Review Result" exists
anywhere in the repo for review output today.
## Goal
Formalize the existing canonical review-result semantics as one
machine-readable schema, with a validating example document — without
redefining any semantic concept that already has a canonical owner.
## Scope
- A schema (JSON Schema or equivalent) that references, rather than
redefines, the canonical semantic owners above for: finding fields (id,
severity, title, location, evidence, remediation), decision derivation,
review-level metadata (reviewed SHA, summary, counts), and finding
identity.
- One example document that validates against the schema and is
consistent with the canonical sources it draws from.
- Document field semantics as pointers to their canonical
policy/template/contract, not as a second definition.
## Non-goals
- Versioning policy (see #68).
- Skill wiring / runtime emission (see #69, #70) — this issue defines the
schema only, it does not emit anything.
- Redefining any semantic concept (finding identity, severity, decision,
evidence/remediation shape, reviewed-SHA state) that already has a
canonical owner listed above.
## Acceptance criteria
- Schema covers the finding and review-level fields, sourced from the
canonical files above.
- Example document validates against the schema.
- Field semantics reference existing severity/decision/identity policy
rather than redefining it.
- Schema contains no finding/decision/identity semantics that conflict
with or duplicate its canonical source.
## Dependencies
Blocks #68, #69, #70, #71. Parent: #44.
## Validation
- Schema lints; example validates.
Contributor guide
Assessment
This issue has not been assessed yet.