audit

skills/groundwork/commands/audit.md

A structured assessment of how well a repo's information environment serves an AI agent. Defensible numbers, prioritised findings, three commands worth running next.

When to use it

  • Before a major refactor, migration, or stack change.
  • Before onboarding a new hire.
  • On a quarterly cadence.
  • When the team is saying "AI is unreliable." The audit usually shows why.

What it produces

  • docs/context-audit-<YYYY-MM-DD>.md: the full audit file.
  • A 10 to 15-line chat summary: overall score, per-layer scores, top three findings, recommended next commands.
  • Optionally docs/context-audit-<YYYY-MM-DD>.html: an interactive report (see below).

How it works

  1. Map the repo against each of the five layers. What exists, what is missing.
  2. Content-quality scan on AGENTS.md. Beyond "file exists": every Style rule must be behaviourally anchored (verb plus named technology, command, or pattern); every verification command must resolve to a real script in package.json or equivalent; Boundaries → Always and Ask first must have project-specific entries beyond the default plan-mode triggers; negative-space.md must have content beyond the template stub.
  3. Score each layer 0 to 5, with one sentence of evidence per score.
  4. Conformity check. Pick a small task, have the agent attempt it in a scratch branch, run verification. If you cannot run it, say so. Never fabricate.
  5. ADR-coverage scan. Last 30 days of merges. Decision-shaped commits without an ADR become findings, each linking to groundwork adr from PR.
  6. Sort findings. P0 for missing verification commands and stale stack info. P1 for vague Style rules (with quoted line and an anchored rewrite suggested). P2 for empty Boundaries tiers and stub negative-space. Specific filenames only.
  7. Recommend three commands. Not six. The highest-leverage moves for the highest-priority findings.
  8. Optional HTML report. The command asks once whether to emit an interactive HTML version. If yes, writes a self-contained file you open in a browser to walk the findings and ship a remediation plan.

The interactive HTML report

Opt-in. Same findings, different surface: a self-contained docs/context-audit-<date>.html file you open in any browser. No server, no dependencies, no external assets.

  • Hero with overall score and per-layer scores (Project weighted 2×).
  • Findings grouped P0 → P2, varied density by severity. Each row has inline Fix now / Defer / Dismiss controls; picking one reveals the right input below (an anchored rewrite for vague rules, a stub for missing scripts, a free-text reason for dismissals).
  • A live remediation panel that accumulates your decisions. Click Generate remediation plan and your browser downloads audit-remediation-<date>.md.
  • Light mode by default; dark mode toggle.

The downloaded remediation file is the input to apply: that command reads the plan, validates the schema, dry-runs the changes, applies on confirmation, runs the fast verification, and offers rollback if it fails. Audit decides, you decide, apply enacts. Closed loop.