| name | checking-coding-standards |
| description | Use to check code against a project's registered gloria Coding Standards. Fires for plain requests to compare code with the rules — "check this against our standards", "does this drift from our rules/conventions", "are we following our own standards", "review this for standards compliance", "check this PR against our standards", "run a standards check", "audit the repo for drift", "has our code drifted from the rules" — including before or after implementing a change in a project that has registered standards. Runs diff-scoped checks (the per-PR workhorse), cheap metadata checks (render stamp + rule-evidence staleness), or a full audit (snippet staleness included), and reports findings to the gloria drift ledger via report_check_run. Read-only: findings, never edits. |
Checking Code Against Standards
"Check against our standards" is a gloria action; reporting means calling report_check_run
When the user asks to check, audit, or compare code against the project's
standards / rules / conventions — or asks whether code drifts from them —
that is this skill, driven by gloria's registered library (get_standards), not
an ad-hoc code review from memory. Reporting the findings — the sync half —
means calling the gloria MCP tool report_check_run, which records them to
gloria's drift ledger; it is not just printing a summary in chat. Load the
standards, evaluate, then report_check_run (even when findings are empty).
Overview
The probe half of gloria Coding Standards: evaluate code against the project's registered rules
and snippet library, and report what has drifted to the backend ledger. The agent is the probe;
the backend is the ledger — this skill never edits source, it only observes and reports.
Core principle: every finding traces to a specific rule or snippet id. A finding that can't
name what it violates is a vibe, and vibes-based findings poison the ledger — they train people
to dismiss it.
When to Use
- Reviewing a PR / branch in a project with registered standards (diff-scoped run)
- A periodic or on-demand whole-repo recalibration (full audit)
- Any check invocation at all (metadata checks ride along free)
Don't use for: fixing the violations (report first; fixing is a separate, explicitly
requested task); repos with no registered standards — confirm with get_standards and stop if
version is null.
Process
Step 0 — Load the standards
get_standards { projectSlug } → version N, rules[]
If version is null, there is nothing to check against — say so and suggest
extracting-coding-standards. Record startedAt (Unix seconds) now; every finding this run
produces must cite a ruleId or snippetId from what this call returned.
Step 1 — Metadata checks (every run, cheap)
- Render staleness: the stamp
<!-- gloria:standards v<M> --> may live in CLAUDE.md,
AGENTS.md, or a standalone file either of those points to (e.g. CODING-STANDARDS.md) —
check all three and take the highest M found. M < N, or no stamp found anywhere, → one
render_stale finding, detail naming both versions and which locations were checked.
- Rule-evidence staleness: for each rule, check whether its
evidence.sources files
changed since the rule's updatedAt (git log -1 --format=%ct -- <file>). Changed →
rule_stale finding for that ruleId. The rule may still be right — staleness means
"re-derive and confirm", not "wrong".
Step 2 — Pick the code scope
- Diff-scoped (default): the PR diff, or
git diff <last-checked>..HEAD when invoked
outside a PR. This is the workhorse — cheap enough to run per-PR.
- Full audit (on demand / periodic): every source file in scope of any rule. Also
re-examines snippet exemplars (Step 4).
Step 3 — Evaluate the code
For each changed (or in-audit) file, against each rule whose scope covers it:
rule_violation — the code does what the instruction forbids (or omits what it
requires). Finding: ruleId, file, line, and a detail quoting the offending shape.unattributed_duplication — the code re-implements a pattern that has a canonical
snippet, with no gloria:snippet marker. Finding: snippetId, file, line.- Marker verification — where a
gloria:snippet <project>/<id> (verbatim|adapted) marker
exists: the id must resolve (via find_snippets or get_standards) and the code must be a
faithful adoption — structure matching, placeholders filled. A (verbatim) claim over a
structurally changed body, or a marker pointing at a nonexistent snippet, is a
rule_violation-grade finding against the snippet's linked rules (cite those ruleIds).
Step 4 — Full audit extras
- Re-score known open findings: still true at today's code? (Ones that no longer reproduce
will auto-resolve when you report without them.)
snippet_stale — for each snippet, compare its structure to the repo's current dominant
instances of that pattern. If the living code has moved on (new field conventions, changed
layering) the exemplar is stale: finding with snippetId and what diverged.
Step 5 — Apply the false-positive guardrails
Before reporting, drop any finding that:
- Names no rule/snippet id — not reportable, ever.
- Is documented divergence — an adjacent comment justifying deviation from a
strong-match snippet or an
observed-authority rule. That's intent, not drift.
(enforced rules get no such exemption.)
- Has no coverage — a language or pattern with no registered rule/snippet. Absence of a
snippet is not a violation.
Step 6 — Report
report_check_run {
projectSlug, kind: "diff" | "audit" | "metadata",
triggeredBy: "pr" | "manual" | "cron",
standardsVersionChecked: N,
scopeDetail: { diffRange?, prRef? },
startedAt, completedAt,
findings: [{ type, ruleId?, snippetId?, file?, line?, detail }]
}
Report even when findings are empty — a clean run resolves previously-open findings in its
scope and refreshes last-checked for the staleness cron. Then summarize for the user: counts
by type, the specific findings with file:line, and what auto-resolved.
Common Mistakes
| Mistake | Fix |
|---|
| Findings with no rule/snippet id | Guardrail 1: drop them; if the concern is real, propose a new rule instead |
| Flagging documented divergence | Read the adjacent comment; observed/snippet divergence with a reason is intent |
| Flagging uncovered languages/patterns | No coverage → no finding |
| Fixing violations in the same run | Read-only; report, then fix only on explicit request |
| Skipping the report because findings were empty | Empty reports resolve stale findings and feed last-checked |
| Diff runs re-reporting old, unchanged findings | Diff scope evaluates changed code; the ledger dedups by key, but keep detail current |
| Treating rule_stale as "rule is wrong" | It means "evidence changed — re-derive and confirm" |
Quality Checklist
