review-team

What this skill does

# review-team

## Purpose

Run an SDD artifact through a **crew of persona-agents** instead of a single
pass, then **reduce** their findings into one scored report — so a document
reaches the same review depth on the plugin as on the MCP platform. This skill
is the plugin's binding of the engine-agnostic review-team model
(`${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_TEAM.md` + `${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_CREWS.yaml`):
one team definition, run here as Claude Code `Task` subagents over a shared
**review blackboard**.

Per `plans/DECISIONS.md` **D-0005** (blackboard for crew-state) + **D-0031**
(saga.json for outer-loop state), the plugin uses the blackboard (durable
per-persona slots) + coverage/quorum for crew-state resilience, **and** a
minimal saga.json journal for outer-loop phase state per the framework
saga lifecycle contract (`${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md`).
D-0031 supersedes D-0005's scope-narrowing premise; D-0005's blackboard
reasoning remains authoritative. The plugin does not implement Hermes'
full saga runtime (compensation/retry state-machine in Python) — its
implementation is cooperative via SKILL prompts.

## When to Use

- **At gates** (default for `team` mode): `pre_promotion` / `pre_merge` — invoked
  by `../doc-<layer>-audit/SKILL.md` (review), `../doc-<layer>-fixer/SKILL.md`
  (remediate), `../doc-<layer>-autopilot/SKILL.md` (create loop).
- **`single_pass` fallback** (advisory): at `on_author`, or wherever subagents
  are unavailable / cost-constrained — one agent applies every lens in one pass.

The active mode comes from the `review_mode` knob (`team` | `single_pass`) in the
project adaptation profile (`.aidoc/profile.yaml`); default **team at gates,
`single_pass` (advisory) at `on_author`** so write-time cost is unchanged.

## The crew (lens → plugin agent)

Each layer's crew + per-layer weights are defined in
`${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_CREWS.yaml`. The framework's engine-agnostic lenses
map to the plugin's `agents/` like so (a lens with no dedicated agent is run by
the closest agent with that lens brief):

| Framework lens | Plugin agent |
|----------------|--------------|
| `requirements_specialist`, `business_analyst`, `product_owner` | `requirements-analyst` |
| `architect`, `tech_lead`, `integration_lead` | `solutions-architect` |
| `qa_lead` | `test-architect` |
| `operator` | `devops-release-engineer` |
| `auditor` | `traceability-auditor` |
| `chaos_engineer` | `chaos-engineer` |
| `security_engineer` | `security-engineer` |
| `synthesizer` | `synthesizer` |
| `drafter` (create) | the layer's author agent |
| `fixer` (remediate) | `software-engineer` / `../doc-<layer>-fixer/SKILL.md` |

## The blackboard

A per-review workspace under the git-ignored project-runtime dir:

```
.aidoc/review/<artifact-id>/
  <persona>.json     # one slot per lens (the persona-output record)
  report.md          # the synthesizer's unified report (may also persist to the doc folder)
```

Each slot is the framework **persona-output contract**:

```json
{
  "persona": "chaos_engineer",
  "findings": [
    {"id": "<stable id>", "priority": "P0|P1|P2|P3",
     "location": "<section / element id>", "message": "<what is wrong>",
     "recommendation": "<how to fix>"}
  ],
  "lens_score": 0
}
```

The blackboard is a **hub** (orchestrator-mediated): subagents return their
record to the orchestrator, which writes the slot. It is **not** a peer-to-peer
mesh — subagents do not share live memory. Slots are **transient + git-ignored**
(`.aidoc/review/`); only the unified report may persist into the doc folder.

## The saga journal

Alongside the blackboard, the orchestrator maintains a **saga journal**
at `.aidoc/review/<NN>_<LAYER>/<artifact-id>/saga.json` per
`${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md`. The saga
journal records:

- run-level **state machine** progression (PREPARED → FANOUT_STARTED
  → BRANCH_RUNNING → BRANCH_COMPLETED → FANIN_REDUCED → SYNTHESIZED →
  CLOSED, with `PARTIAL_TIMEOUT` and `ESCALATED` failure paths)
