# Audit Automation Gaps

> Audit a repo's Claude Code automation (hooks, MCP servers, skills, subagents, scheduled tasks) against the enforcement hierarchy, with evidence-backed PASS/REJECT/CONDITIONAL verdicts, REJECT by default. Use when: 'audit automations', 'what automations should we add', 'are we missing any hooks', 'hook gap analysis', 'should I add an MCP server for X'; pass --implement to apply approved items, or filter by category (hooks|mcp|skills|subagents|scheduled).

- Skill: `melodic-software/audit-automation-gaps-2` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx get-skill add melodic-software/audit-automation-gaps-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/audit-automation-gaps-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/melodic-software/audit-automation-gaps-2

---


**Arguments.** `[--recommend-only] [--implement] [hooks|mcp|skills|subagents|scheduled|all]`. default: all

## Pre-computed context

Automation inventory: !`bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/scripts/inventory.sh" 2>/dev/null || echo "inventory unavailable"`

That block counts files present separately from handlers registered, and marks a scope it could
not read as `unreadable`, not zero. Treat it as a starting point, never a finding. Re-derive any
count a verdict leans on; where your count disagrees with the block, report both and say which the
verdict used. A partial inventory that reads as complete is this skill's recorded failure: see
[context/gotchas.md](context/gotchas.md).

## Purpose

Find evidence-backed automation gaps, where no mechanism in the enforcement hierarchy covers the
concern, not surface-level "you don't have X" observations.

**Design principle**: most "missing automation" gaps are already covered by higher enforcement levels
(compiler, analyzers, build-time checks, architecture tests, behavioral rules). Prove a gap exists
before recommending a solution. The default verdict is REJECT, not PASS.

**The enforcement hierarchy** is the rung list in
[context/enforcement-ladder.md](context/enforcement-ladder.md); this skill's selection rule there
is the strongest rung that covers the concern. A consuming repo's own hierarchy, documented in
`CLAUDE.md`, in an `AGENTS.md` the session reads natively (in place of or beside a `CLAUDE.md`), or
in rules files, overrides this default ordering: read and use theirs.

A proposed deterministic check meets the "Guardrail criterion" section of that same file before it
earns a PASS verdict.

## Boundary: no machine-readable hook enumerator

This skill ships no hook-enumeration mode, by decision. The native `/hooks` menu already reports the
harness's resolved set, with each hook's source; a script here would restate that set from the
settings files instead of the harness's own resolution, the weaker source. Revisiting the decision
first requires recording a native-surface verdict for `/hooks` in whatever registry the repository
keeps for native-overlap decisions, because whether such a reference should exist is a human's
call. This paragraph is a boundary, not a routing verdict.

