| name | gov-review |
| description | ALWAYS invoke to audit existing governance artifacts for quality gaps. Triggers:"review our ADRs","audit decision records","check governance docs". NOT for making a new decision (use govern) or reviewing code (use audit/review-branch). |
| argument-hint | [path-or-glob] [docs/decisions|docs/rfcs|docs/design] |
| model | sonnet |
| allowed-tools | Agent(gov-audit-reviewer), Read, Grep, Glob, Bash, AskUserQuestion |
Governance Artifact Review (read-only)
Overview
Audits already-written governance artifacts — ADRs, RFDs, and design docs — against a six-axis quality rubric and reports where they fall short. Globs the artifact directories (or a user-supplied path/glob), fans gov-audit-reviewer out one-per-artifact, collects each VERDICT:, and writes a single ranked review report with a per-artifact table plus an aggregate roll-up. This skill reads and reports only — it never edits an artifact. Hand the report to govern (to re-decide a failing record) or fix the artifact by hand.
When to Use
- The user wants existing decision records checked for quality, not a new decision made.
- Triggers: "review our ADRs", "audit our decision records", "check the governance docs", "are our ADRs any good".
- One artifact or a whole directory — the skill fans out across however many it finds.
When NOT to use
- Making or recording a new decision — use
govern.
- Reviewing code for bugs or a branch diff — use
audit or review-branch.
- Writing or fixing an artifact — this skill is read-only; it produces findings, not edits.
Input
$ARGUMENTS — Optional. A path or glob to the artifacts to review (docs/decisions/0003-*.md, docs/rfcs/, a single file), and/or one of the dir hints docs/decisions | docs/rfcs | docs/design. If empty, the audit phase globs all three default artifact directories. Ambiguous or unrecognizable input → ask via AskUserQuestion, never guess.
Approval gate
None. This skill is read-only — it scores artifacts and writes a report under REPORT_DIR, modifying no governance artifact — so no user approval gate is required. The reviewer agents are likewise read-only (Read, Grep, Glob).
Constants
- MAX_REVIEWERS: 6 (parallel
gov-audit-reviewer agents per wave; overflow runs in sequential waves)
- TASK_DIR:
.mz/task/
- REPORT_DIR:
.mz/reviews/
- ARTIFACT_DIRS:
docs/decisions/*.md, docs/rfcs/*.md, docs/design/*.md (the default glob set when no path/glob is supplied)
Core Process
Phase Overview
| # | Phase | Reference | Loop? |
|---|
| 0 | Setup | inline below | — |
| 1 | Audit | phases/audit.md | — |
Phase 0: Setup
- Parse the argument. Split
$ARGUMENTS into tokens. A token that is a path, a glob (contains */?), or an existing directory becomes the artifact source. A bare dir hint (docs/decisions | docs/rfcs | docs/design) selects that one directory. No path/glob token → the audit phase falls back to ARTIFACT_DIRS. If a token is unrecognizable (neither a path, a glob, nor a dir hint), ask via AskUserQuestion which artifacts to review — never guess a source.
- Derive the task name
<YYYY_MM_DD>_gov-review_<slug> where <YYYY_MM_DD> is today's date with underscores and <slug> is a snake_case summary (max 20 chars) of the argument (e.g. decisions, all_docs); on same-day collision append _v2, _v3.
- Create
TASK_DIR<task_name>/ and write state.md per the inline v2 contract below — Status: running, Phase: 0, the parsed artifact source, and the resolved REPORT_DIR report path.
- Emit a visible setup block:
task_name, the artifact source (parsed glob/path or "default ARTIFACT_DIRS"), MAX_REVIEWERS, and the report path. Then read phases/audit.md and run Phase 1.
Phase 1: Audit
Glob the artifact source, dispatch gov-audit-reviewer per artifact (parallel up to MAX_REVIEWERS, sequential overflow waves, each wave with a pre-dispatch manifest and a post-wave rollup), collect every VERDICT:, and write the review report to REPORT_DIR. See phases/audit.md. If zero artifacts are found, report that clearly and stop — do not fabricate findings.
Techniques
Techniques: delegated to phases/audit.md (glob resolution, wave batching, manifest/rollup, report shape) and references/review-rubric.md (the six-axis scoring rubric the reviewer applies).
Common Rationalizations
Common Rationalizations: delegated to the gov-audit-reviewer agent — its anti-rationalization table covers the audit-discipline excuses (softening a Critical:, passing a pending sign-off, rounding a single Critical up to PASS).
Red Flags
Red Flags: delegated to phases/audit.md and the gov-audit-reviewer agent. The orchestrator-level red flag: dumping the full report inline instead of reporting its path, or claiming a verdict for an artifact whose reviewer returned no VERDICT: line.
Verification
Output a final block: the report path under REPORT_DIR, the aggregate roll-up (N artifacts reviewed, M failing), and the per-artifact verdict list. Confirm the report file exists. If any reviewer returned no VERDICT:, name that artifact as unscored rather than counting it as a pass.
Error Handling
- Zero artifacts found at the resolved source → report it (the directories may be empty or the glob too narrow) and stop. Do not invent artifacts.
- Unrecognizable argument → escalate via AskUserQuestion before Phase 1; never guess the source.
- A reviewer returns
BLOCKED / NEEDS_CONTEXT / no VERDICT: → record it in the report as unscored (not a pass) and continue with the rest; retry a single empty dispatch once before marking it unscored.
- Never guess on ambiguity — escalate via AskUserQuestion.
State Management
State persists to TASK_DIR<task_name>/state.md. Schema is v2: the file's first line is schema_version: 2, and alongside Status / Phase / Started it carries phase_complete (boolean) and what_remains (YAML list of strings). Set phase_complete: false on phase entry and true once the phase's artifacts are written and its gates pass; refresh what_remains on every phase transition; what_remains MUST be [] when Status: complete. On reading a schema_version: 1 or unversioned file, add the missing keys, set schema_version: 2, and log the upgrade.
