wiring-audit

# Wiring Audit

## Overview

Diff a project's *consumed* surface (UI buttons, components, hooks, fetch calls, tRPC client invocations, GraphQL queries, server actions) against its *produced* capability (route handlers, hook exports, tRPC routers, GraphQL resolvers, exported async functions) and report every mismatch as a prioritized finding with citations on both sides.

The audit's load-bearing claim: every UI consumption should match exactly one backend production, and every production should be consumed somewhere. Orphans, drift, and gaps are the failure modes. The report is the punch list.

## When to use

Trigger this skill when the user asks for:

- A wiring/drift audit ("audit our wiring," "find drift")
- Identification of unused or orphan code on the wire (unused endpoints, unused hooks)
- Verification that backend capabilities are surfaced ("what's not exposed in the UI?")
- Verification that UI surfaces are wired ("is anything in the UI broken or stale?")
- Contract violation detection between FE and BE
- Stale label detection (UI copy that lies about what the backend does)

Do not trigger for:

- Descriptive architectural snapshots (use `architectural-analysis`)
- Security review (use `security-auditor` or `/security-review`)
- Performance audit (use `workflow-performance`)
- Test coverage audit (use `test-review`)

## Workflow

Six phases. The diff (phase 3) is the load-bearing one — the rest are supporting work to feed it accurate inputs.

### 1. Scope

Establish:

- **Target**: full repo, or a frontend-path and backend-path pair in a monorepo, or a single full-stack project (Next.js, Remix, etc.).
- **Stack detection**: identify FE framework (React + which router, which data layer) and BE framework (Express, Fastify, Hono, Next.js routes/route handlers/server actions, tRPC, GraphQL). The signal-set in `references/react-patterns.md` and `references/capability-enumeration.md` adapts based on what's detected.
- **Output root**: `docs/audits/<YYYY-MM-DD>/` — create now if missing.
- **Priors**: if `docs/architecture/<recent-date>/` exists from a previous architectural-analysis run, the UI-surfaces and integrations reports can be passed as priors to skip rediscovery (saves sub-agent time).

### 2. Dispatch enumerators (parallel)

Two sub-agents, dispatched in a single message with two `Agent` tool calls (parallel, one-shot, no `team_name`):

- **Surface enumerator** (`general-purpose`, sonnet) — walks UI, returns the consumed-set per `references/surface-enumeration.md`.
- **Capability enumerator** (`general-purpose`, sonnet) — walks backend, returns the produced-set per `references/capability-enumeration.md`.

Both return YAML registries (see `references/audit-protocol.md` for the contract). Both need sonnet because correlation reasoning across full files matters here — `Explore` excerpt reads aren't sufficient.

### 3. Drift detection (orchestrator)

Read `references/drift-detection.md`. The orchestrator:

1. Builds consumption and production maps keyed by `(kind, identifier)`.
2. Computes set differences (orphans on each side).
3. For matched pairs, runs shape/method/auth/validation comparison.
4. Each mismatch becomes a candidate finding tagged with one of the 8 categories from `references/finding-categories.md`.

### 4. Severity assignment

Apply the rubric in `references/finding-categories.md`:

| Severity | Default applies to | Override when |
|---|---|---|
| **broken** | orphan-surface, method-drift | Surface is dead code (no callers itself) — downgrade to stale |
| **drifted** | shape-drift, validation-drift, permission-drift | Auth-bypass flavor → upgrade to broken |
| **stale** | stale-label | Public-facing user surface → upgrade to drifted |
| **gap** | unwired-capability, unsurfaced-config | Capability is brand-new (recent commit) → annotate "expected, planned" |

### 5. Verify

Every finding's citation must resolve. Use codanna (when `.codanna/` exists) or grep + `Read` to confirm:

- The cited UI line exists and contains the asserted consumption.
- The cited backend line exists and contains (or fails to contain, for orphan claims) the asserted capability.
- For "stale label" findings, confirm the asserted-renamed backend symbol actually exists at the new location.

Discard findings whose citations fail to resolve. Maintain a discard log for the report's verification section.

### 6. Render report (and optional wiring graph)

- Author `docs/audits/<date>/report.md` per `references/report-template.md`.
- Persist raw registries: `docs/audits/<date>/registries/surfaces.yaml` and `capabilities.yaml`. These let future audits diff against them (compare-to-history is a future v2 feature).
- Optionally author `docs/audits/<date>/wiring.mmd` showing surface→capability with broken edges highlighted in red, unwired capabilities in amber.
- If the wiring graph is authored, run `bash scripts/render.sh docs/audits/<date>/` to produce `wiring.svg`.

## Output layout

```
docs/audits/2026-05-10/
├── report.md                          ranked findings, severity-grouped
├── wiring.mmd                         optional supplemental graph
├── wiring.svg                         optional, run scripts/render.sh
└── registries/
    ├── surfaces.yaml                  raw consumed-set
    └── capabilities.yaml              raw produced-set
```

## Strict citation policy

Every finding must carry path:line citations on both sides where applicable:

- **UI side citation** for the consumption (the `fetch` call, `useQuery` invocation, hook import, form submission, etc.).
- **Backend side citation** for the production (the route handler, exported function, tRPC procedure definition).
- For orphan-surface findings, the backend side citation is replaced by a grep-evidence line ("`grep -rn 'route /api/old' server/` returned 0 matches").
- For unwired-capability findings, the UI side is replaced similarly.
- For stale-label findings, both the UI label location *and* the renamed backend symbol's new location are cited.

Fabricated "missing X" claims are the dominant failure mode for audits — sub-agents over-fire on absence. The verification protocol grep-checks every absence claim before the finding is recorded.

## React focus

Generic by design but optimized for React. The signal catalog in `references/react-patterns.md` covers:

- Hook naming conventions and custom hook unwrapping
- React Query / SWR / Apollo / urql data layer signals
- tRPC client patterns (and the type-safety caveat)
- Next.js server actions (capabilities, not routes)
- React Router and Next.js routing (loaders, actions)
- Form action patterns
- Permission-aware rendering vs backend authorization

For non-React targets, the same workflow applies but the FE-side signal catalog is sparser. Tell the user up front if the UI-side detection will be limited.

## Resources

- `references/audit-protocol.md` — workflow phases, registry contracts, sub-agent prompts
- `references/surface-enumeration.md` — UI consumption discovery (generic + React-aware)
- `references/capability-enumeration.md` — backend capability discovery (Node.js HTTP, Next.js, tRPC, GraphQL)
- `references/drift-detection.md` — the diff algorithm in detail
- `references/finding-categories.md` — 8 categories, severity rubric, evidence requirements
- `references/react-patterns.md` — React-specific signal catalog
- `references/report-template.md` — ranked findings report skeleton
- `scripts/render.sh` — render `wiring.mmd` to `wiring.svg` via `mmdc`
- `scripts/verify-findings.sh` — quick path:line existence check over a findings report