amirbena / amirbena/code-review-skill
Add a versioned machine-readable review output contract
- Dominant language
- Python
- Stars
- 7
- Forks
- 2
- Avg merge
- 27m
- Merged PRs (30d)
- 188
Description
## Problem
Consumers such as CI, agents, and GitHub integrations must scrape Markdown
to act on review results, which is brittle and undocumented. This is not
a greenfield semantic-design problem: the semantic content of a review
result already exists across canonical contracts — finding fields
(`shared/templates/finding.md` + `tests/reference/review/finding_contract.py`),
decision derivation (`shared/policies/severity.md` +
`tests/reference/review/decision_semantics.py`), review-level metadata /
reviewed SHA (`shared/templates/review-summary.md`'s "Machine metadata is
subordinate" section + `docs/findings/reviewed-sha-state-contract.md`),
and finding identity (`docs/findings/finding-stable-identity.md`,
`finding-identity-requirements.md`, `finding-matching-strategy.md`). What
is missing is a single machine-readable serialization of these existing
semantics, plus the runtime wiring to emit it.
## Goal
A versioned, documented machine-readable review-output contract, built by
formalizing existing canonical semantics into one schema and then emitting
it from both Skills — without replacing the human-readable report or the
enforcement boundary in #49.
## Scope
Tracked via child issues, in dependency order:
```text
existing canonical review semantics
↓
#67 formalized machine schema
↓
#68 version/evolution contract
↓
#69 local emission + #70 GitHub emission
↓
#71 cross-Skill contract validation
```
- #67 — formalize existing semantics into one output schema (references,
doesn't redefine, the canonical sources above)
- #68 — schema versioning / compatibility
- #69 — structured output in `local-code-review`
- #70 — structured output in `github-pr-review`
- #71 — cross-Skill contract tests
## Non-goals
- Removing or replacing the human-readable report.
- A hosted API service.
- Enforcement logic (see #49) — this contract is a findings document, not
a status/check mechanism, and #49's remaining research does not require
this contract to land first.
## Acceptance criteria
- All child issues closed and linked back to this issue.
- The resulting schema references canonical semantic owners rather than
redefining finding/decision/identity semantics.
## Dependencies
Depends on: none. The previous "Supported by #45" claim was not
load-bearing — #67's schema formalizes existing finding/decision/
reviewed-SHA contracts and does not depend on #45's Review Target/Context
structural mirrors landing first.
Related: #45 (independent Review Context/Target structural work; no
ordering dependency between the two).
Parent: #39.
## Validation
- Contract tests (#71) pass for both Skills.
Contributor guide
Assessment
This issue has not been assessed yet.