---
name: guardrail-review
description: When the governance machinery itself (the rules, skills, and audit gates that keep a governed codebase honest, plus their wiring surfaces) needs a structural-integrity review, run this skill. It is the periodic guard-rail review: a judgment-based pass over the machinery for overlap (two rules or gates covering the same ground), gap (a stated discipline no gate enforces, a recurring failure mode no rule names), and drift (a rule, skill, or gate whose intent has diverged across its wiring surfaces in a way the mechanical parity gates cannot detect, because they check identity and count, not meaning). Maintainer-triggered, and auto-prompted after any PR that adds, removes, or renames a rule, skill, or gate. Catches the architectural erosion the per-PR and corpus-content sweeps are not built to see. Slash command `/guardrails`.
derives_from: ../../governance/gate-discipline.md
---

# Guardrail Review (governance-machinery structural integrity)

## Overview

A governed codebase accumulates machinery: governance rules, the skills that operationalize them, the audit gates that enforce them, and the wiring surfaces that keep all three in lock-step (a gate declared across the CI workflow, the local runner, the pre-commit config, and the audit-programme spec; a rule mirrored from the pack into the local rules copy and enumerated in three places; a skill paired with a slash command and registered for step-parity). The mechanical parity gates verify that these surfaces agree by identity and count: the gate names match across four surfaces, the rule mirror is byte-identical, the skills directory matches the README tree, the paired step-identifiers match. What no mechanical gate can verify is whether the machinery is *coherent*: whether two rules overlap, whether a stated discipline has no enforcing gate, whether a gate has quietly become decorative, whether a rule's intent has drifted from the skill that claims to operationalize it.

`guardrail-review` is that coherence review. It is the periodic structural-integrity pass over the machinery, run with three lenses: **overlap** (redundant or contradictory coverage), **gap** (a discipline, failure mode, or surface that nothing enforces), and **drift** (a meaning that has diverged across wiring surfaces below the resolution of the mechanical parity gates). It is judgment-based, because each of these questions requires reading the machinery as a designer would, not as a string-matcher does.

It is distinct from the content sweeps and the trust-recovery suite, and the distinction is the point. `/validate` and `/validate-pr` review the *corpus content* for regression. `/full-qa` and `/fitness` form the trust-recovery escalation tier, re-examining a *window of work* when an assistant's discipline has lapsed. `guardrail-review` reviews the *machinery itself*: the rules, skills, and gates as a system, asking whether the system is still well-formed. The content sweeps ask "is the corpus right?"; guardrail-review asks "is the apparatus that keeps the corpus right still well-built?".

## When to Use

- **Maintainer-triggered**, as a periodic structural deliverable (a natural cadence is at batch boundaries, before a pack release, or whenever the machinery has grown enough that its coherence is worth re-confirming). Like `library-fitness-review`, it is a periodic review, not a per-PR gate.
- **Auto-prompted after any PR that adds, removes, or renames a rule, skill, or gate.** When the machinery inventory changes, its coherence is exactly what a mechanical parity gate cannot re-confirm; the assistant surfaces a one-line prompt offering the review. The maintainer decides whether to run it now or defer.
- **Before distributing the pack as a standalone baseline.** In pack-distribution mode the machinery *is* the product; a structural review before release is the equivalent of a content proof-read.
- **NOT** as a substitute for the mechanical parity gates (35 gate-name parity, 37 claude-rules-sync, 39 gate-count consistency, 41 collection-enumeration, 44 paired-skill step-parity). Those run every PR and catch identity/count drift mechanically; guardrail-review is the semantic layer above them, not a replacement for them.

## Process

### 1. Establish the machinery inventory and the mechanical baseline

Run `tools/run_all_audits.sh` and confirm it exits 0. The mechanical parity gates (35, 37, 39, 41, 44) must be green before the semantic review begins: a red parity gate is an identity/count defect to fix mechanically first, not a structural finding for this skill. (The baseline run includes the git-history-aware gates 31 and 40; if the clone is shallow they misfire, so confirm `git rev-parse --is-shallow-repository` prints `false`, and `git fetch --unshallow` first if it does not.)

Then enumerate the current machinery as the inventory under review:

