Epic: Build a repository-owned composable code-review suite

[shaug]

Outcome

Build a repository-owned, composable code-review suite that provides three focused review lenses and one orchestrator:

• review-correctness
• review-solution-simplicity
• review-code-simplicity
• review-code-change

The suite must replace the runtime dependency on third-party review skills in implement-epic-sequence while remaining useful outside epic execution.

Motivation

A single generic review checklist mixes concerns that need different reasoning:

• correctness review looks for behavioral, security, compatibility, performance, and validation failures;
• solution-simplicity review asks whether the ticket can be satisfied by a materially smaller overall design; and
• code-simplicity review reduces local cognitive load through meaningful reuse, DRY, and smaller control flow.

Keeping the lenses separate prevents correctness hardening, line-level cleanup, and whole-solution redesign from diluting one another. Repository-owned skills also make the workflow deterministic when a third-party skill is not installed.

Architectural decisions

1. Each lens is a standalone skill with its own trigger description and UI metadata.
2. review-code-change is the only review skill that orchestration workflows need to invoke.
3. The suite uses one shared review packet and one normalized finding/verdict contract.
4. Reviews are read-only. The calling workflow owns implementation, fixes, commits, and pushes.
5. The default sequence is:
   1. capture the change contract and immutable evidence;
   2. review solution simplicity;
   3. review correctness;
   4. review code simplicity; and
   5. run a targeted correctness recheck after accepted simplification changes.
6. Correctness constraints override simplification proposals.
7. Review evidence is bound to the reviewed head. Base drift triggers merge-candidate analysis and only invalidates all review evidence when the effective diff or resulting tree changes, conflicts appear, relevant code overlaps, or repository policy explicitly requires a complete reset.
8. Runtime behavior must not depend on code-review-pro, Code Review Master, or any other third-party skill. Those may be used as research sources only.
9. Detailed rubric text must live in the owning lens, not be duplicated across the orchestrator and implement-epic-sequence.

Scope

• Define and validate the shared evidence and finding contracts.
• Implement the three review lenses.
• Implement orchestration, ordering, aggregation, and bounded re-review behavior.
• Add realistic forward-test fixtures covering correctness, genuine simplification, over-engineering, and intentionally necessary complexity.
• Integrate the suite into implement-epic-sequence.
• Update repository discovery documentation and changelog entries.

Non-goals

• Build a static analyzer, linter, or language server.
• Automatically modify reviewed code from a review-only context.
• Enforce universal line-count, cyclomatic-complexity, SOLID, or design-pattern rules.
• Produce style-only, praise-only, or generic best-practice reports.
• Add more review lenses before the initial three demonstrate a real gap.
• Require every repository to use human or connector review when its policy does not require them.
• Copy or vendor a third-party review skill as the runtime implementation.

Required child sequence

1. Define the shared review evidence, finding, verdict, and evaluation contracts.
2. Implement review-correctness.
3. Implement review-solution-simplicity.
4. Implement review-code-simplicity.
5. Implement review-code-change orchestration after all three lenses exist.
6. Integrate the repository-owned suite into implement-epic-sequence.

The three lens skills may proceed in parallel after the shared contract is complete. The orchestrator must wait for all three. Epic integration must wait for the orchestrator.

Epic acceptance criteria

• Every required child is closed with its acceptance criteria satisfied.
• All four skills validate with the repository's skill validator.
• Each lens is independently invocable and emits the shared result shape.
• review-code-change invokes only repository-owned skills and produces one deduplicated aggregate verdict.
• Forward tests demonstrate that the suite finds seeded material issues while rejecting style-only, speculative, and complexity-relocating suggestions.
• implement-epic-sequence depends on review-code-change, not code-review-pro.
• Review rubric duplication is removed from implement-epic-sequence and its GitHub/review references.
• Head changes and base drift are handled according to the architectural decision above.
• just format, just lint, and just test pass on the final integrated mainline.
• README and changelog describe the final skill suite.

[shaug]

Epic completion verified on main at bee27f759ac0e89f64a72e9f16a5ea2670d36fce.

• Required children Define shared contracts and evaluation fixtures for the code-review suite #5–Integrate the repository-owned review suite into implement-epic-sequence #10 are closed and their PRs feat: define shared code review contracts #12–feat: integrate review suite into epic execution #17 are merged and represented on main.
• The shared contracts, three standalone review lenses, review-code-change orchestrator, and implement-epic-sequence integration are present and validated.
• Runtime epic review now depends on the repository-owned suite rather than a third-party review skill.
• Final just format, just lint, and just test passed with 90 tests.
• The late-feedback sweep found no comments, reviews, or review threads on the six merged PRs.

All epic acceptance criteria are satisfied.