Plan Stub Checker

---
name: plan-stub-checker
description: >
  Plan-only sweep for stubs, dead buttons, fake components, unwired handlers,
  and dead links, then a wiring plan. Use when "find dead buttons", "stub
  checker", "fake components", "unwired handlers", or "dead links".
license: MIT
effort: high
---

# Stub, Dead-Link & Fake-Component Checker + Wiring Plan

**Degree of freedom: MIXED** — wiring plan is judgment; detection
passes and MCP/live probes run exactly. Stay **plan-only**. No wiring until approved.

**Role:** Senior full-stack engineer + reliability auditor.

**Task:** Exhaustively find every **stub, dead button, fake/placeholder component, and unwired
handler** across the repo. Trace whether each *should* connect to a real backend / data pipeline /
Supabase / Sentry path. Produce a burndown + wiring plan. **Audit & plan only — do not implement.**

## This skill vs neighbors

| Skill | Does |
|-------|------|
| **plan-stub-checker** (this) | Plan only — inventory, burndown, wiring roadmap |
| `debug-fe-be-integration` | Diagnose and fix FE-BE mismatches |
| `audit-fe-api` | Audit API calls vs backend contracts |
| `test-qa` | Live QA — may find dead buttons during crawl |
| `debug-sentry-monitor` | Triage production Sentry errors |
| `workflow-fix-and-ship` | Fix → verify → PR after you approve |

**Chain:** `plan-stub-checker` → approval → `plan-test-coverage` → … see `docs/PLAN-LOOPS.md`  
**Execute:** `debug-fe-be-integration` / `workflow-fix-and-ship` → `test-playwright`

## How to reason (every plan item)

1. **Propose** — wiring, target, contract, or instrumentation gap
2. **Risk** — silent failure, dead control, or a fabricated target
3. **Keep-working** — already-wired controls and live data paths
4. **Phase** — silent-failure P0 → mock-to-live → orphan → instrumentation (do not execute)

## Worked example

> **Propose:** wire Settings → Export to the existing `POST /api/export` action; add loading/error/empty.
> **Risk:** `onClick={() => {}}` — user thinks export ran; no request, no error.
> **Keep-working:** Settings → Save profile already hits the server action.
> **Phase:** Phase 1 — silent-failure P0.
> **Cite:** `app/settings/page.tsx:84`. Missing action → `[NEEDS REAL TARGET]`.

---

## ⛔ Preservation Contract

Read `references/preservation-contract.md` before Phase 1.

**Acknowledge in output #1** — restate what you will NOT do:

- No removal of features/routes/screens/handlers/props
- No fabricated endpoints, tables, env keys, or DSNs
- Every claim cites file path + line
- Preserve I/O boundaries unless wiring is proposed + approved
- No silent breaking changes
- **Plan, don't build**

---

## References

| File | Contents |
|------|----------|
| `references/detection-taxonomy.md` | Types, grep patterns, integration checks |
| `references/detection-methodology.md` | Six-pass methodology + linkage tracing |
| `references/output-templates.md` | Burndown, inventory, phased plan templates |

---

## Phase flow

```
1. Auto-detect stack (routes, data layer, integrations)
2. Entry-point + static analysis sweep
3. Handler-binding + data-flow trace
4. False-positive filter (dynamic invocation pass)
5. Integration linkage (API, Supabase, Sentry, pipeline)
6. Burndown + phased wiring plan
7. Research + guardrails (current year)
```

---

## Phase 1 — Auto-detect stack  [HIGH freedom]

Read `package.json` and config:

| Signal | Layer |
|--------|-------|
| `@supabase/supabase-js` | Supabase — find `createClient`, `supabase/migrations` |
| `@sentry/*` | Sentry — find init, instrumentation config |
| `react-query` / `@tanstack/react-query` | Data fetching |
| `next/server` actions | Server actions |
| `trpc` / `graphql` | API style |

Record: route manifest paths, API client location, env example file.

---

## Phase 2–4 — Detection passes  [LOW freedom — run exactly]

Execute all passes in `references/detection-methodology.md`:

1. Entry-point trace (reachable vs orphan candidates)
2. Static analysis (unused exports, dead branches)
3. Handler-binding (every interactive control → real effect?)
4. Data-flow (display components → live source?)
5. **Dynamic-invocation filter** — uncertain → `Review required`
6. Config/env trace (integrations actually initialized?)

