---

title: Session: Audit Command Overhaul tags: [journal, session, audit, specs, knowledge] created: 2026-05-22 updated: 2026-05-22 status: active related:

• “platform”
• “kitchenware-spec”

---

Session: Audit Command Overhaul

Date: 2026-05-22 Scope: .opencode/commands/audit.md, knowledge/inventory/specs/, knowledge/inventory/audit/, knowledge/inventory/_index.md, knowledge/index.md

Summary

Overhauled /audit command from implicit-standards assessment to spec-driven audit with persistent knowledge output. Introduced per-component specs (Must Do/Must Not Do/Contracts) and ranked issue lists (P0-P5). Validated end-to-end flow with kitchenware dry run.

Key Learnings

New Patterns

• Spec-first audit pattern: Define what code SHOULD do before auditing what it does. Without specs, audit can only flag pattern violations — not missing, excessive, or mis-scoped code. Specs make audit meaningful.
• Spec file format: Must Do / Must Not Do / Contracts / Dependencies / Quality Gates — deliberately minimal, focused on code contracts not quantitative targets.
• Issue priority ranking (P0-P5): BLOCKER / VIOLATION / MISSING / DEAD / DRIFT / FRICTION. Replaces per-component status badges (READY/ROUGH/STALE/DEAD) with actionable, ranked issues across all components.
• Agent-per-component spawning: 2-3 agents at a time within a group. Groups ordered by dependency: src/ packages -> models -> endpoints -> infra -> workflows.
• Knowledge persistence for audits: Audit reports written to knowledge/inventory/audit/ as version-controlled docs, not chat dumps. Enables incremental re-audits and historical comparison.

Decisions

• Per-submodule specs (not per-logical-component): submodules are the natural audit unit, maps to existing directory structure.
• Code contracts only in specs (not quantitative targets): targets belong in training journal / model inventory docs. KISS principle.
• Single platform.md for cross-component specs (not one per workflow): one file for the big picture, component specs handle the rest.
• Trust existing specs by default: /audit audits code against existing specs. Use /audit --refresh-specs to re-derive. Keeps user in control of “what should exist” vs “what currently exists”.
• Spec→audit→clean→spec-update feedback loop: edit spec first, then audit reveals code divergence, then clean code to match.

Pitfalls

• Spec/code count mismatches are common: kitchenware spec said “7 nucleotides” but code has 8 (4 RNA + 4 DNA). Code was correct, spec needed update. When bootstrapping specs from code, verify counts against the actual constants, not assumptions.
• remove_water checks wrong field: uses structure.elements == "DOD" but DOD is a residue name, not an element. No-op bug — always false. Found via spec-driven audit; wouldn’t have been caught by simple pattern checks.
• super(ClassName).__init__() without self: StructuresDataset calls super(StructuresDataset).__init__() instead of super().__init__(). The former passes the class but not self, so parent __init__ never runs. Currently harmless (Dataset __init__ is empty) but incorrect pattern.

Skill Updates Needed

• map skill: Add knowledge/inventory/specs/ and knowledge/inventory/audit/ to directory structure. Add “Spec” and “Audit” as key terms.
• essentials skill: Add pitfall — “Never use super(ClassName).__init__() without self; always use super().__init__()”.
• workflows skill: Add spec-driven audit workflow: spec → audit → clean → spec update → re-audit.

Files Modified

• .opencode/commands/audit.md — rewrote from 80-line operational audit to 225-line spec-driven audit command
• knowledge/inventory/specs/platform.md — new: cross-component spec (workflows, contracts, Must Do/Must Not Do)
• knowledge/inventory/specs/kitchenware.md — new: kitchenware spec (bootstrapped from code)
• knowledge/inventory/audit/kitchenware.md — new: kitchenware audit report (8 issues: 4 P4, 3 P5)
• knowledge/inventory/_index.md — added Specs and Audit sections
• knowledge/index.md — added Specs and Audit references under Inventory