Gov Review

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

1. 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.
2. Derive the task name _gov-review_ where ` is today's date with underscores and is a snake_case summary (max 20 chars) of the argument (e.g. decisions, alldocs); on same-day collision append v2, _v3`.
3. Create TASK_DIR/ 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.
4. Emit a visible setup block: task_name, the artifact source (parsed glob/path or "default ARTIFACTDIRS"), MAXREVIEWERS, 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 MAXREVIEWERS, sequential overflow waves, each wave with a pre-dispatch manifest and a post-wave rollup), collect every VERDICT:, and write the review report to REPORTDIR. 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/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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DoctorMozg
• Source: DoctorMozg/claude-pipelines
• License: MIT

Install and usage instructions live in the source repository linked above.