amirbena / amirbena/code-review-skill

Capability-architecture migration: manifest, first extraction, progressive-loading proof (Epic)

Open
#403 0 comments 0 reactions 1 assignee Claimed by @amirbena View on GitHub
area:instruction-architecture maintainer-led priority:P1 type:refactor
Dominant language
Python
Stars
7
Forks
2
Avg merge
27m
Merged PRs (30d)
188

Description

## Problem

Review instruction/resource loading has no declarative capability boundary.
`docs/capability-architecture/capability-architecture-model.md` (added in
#401) shows three hand-maintained, mutually divergent declarations of what
each Skill loads (`SKILL.md` §2, `metadata/skill.yaml`,
`package-manifest.json` — e.g. 17 shared policies ship undeclared in
`local-code-review`'s own metadata), and that the review corpus loads
eagerly with no per-capability activation.

## Goal

Prove, on one bounded capability (`specialist-depth`), that a declarative
capability manifest can make loading conditional, fail-closed, and
behaviorally stable — before deciding whether to migrate the rest of the
capability graph.

## Canonical design

`docs/capability-architecture/capability-architecture-model.md` (§J–§M).
Read the canonical design before implementation on any child; do not
redefine this architecture locally.

## Scope

Children own, in dependency order: the manifest format; making it
authoritative over the three divergent declarations; per-adapter resource
subsets; a loading baseline; extracting `specialist-depth` as a real
ownership boundary; enabling its progressive loading; a benchmark-backed
behavioral proof; and a mandatory reassessment checkpoint.

## Non-Goals

- Migrating any capability besides `specialist-depth`.
- Any repository split (§E/§M.2 reject this).
- Fixing `benchmark_review_adapter.py`'s rendering coupling (owned by #67).

## Stage-4 gate

Children that establish real capability ownership or change loading
behavior do not start until #329 (benchmark-CI-as-real-gate epic) closes —
its Top-K/nightly-drift machinery is what makes later before/after loading
claims trustworthy. Manifest/declaration work is additive and
behavior-preserving and is not gated by #329.

## Acceptance Criteria

- [ ] Manifest format defined and generating byte-identical existing output
- [ ] The three divergent declarations reconciled into manifest projections
- [ ] Adapter-specific resource subsets declared
- [ ] `specialist-depth` extracted as a real boundary, then progressively loaded, fail-closed
- [ ] Benchmark proof of stable behavior + reduced surface exists
- [ ] Reassessment checkpoint answered before any further capability work is planned

## Dependencies

Depends on: none
Blocks: none
Parent: none
Children: pending (added once child issues exist)

## Validation

Each child validates itself; this epic is done when its Acceptance
Criteria are all checked and the checkpoint's answer is recorded.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.