| name | review-consolidate |
| description | Review many repos under every lens — one OS process per (repo × lens), all in parallel — then consolidate every findings.json into ONE cross-repo document grouped by severity then repo. Spawns subprocesses, never subagents. Trigger: /review-consolidate <repo> [<repo>...] --out <file.md>, "review these repos and consolidate the findings".
|
| argument-hint | <repo> [<repo>...] --out <file.md> [--lenses a,b,c] [--no-run] [--all] |
review-consolidate — run the matrix, then write one document
Two jobs, in order: fan out the reviews as parallel subprocesses, then
merge their findings into one document. You review no code yourself.
Subprocesses, not subagents. Never use the Agent tool. Every review runs
as its own claude -p process, one per (repo × lens), launched by
BASE_DIR/bin/run-matrix.sh (ADR 0004).
Shared assets base dir (BASE_DIR below) —
~/.claude/skills/adversarial-review/: CONTEXT.md (glossary), agents/
(reviewer, challenger, judge role packs), lenses/ (15 lenses), bin/run-matrix.sh
(the matrix launcher).
Phase 0 — Arguments (repos and --out are required)
Parse the argument string:
- repo paths — one or more, positional. Required. At least one.
--out <file> — the consolidated document path. Required.--lenses a,b,c — restrict the matrix to these lenses. Default: every lens
except the change-only ones (test-surface, blast-radius).--no-run — skip Phase 1; consolidate reports already on disk.--all — include every report found, not just the newest per (repo, lens).
Stop immediately, with usage, if no repo path is given or --out is missing:
review-consolidate needs repos and an output path:
/review-consolidate <repo> [<repo>...] --out <file.md>
Never guess a default output path and never default the repo list to the
current directory — a consolidated doc written somewhere unexpected, or built
from the wrong repo set, is worse than an error.
Resolve every repo path to absolute. A path that does not exist is a hard error
(name it, list the ones that do). Accept a directory prefix (307) only if it
resolves to exactly one directory; if it matches zero or several, error and list
what it matched.
Pick a run stamp (date +%Y%m%d-%H%M%S) and a log dir next to --out:
<dirname of --out>/review-matrix-<stamp>.logs.
Phase 1 — Run the matrix (parallel subprocesses)
Skip this phase entirely when --no-run was passed.
Run the launcher — ONE command, one bash call, it blocks until every child is
done. Do not hand-roll the fan-out and do not launch the children one at a time:
BASE_DIR/bin/run-matrix.sh --runner claude --log-dir <logdir> \
[--lenses a,b,c] <repo> [<repo>...]
--runner claude is required: the launcher defaults to pi.
What the script does, so you do not re-implement it:
- one
claude -p review process per (repo × lens),
every one launched before it waits — unbounded parallelism, by design;
- one log per pairing at
<logdir>/<repo>-<lens>.log;
<logdir>/manifest.tsv with repo, lens, exit, seconds, report, log, where
report is the REPORT: path each child printed (none if it printed none).
The run is long. Use a generous timeout on the bash call and do not poll,
interrupt, or re-run it — a second launch doubles the load on every repo.
Read manifest.tsv when it returns. A non-zero exit or a none report is a
failed pairing: keep its repo, lens, and log path for the Not consolidated
section. Never silently drop it and never re-run it — a report that says "the
security lens failed here" is honest; a report missing the security lens lies.
Phase 2 — Collect the sidecars
For each repo, list <repo>/.gbencke/adversarial-review/reports/*.findings.json.
- Prefer the sidecar next to each
report path from the manifest (same basename,
.findings.json) — that is exactly this run's output.
- With
--no-run, or for a pairing whose manifest report is none, fall back to
the newest sidecar per lens slug (the
<stamp>-<target>-<lens>.findings.json basename carries both). --all keeps
every sidecar instead.
- A repo with no reports dir or no sidecars is not an error — record it as
NO REPORTS and keep going. It is a signal (the review failed or never ran),
and hiding it would make the doc lie about coverage.
- A sidecar that is not valid JSON is recorded as
UNPARSEABLE with its path.
Never guess at its contents.
Load them mechanically — this is data movement, not judgment:
for f in <repo>/.gbencke/adversarial-review/reports/*.findings.json; do
jq -c --arg src "$f" '{src:$src, target, mode, date, counts,
findings: [.findings[] | {severity, lenses, labels, file, line, title,
failure_condition, suggestion}]}' "$f"
done
Report the tally before writing: repos in, pairings run, sidecars read, findings
loaded, pairings failed.
Phase 3 — Merge
- Tag every finding with its repo (directory basename) and its lens (from
lenses[], falling back to the sidecar's lens slug).
- Within a repo, collapse duplicates: same
file + same defect (same
title or same root cause) → one entry, lenses merged, highest severity kept.
The same file gets reviewed by several lenses, so duplicates are expected.
- Across repos, never merge — each repo owns its own fix. Instead, when the
same defect class appears in ≥2 repos, label every occurrence
[CROSS-REPO: n repos]. That label is the reason this document exists:
a defect in three repos is a platform problem, not three tickets.
- Preserve severities as ruled. Never re-severity a finding here — the judging
already happened, and you no longer have the code in front of you.
Phase 4 — Write the document to --out
Order is fixed: severity first, repo second. Someone reading the top of this
document must see the worst thing across the whole estate.
# Consolidated review — <yyyy-mm-dd hh:mm>
Repos: <n> · Lenses: <n> · Findings: <n> (P0 <n> · P1 <n> · P2 <n> · P3 <n>)
## Summary
| Repo | Lenses | P0 | P1 | P2 | P3 | Total | Verdict |
|------|--------|---:|---:|---:|---:|------:|---------|
<one row per repo, then a TOTAL row. Verdict = worst per-lens health.>
## Coverage
| Repo | Lens | Exit | Time | Report | Status |
|------|------|-----:|-----:|--------|--------|
<one row per (repo, lens) from manifest.tsv: exit code, seconds, report
filename, and OK / FAILED / NO REPORTS / UNPARSEABLE.
>
— · lens(es) · label(s)
Fails when:
Fix:
Rules for the file itself:
mkdir -p the parent of --out. Overwrite --out if it exists (the caller
chose the path; a stamped path is the caller's job).- Write nothing into the reviewed repos yourself. The child processes own their
reports dirs; you only read them.
- Empty findings across every repo is a valid document: write it with the
summary and coverage tables and say so. A silent no-op looks like a crash.
Phase 5 — Summary
Chat reply ONLY: the counts line, pairings run / failed, the worst 5 findings
across all repos (one line each, with repo), and the output path.
Last line, on its own, absolute, prefixed exactly CONSOLIDATED: .
Hard rules
- Never use the
Agent tool. Parallelism is BASE_DIR/bin/run-matrix.sh and its
child
processes (ADR 0004).
- Never run the launcher twice in one invocation.
- Never open a source file in the reviewed repos. Sidecars are the only input
for findings; if a sidecar is thin, the fix belongs upstream in the review.
- Never invent, re-severity, or drop a finding. Consolidation is arrangement.
