---
name: deep-audit
description: Run a multi-domain audit of the workspace (USD compliance, performance, DRY/reinvention, legacy/shims, robotics-sim best practices, resilience, UX) with parallel read-only reviewers, then execute fixes as a no-shim migration plan. Use for periodic health audits or before large refactors.
---

# Deep audit — multi-domain review → no-shim migration plan → batched execution

Workflow for auditing the whole workspace or a subsystem and converting findings
into an ordered, executable remediation plan.

Reports live in `docs/reviews/`. A closed report is **deleted** once its findings land —
git keeps it, and a stale report reads as an open problem list. A finding that will not be
fixed soon graduates to its own `docs/reviews/open-<name>.md`, which stays.

## Phase A — parallel read-only review

1. **One reviewer per domain, launched in parallel, all read-only.** Every prompt contains:
   "Do NOT run cargo, builds, or tests; do not edit files." Reviewers return RAW structured
   findings (`file:line | severity | dimension | defect | evidence`), max ~30, prioritized,
   plus a 5-line maturity verdict — data for the coordinator, not prose for a human.
2. **Dedup against prior reviews.** Every reviewer first skims `docs/reviews/*.md` (and
   `git log -- docs/reviews/` for closed ones) and
   reports only NEW or still-unfixed issues. Have reviewers explicitly re-verify known lore
   (memory items, fixed-bug patterns) and mark each ✅ fixed / ❌ still open — verified-fixed
   findings are as valuable as new ones.
3. **The audit dimensions** (adjust per run, but these are the standing set):
   - **USD compliance** — follow OpenUSD conventions, not parallel inventions: composition
     arcs, defaultPrim, UsdPhysics/UsdGeom/UsdLux names with their real semantics.
     **Minimize custom `lunco:` schema surface**: before declaring a new `lunco:` attribute,
     check whether a USD-native concept already expresses it (kind, purpose, variants,
     payloads, `doc`, existing applied APIs, physics schemas). Every `lunco:` attr that IS
     authored must be declared in `schema.usda` (the staleness gate
     `python3 scripts/gen_schema.py` enforces generatedSchema sync).
     Name-squatting check: places that adopt Pixar/Omniverse NAMES but diverge semantically.
   - **Modelica/cosim conformance** — flattening, connect semantics, initialization,
     events; master-algorithm honesty (declared ZOH/Jacobi contract vs. actual behavior);
     input-strip coverage at EVERY source seam; solver claims in comments match the code.
   - **Performance** — per-frame allocations, systems without run conditions/change
     detection, O(n²)/full-set rebuilds, per-sample virtual dispatch in bake/solve inner
     loops, main-thread work that belongs on `AsyncComputeTaskPool`, caches whose cap is
     below the resident set (a defeated cache reads as "working" in a profile of an idle
     scene — always check cap vs. resident bound), missing `AssetId` dedup on shared assets,
     unconditional component writes that dirty change detection.
   - **DRY / reinvented wheels** — hand-rolled code where a workspace dep or the openusd
     fork already provides it (REUSE openusd — fix the FORK); duplicate numeric cores for
     the same concept (two spline evaluators, two force laws); dead dependencies; a fix
     applied to one of two parallel code paths (the OTHER path still has the bug — always
     grep for the twin).
   - **Legacy & shims** — dual APIs, back-compat aliases, "temporary" bridges, advertised
     surfaces with no implementation, comments describing architecture that was never built
     (the "cached DAE" lie pattern). The rule is ONE FORM: the migration plan must delete
     the superseded path in the same phase that lands the new one.
   - **Robotics-industry best practices** — fixed-timestep discipline, determinism
     (peer-identical bakes/sums, no hash-order iteration into physics), frame safety
     (grid-absolute vs render frame typed via `lunco_core::coords::{GridPos,RenderPos}` —
     new pose-carrying APIs must use them), unit/precision hygiene (no f32 downcasts of
     grid-absolute values), tire/terramechanics fidelity honestly stated, joint lifecycle
     (attach in avian `Prepare`, born-disabled collision), readiness gating.
   - **Resilience** — wedge states (in-flight flags with an early-return that never clears
     them; every guard must fail visibly at its owning boundary), panics on malformed input (checked
     arithmetic on header-controlled sizes), all-or-nothing loads (one bad asset must skip
     +report, not stall the scene), infinite per-frame retries with no give-up, failures
     that never reach the UI (`warn!` is not surfacing — trigger an Error-severity
     `TelemetryEvent`; the StatusBus observer fans it to the status bar and Diagnostics).
   - **UX for robotics engineers** — inspector derives from schema (never hardcodes),
     disabled controls carry `on_disabled_hover_text` saying what would enable them, no
     literal RGB (DesignTokens), change-driven panels, and the operate-and-observe set:
     TF/frame gizmos, joint-state, CoM/inertia/forces gizmo, telemetry browser → plot.
   - **Mission-modeling capability** — what system-level domains exist and at what fidelity
     (power, thermal, comms/link budget, orbits, timelines-with-resources), measured
     against STK/GMAT/Basilisk-class expectations; rank gaps with the cheapest credible
     path (reuse: anise/hifitime, rhai over existing query substrate, pure asset changes).

## Phase B — the report

One file: `docs/reviews/YYYY-MM-DD-<name>.md`. Findings tabulated per domain with stable
IDs (U1…, P1…, T1…, C1…, A1…, X1…, M1…, W1…, S1…) — the IDs are how fix agents are tasked
later, so keep them stable. End with the **migration plan**: ordered phases, each phase
deleting the superseded form in the same phase (no shim survives a phase boundary), with a
sequencing rationale (correctness before perf; change-granularity before profiling — idle
churn drowns measurements; schema before inspector; substrate types before mechanical
sweeps). Record execution state in the memory file as phases land.

## Phase C — batched execution

Follow `skills/subagent-batches` exactly: disjoint file lots, agents NEVER run cargo,
and the coordinator runs focused checks with `-j 4` after the batches land. Run a
broader suite only when the audit scope requires it; set
`CARGO_PROFILE_TEST_STRIP=debuginfo` when large Bevy test binaries make disk usage
material. Additional rules:

- **Attribute every test failure before fixing.** Preserve the working tree and rerun
  the failing target when needed. Separate failures caused by the current change,
  asset/test drift, and intentional negative fixtures before deciding code-fix versus
  test-update.
- **Substrate first, consumers fanned out.** For a cross-cutting type change, land the core
  types yourself (Lot 0), then launch consumer lots in parallel against the new signatures;
  compile breaks between lots are expected and resolved by the single end check.
- **Cross-file handoffs are the coordinator's job.** Agents report edits they couldn't make
  outside their lot (a caller in another lot's file, a cache-version bump); apply them
  yourself between batches — never let one drop.
- Findings discovered DURING execution go back into the report as an addendum section, not
  into the void.

## Definition of done

Every phase: checks cover the touched owners, failures are attributed and
dispositioned, superseded forms are deleted, and the report is updated. Rerunning
Phase A against a clean tree must not reproduce fixed findings.