Taxonomy: `references/detection-taxonomy.md`

Keep **Confirmed** vs **Review required** separate.

Optional live click pass: `protocol-browser-anti-stall` + your own named session (`-s=…`) before playwright-cli.

Delegate a detection pass to a subagent only when it is sizeable, independent of the others, and its raw output (grep dumps, route manifests) has no place in the plan; brief it with the exact commands and the columns to return. It edits nothing, like this pass. Long sweeps are expected — context compaction exists, so finish the inventory rather than wrapping up early.

---

## Phase 5 — Backend / pipeline / integration linkage  [HIGH freedom]

For every stub that *should* be live, map:

- **API:** endpoint or server action — exists? contract? auth? → `[NEEDS REAL TARGET]` if missing
- **Pipeline:** ingest → transform → store → read — which hop is broken?
- **Supabase:** client role, table/view, **RLS** (missing = silent break or leak), types, realtime
- **Sentry:** instrumented? swallowed catches? context/tags/release/env/source maps/PII
- **Analytics / flags / i18n:** real sink, flag resolution, key resolution

Use MCP when available:

| MCP | Use |
|-----|-----|
| Supabase | `list_tables`, policies, advisors — verify tables/RLS exist |
| Sentry | Production errors on related routes — swallowed failures |
| Firecrawl | Current-year Supabase RLS + Sentry instrumentation patterns |
| Playwright | Click dead-looking controls; observe network/nav |

Never invent table names or endpoints.

---

## Phase 6 — Burndown + wiring plan  [HIGH freedom — plan only]

Burndown columns:

`Surface | Element | Type | Classification | Intended target | Wiring gap | Severity P0–P3 | Effort S/M/L | Risk | File:line`

Group by page/screen. Quantify totals.

**Phased wiring plan:**

1. **Silent-failure P0s** — dead controls, swallowed errors, missing RLS
2. **Mock → live data** — replace fixtures with real queries
3. **Orphan cleanup** — proposals only, dependency checks
4. **Instrumentation gaps** — Sentry, analytics, loading/error/empty states

Per confirmed stub: proposed wiring (target, contract, auth, states) + one-line "what must keep working."

**Industry-standard enhancements** (cite current year via Firecrawl):

- Typed Supabase client + generated types; RLS on every public table; test as non-owner
- Replace empty `catch` with handling + Sentry capture; breadcrumbs/tags/release
- Loading/error/empty UI for every newly-wired data path
- Guardrails: lint empty handlers, CI orphan/mock checks, PR checklist

Each phase independently reviewable + revertible.

## Self-critique before the burndown  [LOW freedom — do not skip]

1. **evidenced-not-assumed** — every stub cites file:line; no invented endpoints
2. **plan-only** — no wiring, no handler edits, no fabricated tables
3. **severity/phase justified** — silent-failure and missing RLS are P0, not polish
4. **right-owner** — empty/error rendering of a wired control → `audit-ui-states`; live QA crawl → `test-qa`
5. **no-false-safety** — `Review required` stays uncertain until the dynamic-invocation pass

---

## Required output (in order)

1. Preservation-contract acknowledgment
2. Detection taxonomy results (counts per type)
3. Per-surface stub/dead/fake inventory (checklist — nothing skipped)
4. Burndown table (classification + intended-target + risk)
5. Backend/Supabase/Sentry/pipeline linkage map
6. Wiring + enhancement plan, phased
7. Guardrails / tooling recommendations
8. Research notes + citations
9. Open questions / `[NEEDS REAL TARGET]` list

Deliver as markdown or canvas for large repos, then end the turn with a standalone recap in chat: the two or three highest-impact stubs and the first phase to approve. The document is the deliverable — write it before the recap. **Do not implement wiring** unless user approves in a follow-up.

---

## Rules

- **Plan only — do not implement.** User approves before wiring.
- **Trace before flagging** (entry-point + dynamic-invocation pass).
- **Never fabricate** endpoints, tables, env, or behavior.
- Missing target/integration/env → say so, don't guess.
- Before proposing any file change: one line on what must keep working.

## Related

- `audit-ui-states` — empty/error/offline rendering (wired controls that still look broken)
- `debug-fe-be-integration` / `audit-fe-api` / `test-qa` / `workflow-fix-and-ship`