- **Pointer**: when you need what `/hooks` lists, or what it shows for a selected hook, fetch
  [the /hooks menu](https://code.claude.com/docs/en/hooks#the-/hooks-menu) live.
- **As of**: 2026-10-11
- **Recheck trigger**: that section stops showing each hook's source, or the menu stops listing
  the resolved set of configured hooks.

## Adapting to your environment (graceful degrade)

Where a phase names an adjacent capability (a research skill, an implementation-planning skill, a
work-item tracker, an outcome verifier), it is optional: use your setup's equivalent if it has one,
else follow the inline guidance, which stands on its own. Neighboring questions belong to the
sibling `audit` skill (are the config FILES correct?) and the `audit` skill in the `harness-memory`
plugin (is the instruction layer healthy?).

This skill proposes NEW automation. Whether automation already in place still earns its carry cost
is owned by `/overengineering:audit`, whose evidence-earned-keep walk treats every incumbent as a
retirement candidate until evidence keeps it. Send a retirement question there when the
`overengineering` plugin is installed; when it is not, the **Already enforced** gate still names the
mechanism covering a concern, and any retirement observation is recorded in the verdict for the
human, not acted on here.

## Arguments

Parse `$ARGUMENTS` for:

- **`--recommend-only`**: Run evaluation phases only, skipping implementation. Default behavior
- **`--implement`**: After presenting validated recommendations, implement user-chosen items sequentially
- **Category filter** (`hooks`, `mcp`, `skills`, `subagents`, `scheduled`): Limit to a specific automation type. Default: `all`

There is deliberately no `ci` category. Two skills own that ground: the `ci-lanes` layer of
`/overengineering:audit` judges whether each lane already running still earns its carry cost, and
`/corrections:codify` maps one recurring mistake or review finding to the strongest enforcement rung
that can catch it, including a check that runs in CI. Route a CI concern to whichever fits when the
`overengineering` or `corrections` plugin is installed; when neither is, record the concern in the
verdict as out of scope and name its owner, rather than widening this audit's categories.

## Track progress

For any deep-dive run (Phases 1-4), keep a phase checklist and tick each phase and every anti-noise
doctrine check as it completes, in-response or in a copy of
`${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/templates/checklist.md` wherever the consuming
repo keeps working task notes. Phase 4 is SKIPPED in default `--recommend-only` mode.

## Phase 1: Discover Candidates (Self-Generated)

Analyze the automation landscape directly, with no external recommender dependency.

### 1.1 Inventory Current State

The pre-computed block already ran
`bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/scripts/inventory.sh"`; re-run it directly
if that block is missing. It settles the per-scope hook-location counts, the component counts, and
the enablement inputs. It leaves three things to you: effective plugin enablement,
because `enabledPlugins` follows precedence rather than the merge that hook entries follow; the
contents of any frontmatter `hooks:` block, which it counts but does not parse; and plugins
installed on the machine from outside this repository. Then read:

| What | Source |
|------|--------|
| Hooks | Every hook location: user + project + local `settings.json` → `hooks`, managed policy settings when readable, each enabled plugin's `hooks/hooks.json`, and skill or agent frontmatter `hooks:`. Also record which hook EVENTS you considered: the documented set is far wider than `PreToolUse` and `PostToolUse`, and an event nobody looked at cannot surface a candidate, so a no-gaps hooks verdict names the events it examined |
| MCP servers | `.mcp.json` + `settings.json` → `disabledMcpjsonServers` |
| Permissions | `settings.json` → `permissions` (deny/ask/allow) |
| Enforcement | Ecosystem-specific build config (`<root-build-config>`, e.g. `Directory.Build.props` for .NET, `pyproject.toml` for Python, `package.json` for TS/JS), `.editorconfig` (top 20 lines), any enforcement-hierarchy section in the repo's own instruction files |
| Codebase shape | File counts per language: `find . -name "*.cs" \| wc -l`, same for `.py`, `.ts`, `.sh`, `.ps1` |
| Incident history | `git log --oneline \| wc -l` for the denominator, then a `--grep` count for the concern. That count is a CEILING, never a frequency: read a sample before citing one, and carry the match count, the denominator, the sample size and what the sampled commits actually were into the verdict |

### 1.2 Gap Analysis

For each automation category, check for gaps with the checklists in
[context/gap-analysis.md](context/gap-analysis.md): Hooks (formatter exists? fast enough? higher
enforcement already covers?), MCP Servers (configured? CLI equivalent? service in use yet?), Skills
(skill exists? frequency? simpler mechanism?), Subagents (value over hook/skill? isolation help?
plugin exists?), Scheduled (tracked in the repo's work-item tracker? Dependabot/CI covers? right
durability model?).

### 1.3 Generate Candidate List

Produce a numbered list of candidates, each with category and one-line rationale. Target
**5-10 candidates**. Cast a wide net and include borderline items: the quality gates filter, and
rejecting with evidence beats silently excluding.

## Phase 2: Deep-Dive Each Candidate

**Batch the Explore phase** (read all configs once), then evaluate candidates sequentially.

### 2.1 Explore (Local Codebase)

For each candidate:

- **Read the relevant config/code**: the specific files that would be affected
- **Check the enforcement hierarchy**: walk the ladder's rungs up from the weakest (`automated-review`) to the strongest (`make-impossible`). Stop when you find coverage. Document which level covers it
- **Check incident history**: `git log --grep` for related problems, then read a sample of the hits.
  The count is a **ceiling**, not a count of incidents or a frequency. Report the match count, the
  total commit count, the sample size read, and what the sampled commits actually were
- **Measure performance**: if the candidate involves a CLI tool as a hook, time it:

```bash
time <tool-command> 2>&1 | tail -5
```

Judge that measurement against the **consuming repository's own documented hook budget** where one
exists, and say which source the threshold came from. No upstream latency budget exists, so any
fixed number this skill supplies is a house rule, labeled as one in the verdict. We judge a
`PostToolUse` hook's cost as turn latency, never as a blocked call; the record that points at the
live per-event blocking table is in hook-timing.md. For the budget-resolution ladder, per-event
costs, the documented levers, and the dated upstream-fact records, read
[context/hook-timing.md](context/hook-timing.md).

### 2.2 Research (One Mandatory Batch, Then Conditional)

Research splits by who owns the fact.

**Mandatory: one batched docs fetch for harness mechanisms.** Any candidate whose mechanism is a
Claude Code surface gets its harness facts fetched before its verdict, however settled the local
evidence looks. That covers hook event semantics and what each event can and cannot block,
`async` and `timeout` behavior, MCP server scope and configuration, and skill, agent or plugin
frontmatter fields. Collect every such question across every surviving candidate into ONE fetch
pass. The batch is mandatory because a docs pass routinely reshapes a candidate that local evidence
had settled: a per-event exit-code gate can look settled locally while the event's decision
control upstream says it never fires, which no local reading surfaces.

- **Pointer**: when a candidate gates on a hook event's exit code, fetch that event's decision
  control live, for example
  [hooks: PermissionRequest decision control](https://code.claude.com/docs/en/hooks#permissionrequest-decision-control).
- **As of**: 2026-11-10
- **Recheck trigger**: that section changes which exit codes or decision fields the event honors.

**Conditional: facts the harness does not own.** Third-party tool performance, an ecosystem's
standard formatter, server stability and auth, known issues in a tool the candidate would run. Fetch
these only where the verdict turns on them.

**When a conditional fetch is skipped, record how the fact was settled** in that candidate's
verdict: the measurement taken, the file read, or the existing dated record relied on. "Not needed"
and "not done" must stay distinguishable in the artifact.

Group related queries to minimize agent count, and run the mandatory batch as one dispatch for all
candidates.

**Per-candidate research questions by type:**

| Type | Research Questions |
|------|-------------------|
| **Hook** | Tool per-file performance? Ecosystem standard formatter? Known hook compatibility issues? |
| **MCP Server** | Server stability? Auth requirements? CLI equivalent comparison? Known issues? |
| **Skill** | Existing solutions? Frequency justification? Similar skills in marketplaces? |
| **Subagent** | Can a hook/skill do this more deterministically? Is context isolation needed? |
| **Scheduled** | Platform requirements (CLI vs Desktop vs cloud)? Durability model? Existing coverage via Dependabot/CI/work items? |

Verify Claude Code mechanisms against official docs
([code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks),
[code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp)); use web search for tool
performance and community practices. Research agents gather evidence and state no verdict; the
gates in 2.3 read that evidence and decide.

### 2.3 Vet / Validate (Quality Gates)

A candidate **fails** if ANY gate triggers.

**Run this gate in a fresh context.** Phase 1 generated these candidates in the context now asked
to refuse them, and a context that produced work is a biased judge of it. Dispatch a fresh-context
subagent with the candidate list, the Phase 2.1 and 2.2 evidence, and this table, and keep the gate
results it returns. Where the environment exposes no subagent surface, run the gates inline and say
in the report that the refusal gate ran in the context that generated the candidates, so the bias
is visible.

**Verification level.** Before this gate, run `bash "${CLAUDE_PLUGIN_ROOT}/lib/read-verification.sh" --plugin harness-config --skill audit-automation-gaps`
and copy its line into the report ([levels](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/verification-level/README.md)).
`standard` and `strict` are the paragraph above. Under `light`, and `off`, which acts as `light`
here, dispatch neither this gate nor the Phase 4 step 6 reviewer, and never run either inline in
its place: write `verification: skipped (<level>)` where the gate results or the review would go.
The gate's verdict is this audit's product, so each candidate is listed as `unverified`, never
`PASS`, `CONDITIONAL` or `REJECT`, and none is persisted for `--implement`.

| Gate | Condition | Evidence Required |
|------|-----------|-------------------|
| **Already enforced** | A higher enforcement hierarchy level covers it, and the shift-left carve-out below does not apply | Name the level and mechanism; where the candidate claims the carve-out, the result of each of its three conjuncts |
| **Too slow** | Measured cost exceeds the resolved budget ([context/hook-timing.md](context/hook-timing.md)) for the event's actual cost: a blocked call on a blocking event, turn latency on `PostToolUse` | Timing measurement + the budget it was judged against and that budget's source |
| **Not scriptable** | The mechanism can't be automated with available tools | Specific limitation cited |
| **Zero incidents** | A read sample of the matching commits shows the problem has never occurred. A `--grep` count alone never triggers this gate, in either direction | Keyword match count, total commit count, the sample size read, and what the sampled commits turned out to be |
| **Already exists** | A skill, behavioral rule, or convention already handles it | File path and line |
| **YAGNI** | Low frequency (<5% of commits) AND low severity, where the frequency is sampled rather than counted | The match count over total commits as the ceiling; plus a sampled frequency whenever that ceiling is 5% or higher, and none when it is already below |
| **Platform mismatch** | Requires infrastructure the user doesn't have | Platform requirement cited |
| **Premature** | Depends on unfinished work (planned database, future CI) | What's missing cited |

#### Incident counts are ceilings

**Zero incidents** and **YAGNI** both read a `git log --grep` count, and that count is an upper
bound on the concern, not a measure of it: it counts commits whose message mentions a word. On this
marketplace at merged main `49912c63`, `secret|gitleaks` matched 209 of 2202 commits while the first
15 read were dependency bumps, component syncs and CI pins, with no leaked secret among them, and
`markdownlint|lint` matched 1128, about 51%. Cite a frequency only after reading a sample and saying
what the sampled commits were.

The discipline is asymmetric, which keeps it cheap. A ceiling already below the 5% **YAGNI**
threshold settles that gate on its own, because the true frequency cannot exceed the ceiling. Only
a PASS, or an affirmative claim that the concern is frequent, has to pay for a sample.

#### Shift-left carve-out to Already enforced

A candidate that deliberately duplicates a check a higher rung already runs, at edit time, is not
rejected by **Already enforced** alone. Duplication earns a hearing only when all three conjuncts
below hold, each stated with its evidence. Any conjunct that cannot produce its evidence fails, and
the candidate returns to REJECT. The carve-out changes which gate decides, never the REJECT-by-
default posture: a candidate that clears all three is handed to **Too slow** and the remaining
gates, not passed.

1. **Sampled frequency, never incident history.** The concern clears **Zero incidents** and
   **YAGNI** on a count sampled from the current tree, not from `git log`. A check the higher rung
   already runs suppresses its own incidents, so zero incidents in history is evidence about the
   incumbent check, not about the concern. Sample instead: run the check over a stated N of files
   or of recent edits and report hits over that N. Falsified when the sampled hit rate is under
   5 percent, which is the **YAGNI** threshold read against the sampled denominator. State N and
   the hit count, so the arithmetic is checkable rather than asserted.
2. **Placed where the check-placement rubric puts it.** A report-only duplicate (one that only
   prints findings) goes in a git `pre-commit` hook that blocks the commit on findings in changed
   lines, or `pre-push` when its measured run is over the commit budget but within 60 s, never in
   a per-edit `PostToolUse` hook; a formatter duplicate may also rewrite once per batch from
   `PostToolBatch`, sending the model nothing. CI keeps re-running the check on the change.
   Falsified by a per-edit hook that sends findings to the model, a Claude Code hook that blocks a
   tool call to enforce a report-only check, or documentation presenting the local hook as a
   replacement for the CI check. The rubric is this marketplace's house rule, not upstream
   guidance: [check-placement](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/check-placement/README.md#the-rubric).
3. **Fits the remaining budget, as a hard gate.** Resolve the budget through the two-rung ladder in
   [context/hook-timing.md](context/hook-timing.md), then report four things: the measurement, the
   budget row judged against, which rung supplied it, and the headroom arithmetic. Falsified when
   the measured cost exceeds the stated headroom. Where the consuming repository documents a budget
   and its own accounting records no headroom on that row, the verdict is REJECT at **Too slow**
   whatever conjuncts 1 and 2 returned; the carve-out does not reopen a budget the consumer says is
   already overspent.

Why the carve-out is scoped this narrowly: the hooks documentation states that hooks give
"deterministic control: certain actions always happen rather than relying on the LLM to choose to
run them", which supports duplicating a check so it runs deterministically for every author. It
says nothing about whether a check belongs in CI or in a hook, so no latency or placement argument
may be offered as an upstream one. The record for both facts:

| Claim | Basis | As of | Recheck trigger |
|---|---|---|---|
| Hooks exist to give deterministic control, so certain actions always happen rather than relying on the LLM to choose to run them | [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide), opening paragraph | 2026-09-13 | A re-fetch finds the opening statement of purpose no longer matching this row |
| No official page addresses whether a check belongs in CI or in a hook | Absence record in [context/hook-timing.md](context/hook-timing.md), upstream-fact records | 2026-09-12 | That record's own trigger fires |

These gates answer *should* we mechanize. Whether a candidate *can* be, and how far up the hierarchy
it climbs, is a separate enforceability question: the **Not scriptable** gate maps to concerns no
hook type reaches, **Already enforced** to a deterministic finding already escalated. `prompt` and
`agent` hooks do evaluate reasoning-only concerns.

- **Pointer**: before proposing a `prompt` or `agent` hook, fetch its status and fields live at
  [hooks: prompt and agent hook fields](https://code.claude.com/docs/en/hooks#prompt-and-agent-hook-fields).
- **As of**: 2026-11-10
- **Recheck trigger**: that section changes either type's status or the fields it accepts.

Produce a verdict per candidate:

- **PASS**: clears all gates, provides genuine value
- **CONDITIONAL**: value exists but only under specific conditions (document the condition)
- **REJECT**: fails one or more gates (cite which gates and evidence)

## Phase 3: Present Results

### Summary Table

```markdown
| # | ID | Candidate | Category | Verdict | Key Evidence |
|---|----|-----------|----------|---------|--------------|
| 1 | h1 | ... | hooks | REJECT | [gate]: [evidence] |
| 2 | s1 | ... | skills | PASS | No existing coverage, [n] of [total] commits, [k] sampled |
```

`ID` is a short stable token for the candidate, and `Category` is one of `hooks`, `mcp`, `skills`,
`subagents`, `scheduled`. Both are what the persisted artifact is keyed and filtered by, so a row
without them cannot be written back or read by `--implement`.

### Detailed Verdicts

For each candidate, provide:

- **Verdict** with gate results
- **Evidence** (timing data, git history counts, enforcement mechanisms found)
- **For PASS/CONDITIONAL**: implementation plan (files to change, size, test strategy).
  A `PASS` or `CONDITIONAL` without a plan cannot be persisted, because the plan is precisely what
  `--implement` reads back in a later session

**Size.** Resolve `time_units` once, lowest layer first: the default `false`; the user's option,
`${user_config.time_units}` (empty or a literal, unexpanded placeholder means unset); and the
`time_units` key of `<home>/harness-config.yaml`, which wins when set. `<home>` is what
`bash "${CLAUDE_PLUGIN_ROOT}/lib/resolve-convention-home.sh"` prints, else `docs/conventions`; its
exit 5 (the root is `$HOME`, an ancestor of it, or not a git working tree) skips that layer, and a
missing file or key leaves it unset. A value other than a bare `true` or `false` is named with its
file or option, the key and the value, and that layer is dropped: a valid repository value still
wins over an invalid user value, and an invalid repository value resolves `false`, never the
user's value.

Only a resolved `true` turns it on. State the resolved value, `on` or `off`, and the layer that
supplied it at the top of the report.

- **Off:** Small, Medium or Large, with what makes it that size (files, moving parts, unknowns).
- **On:** an estimate in minutes, hours, days, weeks or a named span such as an afternoon, with
  what makes it that size.

Either way, a time budget the user states is quoted in the user's words.

**Order by value/impact**, highest value first. Value = frequency × severity × ease of implementation.

### Maturity Assessment

End with a one-paragraph assessment of the repo's automation maturity: what's well-covered, the
genuine gaps (if any), and whether the automation investment fits the project stage.

If items pass: "Which items would you like to implement? I'll work through them sequentially."

If no items pass: State that clearly. A clean bill of health is a valid outcome.

### Persist the findings

Write twice, because the selection does not exist yet when the verdicts do.

Write once as soon as the verdicts are presented, so an audit is never lost to a session that ends
at the question above. Every candidate carries `approved: false` at this point, which is true: the
human has not chosen yet.

Write again once the human answers, with `approved: true` on the candidates they picked. Run ids
are suffixed rather than overwritten and `read` serves the newest run, so the second write is what
a later `--implement` sees, and the first survives as the record of what the audit actually found.
Skip the second write only when nothing passed, since there is then nothing to select.

```bash
bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/scripts/findings-state.sh" write \
  --plugin-data "${CLAUDE_PLUGIN_DATA}" --findings <file-or-->
```

We pass `${CLAUDE_PLUGIN_DATA}` as that argument rather than relying on the shell to have it; the
script exits 2 rather than guessing when it is missing.

- **Pointer**: when deciding how a script receives a plugin path variable, fetch
  [plugins manifest reference: where each variable resolves](https://code.claude.com/docs/en/plugins/manifest-reference#where-each-variable-resolves)
  live.
- **As of**: 2026-11-10
- **Recheck trigger**: that section starts exporting the variable to commands run through the Bash
  tool.

The payload is exactly one JSON object with a `candidates` array, each entry carrying
`id`, `candidate`, `category`, `verdict`, an `evidence` array, and a `plan` object on any `PASS` or
`CONDITIONAL`. Each entry also carries `approved`, the boolean that records the human's selection.
A malformed payload, or a stream carrying more than one document, exits 3 and writes nothing,
listing every problem at once.

Writes are all or nothing. A run id already taken is reserved under the next free suffix rather than
overwritten, so two runs racing for one id both survive and each is told the id it actually got.

Findings are keyed per project, so one checkout never reads another's verdicts. This tree is the
only durable copy, and an uninstall can delete it.

- **Pointer**: when deciding whether the findings survive an uninstall, fetch
  [plugins CLI reference: what an uninstall deletes and keeps](https://code.claude.com/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)
  live.
- **As of**: 2026-11-10
- **Recheck trigger**: that section changes whether the plugin data directory survives an
  uninstall.

## Phase 4: Implement (if `--implement` or user requests)

Recover the prior run's verdicts first, rather than re-deriving them:

```bash
bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-automation-gaps/scripts/findings-state.sh" read \
  --plugin-data "${CLAUDE_PLUGIN_DATA}"
```

That serves this project's newest run. Implement the candidates whose `approved` is `true`. Where
no candidate carries `approved: true`, the stored run predates the human's selection, so ask which
items to implement rather than treating every passing candidate as chosen: a `PASS` verdict is this
skill's judgment, not the operator's consent.

Exit 4 means this project has no stored run, which is the cue to audit first rather than to
implement from memory; the script never falls back to another project's artifact. Exit 5 is the different answer: stored state exists but cannot be trusted,
because a file is unreadable or a previous write half landed. Treat 5 as a state to repair or
re-audit, never as an absence, and say which of the two you got. `list` shows the earlier runs when
a specific one is wanted.

For each user-selected item:

1. **Explore**: re-read current state (may have changed since evaluation)
2. **Research + Validate**: verify the implementation approach against current docs. The audit
   already ran one batched fetch for Claude Code surfaces in Phase 2.2, so re-fetch only what the
   stored evidence does not already settle, or what has plausibly moved since the run was written.
   For a mod, load the built-in `plugin-authoring` skill before planning: its type declarations
   are the authority for the running build, and they win where a docs page disagrees
3. **Plan**: detailed implementation steps
4. **Implement**: execute with incremental validation and commit checkpoints
5. **Test**: verify the automation works (run hooks, test skills, etc.)
6. **Review**: dispatch a fresh-context reviewer to check the change against existing patterns,
   since the context that wrote it is a biased judge of it. It lists only problems that should
   block the change, each with file and line, why it is wrong, and how to show it fails. Where no subagent surface exists,
   review inline and record that the review was same-context. Under a `light` or `off`
   verification level (2.3), dispatch no reviewer and review nothing inline: write
   `verification: skipped (<level>)` in the review's place
7. **Verify**: build/test the repo if code changed, confirm no regressions

Route steps 2-7 through the consuming environment's own workflow skills when it has them; the inline
steps stand on their own otherwise.

## Quality Principles

Principles that govern every verdict:

1. **The enforcement hierarchy is your first check.** Most "gaps" are covered by the compiler-through-git-hooks levels
2. **Measure, don't assume.** Time every tool before recommending it as a hook. A formatter looks perfect until you measure 15+ seconds per file
3. **Check incident history, then read it.** Zero incidents across 100+ commits is strong evidence the problem doesn't exist in practice, but a `git log --grep` count is a ceiling, and a check a higher rung already runs suppresses its own incidents
4. **Behavioral rules are valid enforcement.** A rule in CLAUDE.md, or in a natively read AGENTS.md, is legitimate coverage; not everything needs a hook or script
5. **YAGNI is a quality gate, not laziness.** Automation for a task at 4% frequency is premature
6. **Premature is worse than missing.** Adding a database MCP before a database exists, or scheduling before CI exists, creates maintenance burden for zero value
7. **A clean bill of health is a valid outcome.** Not finding gaps means the automation is mature; don't manufacture recommendations to justify the audit

## Next

- Candidates passed and are ready to build: `/planning:plan`.
- Candidates passed and need slicing into grabbable tickets first: `/work-items:decompose`.
- The run raised a question about automation already in place: `/overengineering:audit`.
- A verdict is worth revisiting later rather than acting on now: `/work-items:track add`.

## Gotchas

Five failure modes this skill has produced, each with its evidence and dated upstream records: a partial inventory anchoring every later verdict, keyword counts read as
frequencies, `PostToolUse` candidates phrased as gates, an `exit 2` gate on `PermissionRequest` that
is silently inert, and a candidate generator that reaches four of the
[documented hook events](https://code.claude.com/docs/en/hooks#hook-events).
Read [context/gotchas.md](context/gotchas.md) before any run whose verdicts a human will act on.

