doc-brd-audit

What this skill does

# doc-brd-audit

## Purpose

Run a **unified BRD audit** — declarative structural checks plus content-quality
review — in one pass, producing a single combined report that
`../doc-brd-fixer/SKILL.md` consumes. The framework ships no runtime code, so
**this skill is the validator**: Claude performs each check directly against the
BRD using the spec as the contract.

**Layer**: 1 (BRD quality gate). **Upstream**: a BRD file. **Downstream**:
`BRD-NN.A_audit_report_vNNN.md` and an optional fix-cycle trigger.

## When to Use

Use after a BRD exists and before generating the PRD, or inside the autopilot's
audit↔fix cycle. Do **not** use to create a BRD (use `../doc-brd/SKILL.md` or
`../doc-brd-autopilot/SKILL.md`).

**Fresh-audit policy:** always audit from scratch — never reuse prior scores or
cached results; compute the PRD-Ready score independently each run.

**Report cleanup:** after writing the new report, delete superseded
`BRD-NN.A_audit_report_v*.md`; keep `BRD-NN.F_fix_report_v*.md` and
`.drift_cache.json`. Record a cleanup summary in the report.

## Execution Contract

**Input:** BRD path (`docs/01_BRD/BRD-NN_*/...`); optional score threshold
(default 90); optional `review_mode` override (`team`|`single_pass`); default
resolved from `.aidoc/profile.yaml`.

**Sequence:** 1) run structural checks (always, deterministic) → 2) record
findings → 3) run content review (branches on `review_mode`, see below) →
4) merge/normalize findings → 5) write the combined audit report to
`.aidoc/audit/01_BRD-audit.md` (the legacy
`BRD-NN.A_audit_report_vNNN.md` shape and content are preserved, just
relocated to the `.aidoc/` provenance tier) → 6) if auto-fixable findings
exist, hand off to `doc-brd-fixer`.

## Review Mode

Resolve `review_mode` from `.aidoc/profile.yaml`; if the key is unset
(the project profile is an override-only delta — most knobs are absent),
fall through to the framework default per the precedence chain in
`${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md` (`framework
defaults < user-global seed < project profile`). The framework default
is `team` at gates (`pre_promotion` / `pre_merge`) and `single_pass` at
write-time (`on_author`). The same fallback rule applies to every other
adaptation knob (`audit_threshold`, `section_toggles`, `active_layers`,
`glossary`). The structural checks below are run **deterministically by
this skill in every mode** — they are the gate floor per
`${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_TEAM.md` §"Scoring,
conflicts & the gate".

### team mode (default at gates)

The content-quality review is performed by a **fan-out of per-lens `Task`
subagents** over a per-artifact blackboard, per
`${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_TEAM.md` §Operations
§Review.

1. **Prepare the blackboard.** `mkdir -p .aidoc/review/01_BRD/<BRD-id>/`
   where `<BRD-id>` is the BRD's short artifact ID (e.g. `BRD-01`), not
   the nested folder name. This keeps blackboard paths stable when
   slugs change.
2. **Read the BRD crew** from
   `${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_CREWS.yaml` —
   `{architect: 30, business_analyst: 30, auditor: 20, chaos_engineer: 12,
   security_engineer: 8}`. Weights sum to 100. Rationale: chaos-heavy at
   BRD because reliability NFRs outweigh threat-modelling at this layer;
   see `REVIEW_TEAM.md` §"Weight allocation rules".
3. **Map each lens to its plugin agent** via the table in
   `../review-team/SKILL.md`:
   - `architect` → `solutions-architect`
   - `business_analyst` → `requirements-analyst`
   - `auditor` → `traceability-auditor`
   - `chaos_engineer` → `chaos-engineer`
   - `security_engineer` → `security-engineer`
3a. **Load the layer-and-lens playbook.** For each lens in the crew,
   resolve and read the playbook content from
   `${CLAUDE_PLUGIN_ROOT}/../../framework/playbooks/01_BRD/<lens>.md`.
   If the playbook file is missing, mark `branches[<lens>].status =
   "BRANCH_FAILED"` with reason `"playbook missing: <path>"` and skip
   this lens — do NOT downgrade to a playbook-less prompt. Other lenses
   continue. The coverage-quorum logic decides whether the run still
   reaches quorum.