- per-branch **status** (one entry per persona dispatched)
- a **transitions[]** append-only log (every state change)
- a **compensation_actions[]** append-only log (compensation events
  during the fixer's multi-lens validation phase)

The blackboard (slot files) captures **persona findings**; the saga
journal captures **lifecycle progression**. The two artifacts
complement each other:

```text
.aidoc/review/<NN>_<LAYER>/<artifact-id>/
  <persona>.json        # blackboard slot — persona-output record
  saga.json             # saga journal — lifecycle state + transitions
  report.md             # synthesizer's unified report
  verdict.json          # synthesizer's combined-status companion (per BRD-RT-002)
```

The dispatcher (this skill) is responsible for transitioning the
saga `status` and per-branch states as it fans out and reduces.
Specifically: it updates `branches[<lens>].status` to
`BRANCH_RUNNING` before each dispatch and to `BRANCH_COMPLETED` /
`BRANCH_FAILED` after each return, and transitions the run-level
`status` from `FANOUT_STARTED` → `FANIN_REDUCED` once all branches
have reached terminal states.

The schema lives at
`${CLAUDE_PLUGIN_ROOT}/framework/governance/saga.schema.json`;
conformance tests (arriving in SAGA-PARITY-001 Phase 3) validate
runtime saga.json files against it.

Saga writes are skipped in `single_pass` mode and in standalone
audit/fixer invocations that lack a pre-existing saga.json (the
orchestrator is the lifecycle owner; standalone skills do not
initialize the saga from scratch).

## How it runs

1. **Resolve the crew** for the layer + operation from `REVIEW_CREWS.yaml`; map
   each lens to its agent (table above).
2. **Fan out** (mode `independent`, the default): dispatch each lens as a `Task`
   subagent with the artifact + its lens brief; each returns its persona-output
   record, which the orchestrator writes to the lens's slot. (`sequential` mode:
   pass prior slots to each lens in turn — richer, costlier.)
3. **Reduce + synthesize**: run the `synthesizer` subagent over all slots. It
   dedups by (`location`+`id`), takes max severity, **unions** recommendations,
   computes the weighted/capped score + coverage, and writes `report.md`.
4. **Gate**: see below.

`pm-orchestrator` (or the invoking `doc-<layer>-audit`) is the dispatcher.

## Scoring, coverage & the gate

- **Aggregate score (advisory)** = weighted average of the crew's `lens_score`s
  using the `REVIEW_CREWS.yaml` per-layer weights, **renormalised over lenses that
  ran**, **then capped**: unresolved **P0 ⇒ 0**, **P1 ⇒ below the gate threshold**.
- **Coverage** = ran vs. expected lenses; below the crew **quorum** the result is
  **low-confidence → human review**, never a silent pass.
- **The gate is deterministic**: the structural `../doc-<layer>-audit/SKILL.md` /
  `../doc-validator/SKILL.md` floor (`sdd_doc_lint`) **plus** "no unresolved
  P0/P1". The numeric score + narrative are advisory enrichment **above** that
  floor — a borderline artifact cannot flap pass/fail on model variance.

## Operations — three shapes, one crew

- **Review** (`doc-<layer>-audit`): the crew reviews; the synthesizer emits the
  findings report + score.
- **Create** (`doc-<layer>-autopilot`): **one drafter** authors from the template
  and upstream artifacts; the crew reviews and the drafter revises — a
  draft→review→revise loop until the gate passes (not N parallel drafts).
- **Remediate** (`doc-<layer>-fixer`): a **fixer** proposes a patch per blocking
  finding; the relevant lens(es) validate it does not regress; the synthesizer
  emits the proposed fix set.

## Resilience & security

- **Partial crew.** If a lens subagent fails/returns nothing, the orchestrator
  marks its slot failed; the reduce proceeds on the lenses that returned and
  records `coverage`. Below quorum → low-confidence/human-review.
- **Untrusted content.** The artif