Use when the user wants to check whether any artifact or work product aligns with their stated best practice preferences — e.g., "check compliance", "linter for best practices", "are we following our pinned practices?", "check this document against our standards".
Instrucciones de origen · Vista previa de solo lectura
name
check-best-practice-compliance
description
Use when the user wants to check whether any artifact or work product aligns with their stated best practice preferences — e.g., "check compliance", "linter for best practices", "are we following our pinned practices?", "check this document against our standards".
source
Sadowski et al. (2015) "Tricorder: Building a Program Analysis Ecosystem Inside Google", ICSE; Ford, Parsons, Kua (2017) "Building Evolutionary Architectures"; Open Policy Agent documentation
Run a compliance check against any artifact using the resolved effective preferences from grimoire.toml. Outputs LSP-compatible JSON (machine-readable, editor-consumable) and an HTML coverage report (human-readable).
Why This Is Best Practice
Adopted by: Linters (ESLint, Checkstyle, Rubocop), architecture validation tools (ArchUnit), and policy-as-code frameworks (OPA, Conftest) encode quality criteria once and run them repeatedly against any artifact. Google's Tricorder runs 30+ analyzers on every CL and blocks 15–20% that would have passed human review; false-positive rate kept below 5% by restricting to well-defined criteria (Sadowski et al., ICSE 2015).
Manual best-practice review is inconsistent — what gets checked depends on who reviews and when. A compliance check applies the same criteria every run and produces a structured, comparable result. Coverage metrics make progress visible: teams that track compliance coverage improve it (Hawthorne effect for quality metrics, confirmed in code review studies at Microsoft Research).
is one-shot and subjective. is repeatable, explicit, and machine-readable — it runs against the user's actual stated preferences (resolved from settings), producing LSP-compatible diagnostics that any editor or CI system can consume directly.
Impact:
Why best:
review-best-practice-fit
check-best-practice-compliance
Sources: Sadowski et al. (2015) "Tricorder: Building a Program Analysis Ecosystem Inside Google"; Ford, Parsons, Kua (2017) "Building Evolutionary Architectures"; ESLint architecture documentation
Steps
1. Resolve the effective spec (silent)
Grimoire-first (preferred): If grimoire MCP is connected, call grimoire_context — use resolved_profiles, domain_sections, and settings_sources as the authoritative resolved spec. Grimoire has already expanded profiles (5-step file search + 4-layer composition) and merged all settings layers. Do NOT re-derive what grimoire already provides.
If CLI only (no MCP): run grimoire context --json and read the same fields from the output.
Fallback (grimoire not installed): Apply all settings layers in precedence order (session > project-local > project-shared > global). Expand profiles, apply domain overrides, remove disabled entries. The resolved spec is the check suite — not any individual layer.
2. Select scope
Default: [a] Full project. Infer from context if user specified a file, directory, or "changed only" — no need to ask. Only ask if scope is genuinely ambiguous.
Keyword in request
Inferred scope
names a file/component
[s] specific artifact
names a directory/module
[r] region
"changed", "diff", "PR", "commit"
[c] changed only
no specific target
[a] full project (default)
3. Evaluate each practice
For each practice in the resolved spec, check the target artifact against its observable criteria. Each criterion: pass, fail, partial, or suppressed (via inline annotation).
Evaluation criteria:
PASS — the artifact satisfies this criterion with direct, observable evidence
PARTIAL — the artifact partially satisfies it (some indicators present, some absent)
FAIL — the artifact contradicts or entirely omits this criterion
Apply to observable content only — do not infer intent or assume unstated behavior.
False positive suppression — any finding can be suppressed inline. Suppressed findings are never dropped from output — they appear as "status": "suppressed" in JSON.
# grimoire-ignore: apply-solid-principles/srp
class LegacyAdapter: ... # intentional god class — refactor blocked by contract
# grimoire-ignore-start: apply-low-coupling
... third-party integration block ...
# grimoire-ignore-end
Configuring suppressions: Findings can be suppressed two ways:
Inline annotation: add # grimoire-ignore: [practice]/[criterion] on the line before the violation
Settings entry: add the practice to the disabled array in grimoire.toml for the relevant domain
Suppressed findings always appear in JSON output with "status": "suppressed" — they are never silently dropped.
4. JSON output (primary)
Always written to .grimoire/reports/compliance-<timestamp>.json (e.g., .grimoire/reports/compliance-2026-06-14T143000.json). Also write a symlink .grimoire/reports/compliance-latest.json pointing to the most recent report.
LSP-compatible schema — consumable by editors, CI pipelines, LSP servers, dashboards:
{"version":"1","timestamp":"2026-06-09T14:32:00Z","mode":"full","scope":"src/contracts/VendorAgreement.md","spec":{"sources":["grimoire.toml","~/.config/grimoire/grimoire.toml"],"resolved_from":"project-shared + global"},"result":"fail","coverage":{"overall_pct":61.1,"practices":{"total":4,"passing":1,"partial":1,"failing":2,"coverage_pct":37.5},"criteria":{"total":18,"passing":11,"failing":7,"suppressed":1,"coverage_pct":61.1},"details":[{"name":"apply-kiss-principle","total":3,"passing":3,"partial":0,"failing":0,"coverage_pct":100.0},{"name":"audit-gdpr-compliance","total":5,"passing":2,"partial":0,"failing":3,"coverage_pct":40.0},{"name":"apply-solid-principles","total":5,"passing":3,"partial":0,"failing":2,"coverage_pct":60.0},{"name":"apply-domain-driven-design","total":4,"passing":0,"partial":0,"failing":4,"coverage_pct":0.0}]},"threshold":{"required":80,"actual":61.1,"status":"fail"},"summary":{"error":2,"warning":1,"info":0,"pass":11,"suppressed":1},"diagnostics":[{"uri":"file:///project/src/contracts/VendorAgreement.md","range":{"start":{"line":42,"character":0},"end":{"line":58,"character":0}},"severity":1,"code":"audit-gdpr-compliance/dpa-required","source":"grimoire","message":"No data processing agreement section found — GDPR Art.28 requires one before processing EU customer data","practice":"audit-gdpr-compliance","criterion":"dpa-required","status":"fail","coverage":{"total":5,"passing":2,"coverage_pct":40.0}},{"uri":"file:///project/src/UserService.ts","range":{"start":{"line":12,"character":0},"end":{"line":45,"character":1}},"severity":2,"code":"apply-solid-principles/srp","source":"grimoire","message":"UserService handles auth, email, and billing (3 concerns) — violates SRP","practice":"apply-solid-principles","criterion":"srp","status":"suppressed","suppressed_by":"inline","coverage":{"total":5,"passing":3,"coverage_pct":60.0}}],"git":{"commit":"abc1234","branch":"main","dirty":false}}
Always populate coverage.details — one entry per practice in the resolved spec, with total/passing/partial/failing/coverage_pct computed from that practice's criteria results. This lets grimoire check and downstream tools display per-practice scores without grouping diagnostics client-side.
Always populate git — read from git context (HEAD commit hash, current branch, whether working tree is dirty). Omit the field entirely (not just empty strings) when not in a git repository.
LSP severity: 1 = Error (FAIL) · 2 = Warning (PARTIAL) · 3 = Information · 4 = Hint
Incremental mode ([c] changed only): output includes "mode": "incremental" and "base_ref": "HEAD~1" so downstream tools know what was checked.
5. HTML report (human summary)
Always generated alongside JSON at .grimoire/reports/compliance-<timestamp>.html.
Structure:
Header: artifact, timestamp, spec sources, overall result badge (PASS/FAIL)
Coverage gauge: overall % with threshold indicator
Per-practice sections: collapsible, progress bar per practice, criteria checklist
Suppressed findings: shown separately, not counted in coverage
Footer: links to settings files, next actions
Color coding: green (pass) · red (fail) · amber (partial) · grey (suppressed).
Suitable for browser viewing or CI artifact upload.
For each FAIL, offer to invoke the relevant grimoire skill, or run the full BPDD cycle:
Fix with:
[1] audit-gdpr-compliance — add DPA section and liability clause
[2] apply-domain-driven-design — extract domain model
[a] Run full BPDD cycle → /apply-best-practice-driven-development
[w] Start grimoire watch — re-check on every file save (local dev continuous mode)
Routing: Auto-invoke only the top-priority FAIL (highest severity, lowest coverage %). For all other FAILs: list them in the output but do not invoke — wait for user to select. User can type a number to fix that specific finding, or [a] to run the full BPDD cycle.
Common Mistakes
Checking against a single settings layer instead of the resolved spec. Always resolve the full precedence chain — project overrides global.
Treating suppressed findings as passing. Suppressed findings are excluded from coverage calculation but counted separately. Review suppressions periodically — suppressed ≠ acceptable.
Setting threshold to 100% on legacy projects. Start with the current coverage as baseline, improve incrementally. A threshold below current = no gate; set it at current + 10% to enforce improvement without blocking work.
When NOT to Use
For one-time exploration — use review-best-practice-fit to discover what practices apply; use this when you know your spec and want to verify alignment
When grimoire.toml is empty — set preferences first; this checks against your stated spec, not general best practices