4. **Fan out.** Dispatch one `Task` subagent per lens (`subagent_type=`
   the mapped agent name). Each subagent's brief contains:
   - The absolute artifact path (untrusted content)
   - The lens name and its weight
   - The slot path `.aidoc/review/01_BRD/<artifact-id>/<lens>.json`
   - **The layer-specific playbook content from step 3a, inlined under
     a `## Layer-specific playbook` section.** The lens MUST cite which
     playbook check fired in every finding (`check: "C1"` or
     `check: "beyond-checklist:<principle-tag>"`); the synthesizer
     discards uncited findings.
   - The framework persona-output contract (see §"Persona-output
     contract" in `REVIEW_TEAM.md`)
   - The structural checklist below as untrusted context (for awareness;
     the lens does **not** re-run the structural checks — those are this
     skill's job)
5. **Collect slots.** Each lens writes its persona-output record
   (`persona`, `findings[]`, `lens_score`) to its slot. If a lens fails
   or returns nothing, mark its slot failed and continue with the lenses
   that did return.
6. **Dispatch the synthesizer.** Run a `Task` subagent
   (`subagent_type=synthesizer`) against the slot directory. It writes
   **both** companion files (per `agents/synthesizer.md` §"Output"):
   - `.aidoc/review/01_BRD/<BRD-id>/verdict.json` — the authoritative
     machine-readable verdict (`combined_status`, `content_score`,
     `structural_status`, `coverage.*`, `blocking_findings_count`,
     `lens_scores`).
   - `.aidoc/review/01_BRD/<BRD-id>/report.md` — the human narrative
     (mirrors verdict.json values).
7. **Compose the combined audit report.** Read
   `.aidoc/review/01_BRD/<BRD-id>/verdict.json` and `report.md`. The
   final audit report at `.aidoc/audit/01_BRD-audit.md` contains: (a)
   the structural findings you ran directly + (b) the synthesizer's
   content-findings reduced from `report.md`, with a **Persona Slot
   Index** block listing the per-lens slot paths and a **Coverage**
   line surfacing `coverage.quorum_met` for consumers (`doc-brd-fixer`,
   `doc-brd-autopilot`).

**Quorum & coverage.** Per `REVIEW_TEAM.md` §Resilience, if
`verdict.coverage.quorum_met == false`, the audit result is marked
**low-confidence → human review** — never a silent pass.

### Output Contract (team mode)

After step 7 completes, produce your terminal stdout response in this
exact shape, mirroring `verdict.json` values verbatim:

```
Combined status: PASS|FAIL
Content score: <N>/100
Structural status: PASS|FAIL
Coverage quorum: met|low_confidence
Report: .aidoc/audit/01_BRD-audit.md
```

Read `combined_status`, `content_score`, `structural_status`, and
`coverage.quorum_met` from `verdict.json`. **Do NOT echo the BRD's
self-claimed PRD-Ready score** (the value the BRD document writes into
its own Document Control / Traceability sections is stale data the
audit must overwrite). The synthesizer's `verdict.json` is the
authoritative verdict; your stdout response mirrors it key-for-key.

### single_pass mode (fallback)

Run the content review **in this skill's own context**, applying every
lens (architect / business_analyst / auditor / chaos_engineer / security_engineer) sequentially in
one pass. No `Task` subagents, no blackboard. Quorum does not apply.
Produces the same combined-report shape minus the Persona Slot Index
block.

Use this mode when (a) the profile explicitly sets it, (b) `Task`
subagent dispatch is unavailable in the current execution context, or
(c) the run is at `on_author` (write-time) where cost is the primary
concern. **Architecture in v0.4.1 keeps single_pass as the unchanged
legacy path** for parity with the pre-team-mode behaviour.

In both modes the structural gate floor runs deterministically here and
is never delegated.

## Saga interaction

When invoked by `doc-brd-autopilot` (or d