g-eskayo/marvin/audit

Audit

Grew out of the 2026-07-09 quarantine investigation (~/.agents/docs/adr/0015-quarantine-review-feedback-loop.md): calibrate.py's own docstring said record_label()'s "intended caller" was "the quarantine review workflow, once built" — and nothing had ever built it. That's the shape of gap this skill exists to find: not a reported bug, a divergence between what the system says about itself and what it actually does.

Full scope/design rationale: ~/.agents/CONTEXT.md's "Intent-vs-reality audit agent" section, ~/.agents/docs/adr/0016-intent-reality-audit-agent-scope.md.

When to trigger

Judged in the moment by the main conversation agent — not scheduled, not requiring the user to name a component. Fire on:

• A direct verification/status question ("did X happen?", "is Y actually working?") that can't be confidently answered from what's already in context — the exact moment that started the 07-09 investigation.
• Noticing a mismatch mid-task between something just read (a docstring, an ADR, a roadmap [decision]/[research] marker, a comment claiming "this is handled by...") and observed system state.
• The user expressing suspicion or asking "what is X supposed to do vs. what does it actually do?"

Don't trigger for: a reported bug with a known symptom (that's diagnose), routine "is this file up to date" checks, or anything where the answer is already directly visible without investigation.

How to dispatch

Use the Agent tool with run_in_background: true (unless the user is actively blocked waiting on the answer, in which case foreground). Do not build a standalone script for this — the Agent tool already provides backgrounding, its own tool-access safety model, and a notify-on-completion mechanism.

Brief the agent like Agent's own guidance demands — a fresh agent, no memory of this conversation:

Investigate [component/subsystem name] for gaps between what it's documented to do and
what it actually does. Read: [specific docstrings/files known to describe intent], any ADRs
in ~/.agents/docs/adr/ mentioning it, any ~/.claude/marvin-roadmap.md entries referencing it
(especially [decision]/[research]-tagged ones that may never have been resolved to [done]).
Then check actual state: [specific files/logs/directories that would reveal real behavior] —
does real behavior match what's documented? Look specifically for: functions whose docstrings
describe an "intended caller" or dependency that doesn't exist; roadmap decisions left open
that were silently defaulted one way in practice; comments/docstrings promising a mechanism
elsewhere in the codebase that was never actually built; a new script implementing the same
*shape* of logic as an existing one on different data (a duplicated pattern, not necessarily
copied code — added 2026-07-09, Gil's direction: every new script is something to maintain
going forward, so check for reuse before assuming something new is needed).
 
For each real divergence found:
- If it's fixable within the exact scope auto_fix.py already covers (NAMING/VERBOSITY
  findings only, files under ~/.agents, never files in auto_fix.py's own _core_files()
  exclusion list) — run auto_fix.py, don't fix it yourself.
- Otherwise, do NOT fix it. Append a suggestion to ~/.claude/suggestions.md using
  architecture-review's exact entry format (## [date] [title], Status: pending, Impact,
  Effort, Why, What, How) so it's queued for review, not silently changed.
 
Report back: what you found, what you fixed (if anything, via auto_fix.py), what you queued.

Output routing

No new dedicated findings file — reuse what already exists, split by risk tier:

• Low-risk, auto-fixable (matches auto_fix.py's existing narrow scope exactly): triggered via auto_fix.py, not fixed directly. Lands in ~/.claude/auto-fix-log.md, same as any other auto-fix run. Session Start step 8 already surfaces this.
• Needs real judgment (a design decision, a logic change, anything auto_fix.py's safety boundary doesn't cover — the shape of all three fixes in ADR 0015): appended to ~/.claude/suggestions.md in architecture-review's exact format, unimplemented, queued for the user's review. Session Start step 2 already surfaces the pending count.

If the investigation finds nothing — intent and reality actually match — don't write anything anywhere. A clean result isn't a finding.

Reporting back to the user

When the backgrounded agent completes, relay a concise summary in the main conversation — what was investigated, what was found (or that nothing was), what got auto-fixed vs. queued. Don't dump the full investigation transcript; the durable record already lives in auto-fix-log.md/suggestions.md.