---

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