| name | audit-grounding |
| model | haiku |
| description | Signal-only review confronting the working diff against the repo's source of truth — CONTEXT.md (domain glossary), docs/adr/, and the knowledge base — to surface semantic hallucination: conventions invented without agreement (invented-convention) and domain facts asserted without support (unsupported-domain-fact). Never blocks. Triggered at task end by the grounding-check stop hook; quality bundle.
|
| triggers | {"keywords":["audit grounding","grounding check","invented convention","hallucination check","source of truth"]} |
Source-of-Truth Grounding Audit
Overview
A formatter, a type checker, and a secret scanner judge syntax —
they cannot tell whether a naming pattern was actually agreed by the
team, or whether a sentence in a comment states a true fact about the
domain. Those two failures are semantic hallucination, and the only
thing that can judge them is a reader holding the team's source of
truth in one hand and the diff in the other.
audit-grounding is that reader. It loads the living source of truth
the team already maintains and confronts the diff against it, emitting
two kinds of finding:
invented-convention — a naming, folder, field, or structural
pattern introduced by the diff that is not present in the source
of truth and was never agreed.unsupported-domain-fact — a claim about the domain or business
(in code, comments, or docs touched by the diff) that contradicts
or is absent from the decisions of record.
The skill is signal-only: it never blocks a commit, a task, or a
merge. The verdict comes from a probabilistic reading of documents, so
blocking on it would be worse than the problem it solves. It reports;
the human decides.
When to Engage
Engage when:
- A
Stop hook fires it automatically at the end of an agent task
(the default path — see hooks/stop/grounding-check.sh).
- A reviewer wants to check, before merge, whether an agent invented a
convention or asserted an unsupported domain fact.
Do not engage for:
- Syntactic concerns — formatting, type errors, secrets. Those are the
guardrails bundle's job (pre-commit + loop-level hooks) and they
block; this skill does not duplicate them.
- Non-existent APIs or missing files that break the build — the
compiler and type checker already catch those.
The Source of Truth
Load, in order, and degrade gracefully when an artifact is absent:
CONTEXT.md — the domain glossary and the team's vocabulary.
The primary reference for invented-convention.docs/adr/* — decisions of record. The primary reference for
unsupported-domain-fact.- The knowledge base (
knowledge/) — accumulated facts and
patterns the team has chosen to preserve.
- Module-scoped context — any nested
CLAUDE.md covering the
directories the diff touches.
When CONTEXT.md is missing, fall back to docs/adr/ and the
knowledge base; report the absence as an info note so the team knows
the grounding was partial.
Protocol
- Scope the diff. Use the same ref discovery the other
audit-*
skills use (working tree, a branch, or a PR ref). Restrict attention
to changed lines and the files they touch.
- Load the source of truth in the order above.
- Hunt invented conventions. For each new convention the diff
introduces — a field name, a folder layout, a status enum, a naming
pattern — check whether it is grounded in
CONTEXT.md or an ADR. If
it is not, emit an invented-convention finding citing the diff
location and noting which source it should have matched.
- Hunt unsupported domain facts. For each domain or business claim
the diff asserts, check it against the decisions of record. If it
contradicts an ADR or is absent from all sources, emit an
unsupported-domain-fact finding.
- Report. Emit findings in the same severity-tiered shape as
audit-all, but capped at warn/info — never block. State
explicitly in the report header that the audit is signal-only.
Report Shape
Mirror audit-all's tiered report, with the blocking tier disabled:
warn — a likely divergence the human should look at before
merge (invented convention with no source match; a domain claim that
contradicts an ADR).info — a weaker signal or a partial-grounding note (claim absent
from the source but not contradicting it; CONTEXT.md missing).
Each finding names the diff location, the finding type
(invented-convention / unsupported-domain-fact), the source it was
checked against, and a one-line "what to confirm". The audit emits no
block tier by design.
Anti-Patterns
- Blocking on a finding — forbidden; this skill is signal-only.
- Flagging syntactic issues the
guardrails bundle already blocks.
- Inventing a divergence when the source of truth simply does not cover
the area — say "not covered" (
info), do not manufacture a warn.
- Editing the source of truth or the diff — the skill is read-only.
Integration with Other Skills
audit-config — sibling audit over the configuration surface;
this one audits the diff against the domain source of truth.audit-all — code audits; audit-grounding complements it with
the semantic-grounding dimension and shares its report shape.review-proposals — consumes the proposals the grounding-check
stop hook routes to .octopus/proposals/.guardrails bundle — owns the syntactic, blocking layer this
skill deliberately does not duplicate.
Model tier
This audit is mechanical — it pattern-matches a diff against a fixed
checklist, not deep reasoning. Run it on the cheapest model tier
(--model haiku / each assistant's cheapest). Reserve frontier models
for the architect/dba/security roles that adjudicate the findings
(RM-130).