- **Governance rules**: the files under `dev-security/claude-rules/governance/` and their `.claude/rules/governance/` mirror, plus the three enumeration surfaces (pack README tree, pack `CLAUDE.md`, project `.claude/CLAUDE.md`).
- **Skills**: the directories under `dev-security/claude-rules/skills/`, each with its `derives_from` parent, its slash-command counterpart (if paired), its PAIRS registration, and its README-tree entry.
- **Gates**: the audit gates declared across the four parity surfaces (CI workflow, runner, pre-commit, audit-programme spec §6), each with its linter and the discipline it enforces.

### 2. Review the inventory through three lenses

Each lens is a systematic pass (or a dispatched subagent); every finding quotes `path:line`.

- **Overlap**: do two rules, two skills, or two gates cover the same ground? Redundant coverage is a maintenance cost (two surfaces to keep in sync) and a contradiction risk (the two can drift apart). For each candidate pair, decide: is the overlap deliberate and documented (different lenses on one surface, like `/full-qa`'s subagents A and F), or is it accidental redundancy that should be merged or one side retired?
- **Gap**: is there a stated discipline (in a rule, in `CLAUDE.md`, in a SKILL) that no gate enforces? a recurring failure mode (visible in `.working/improvement-log.md` or `.working/hallucination-metrics.md`) that no rule names and no gate catches? a rule with no operationalizing skill where one is warranted? a gate that covers one surface while a sibling surface is ungated? A gap is where the machinery says it does something the machinery does not actually enforce.
- **Drift**: has a rule's, skill's, or gate's *meaning* diverged across its wiring surfaces in a way the mechanical parity gates cannot see? The parity gates check that the gate names match, the mirror is byte-identical, the counts agree; they do not check that a rule's pack copy and the one-line `CLAUDE.md` bullet describing it still mean the same thing, that a gate's docstring still matches what its code enforces, or that a skill's `description` still matches its parent rule's intent. Semantic drift below the parity gates' resolution is this lens's quarry. (The recurring real instance: a convention revised in the rule but left stale in a one-line enumeration description, which the resume `/validate` of 2026-06-23 caught in the pack README.)

### 3. Synthesize and verify at apply-time

Dedupe findings by `(surface, item, lens)`; adjudicate severity (pick the higher of adjacent disagreements; no averaging); and **re-read each cited source before routing any finding**. A lens pass (or subagent) produces research, not findings; the orchestrator confirms each against the live source, because a structural claim about an unread surface is a hypothesis. Findings refuted at apply-time are recorded with the refutation, not routed.

### 4. Route findings to the backlog, severity-tiered

Route every confirmed finding to the project backlog, tagged `[guardrails]`, tiered by severity (High[critical]/High to the top-priority tier, Medium/Low to the next), none dropped. Structural findings frequently *propose a machinery change* (merge two overlapping rules, add a gate to close an enforcement gap, retire a decorative check, reconcile a drifted description). These are proposals for maintainer triage, not changes the skill applies autonomously: changing the machinery is a design decision the maintainer owns. Findings that dedupe against an existing backlog item are cross-referenced, not duplicated.

### 5. Record

Write a per-run record (in this project `.working/guardrail-reviews/YYYY-MM-DD-rN.md`) with one section per lens (overlap, gap, drift), an orchestrator-synthesis-and-verification section, and a findings-routed section. Append a row to the review history. Zero-finding runs still get a history row; the record file is conditional on findings, matching the sibling sweeps' convention.

### 6. Surface to the maintainer (termination)

Surface the confirmed findings inline in chat (per-finding: lens, severity, `path:line`, evidence quote, the proposed machinery change). The review is a single pass, not a fix-to-fixed-point loop: structural findings are maintainer-decision proposals, so the skill does not re-run itself to convergence the way `/validate` does. It terminates when the findings are routed and surfaced. (When the maintainer accepts a proposed machinery change, that change is its own PR, which itself becomes a trigger under the auto-prompt cadence.)

## Red Flags

- Running guardrail-review while a mechanical parity gate is red. Fix the identity/count defect mechanically first; the semantic review assumes the mechanical baseline is green.
- A finding without a quoted `path:line` (it is a hypothesis, not a finding).
- Routing a lens finding without the orchestrator's own re-read (apply-time verification is the false-positive filter, the same as in the content sweeps).
- Applying a proposed machinery change autonomously. Overlap-merges, gate additions, and rule retirements are maintainer-owned design decisions; the skill proposes, the maintainer disposes.
- Treating guardrail-review as a per-PR gate. It is a periodic deliverable; running it on every PR is both wasteful and not what the cadence calls for.
- Confusing this skill with the content sweeps. If the question is "is the corpus right?", that is `/validate`; if it is "is the machinery well-built?", that is this skill.

## Verification

The review is complete on a given run when: the mechanical baseline was confirmed green (the parity gates in particular); the machinery inventory was enumerated across rules, skills, and gates; all three lenses (overlap, gap, drift) were applied with evidence-quoted findings; the orchestrator re-read each cited source and confirmed or refuted it; every confirmed finding was routed to its severity-appropriate backlog tier tagged `[guardrails]`, none dropped, with proposed machinery changes flagged as maintainer-decision proposals; and the per-run record and history row were written and the findings surfaced in chat.

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "The parity gates pass, so the machinery is fine." | The parity gates check identity and count, not coherence. They pass while two rules overlap, a discipline goes unenforced, or a description drifts in meaning. That gap is exactly what this skill reviews. |
| "This overlap is obviously fine; skip it." | Then record it as a confirmed deliberate overlap with the reason. An undocumented "obviously fine" is how accidental redundancy hides until the two surfaces contradict each other. |
| "There is no gap; everything important has a gate." | "Important" is the judgment under review. Check `improvement-log.md` and `hallucination-metrics.md` for recurring failure modes; a pattern with no rule and no gate is a gap regardless of how it felt. |
| "I found a drifted description, so I'll just fix it now." | Fixing a stale description is a content fix (fine to bundle). Merging rules, adding a gate, or retiring a check is a machinery change the maintainer owns; route it as a proposal, do not apply it autonomously. |
| "Run it every PR to be safe." | It is a periodic review, not a gate. The mechanical parity gates run every PR; this skill runs on the maintainer trigger and the inventory-change auto-prompt. |

## See Also

- Canonical rule [`governance/gate-discipline.md`](../../governance/gate-discipline.md): the rule this skill operationalizes at the machinery level (a gate, and by extension the whole apparatus, derives its value from being meaningful and unconditional, not decorative).
- Related skill [`skill-authoring-discipline`](../skill-authoring-discipline/SKILL.md): the per-skill structural template; guardrail-review is the system-level counterpart that reviews the machinery as a whole rather than one new skill.
- Related skill [`deep-qa-review`](../deep-qa-review/SKILL.md) (`/full-qa`): its audit-programme-integrity subagent (C) checks the four-surface parity within a trust-recovery window; guardrail-review generalizes that check to the standing machinery and adds the overlap and gap lenses.
- Sibling skills [`validation-sweep`](../validation-sweep/SKILL.md) (`/validate`) and [`library-fitness-review`](../library-fitness-review/SKILL.md) (`/fitness`): the content-regression and fresh-reader reviews; guardrail-review is the machinery-structure review that complements them.
- Canonical rule [`governance/evidence-grounded-completion.md`](../../governance/evidence-grounded-completion.md): the apply-time re-read discipline each finding meets before routing.

## Why this skill exists

The governance machinery of this project grew from five rules to ten, from a handful of skills to fifteen, and from a dozen gates to fifty-four, each addition wired across multiple surfaces. The mechanical parity gates grew alongside it and reliably catch identity and count drift: a gate missing from one of its four surfaces, a rule mirror that fell out of sync, a skill absent from the README tree. What they cannot catch is the slow architectural erosion that comes with growth: two rules that have come to overlap, a discipline added to a CLAUDE.md section that no gate ever enforced, a one-line rule description that drifted in meaning from the rule it describes while the mechanical mirror check stayed green. Each of those is a structural defect invisible to a string-matcher and visible to a designer reading the machinery as a system. The resume `/validate` of 2026-06-23 caught a concrete instance (a routing convention revised in the rule but left stale in two pack-README enumeration descriptions); guardrail-review is the standing, periodic review that hunts that class deliberately rather than waiting for a content sweep to stumble on it. It is judgment-based and maintainer-gated by design: the mechanical layer is the per-PR enforcer, and this skill is the periodic architect's walk-through of what the mechanical layer cannot see.