wiring-audit

---
name: wiring-audit
description: User-triggered audit that finds wiring drift between a project's UI surfaces and backend capabilities — orphan surfaces (UI calls endpoints/hooks/procedures that no longer exist), unwired capabilities (backend routes/exports that nothing surfaces), shape drift (both exist but contracts mismatch), method drift (URL matches, HTTP verb does not), validation drift (frontend vs backend rules diverged), permission drift (UI exposes what backend forbids or vice versa), stale labels (UI text references renamed backend concepts), and unsurfaced configuration (env vars or flags that gate behavior with no UI or CLI to control them). This skill should be used when the user asks to "audit our wiring," "find UI/backend drift," "find unwired capabilities," "find stale surfaces," "check for contract violations," "find unused endpoints," "find unused hooks," "what mismatches between UI and backend," or any similar request whose deliverable is a prioritized findings report rather than a descriptive snapshot. Generic across UI frameworks but optimized for React applications (hooks, fetch, react-query, SWR, tRPC, server actions, react-router, Next.js). Not for descriptive architectural snapshots (use architectural-analysis), security audits (use security-auditor), or performance audits (use the performance-optimization skills).
license: MIT
---

# 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 the performance-optimization skills)
- 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