Plan Gap Finder

Plan Gap Finder

Announce at start: "I'm using the plan-gap-finder skill to cross-reference the plan against the codebase with parallel agents."

What This Does

Spawns parallel Claude subagents to scan different areas of the codebase and cross-reference each area against the plan file. Each agent reports three categories:

• Planned but missing - plan says it should exist, code does not implement it
• Implemented but not planned - code exists, plan does not mention it
• Partial - partially implemented or mismatched API/signature/behavior

The results are aggregated into one consolidated gap report.

How to Invoke

/plan-gap-finder [path-to-plan.md]

If no path is given, auto-detect the most recently modified plan file.

Steps

Step 1: Find the Plan File

If the user provided a path, use it directly.

Otherwise, auto-detect in this order:

ls -t docs/superpowers/plans/*.md 2>/dev/null | head -1
ls -t docs/plans/*.md 2>/dev/null | head -1
find docs/ -name "*plan*" -o -name "*spec*" -o -name "*design*" 2>/dev/null | head -5

Confirm with the user: "Found plan at <path>. Scanning codebase for gaps."

If no plan found, ask the user to provide the path.

Step 2: Read the Plan

Read the plan file in full. Extract:

• All tasks, components, files, APIs, endpoints, data models, and behaviors mentioned
• Technical decisions and constraints stated in the plan

Keep the full plan content in context -- you will embed it verbatim in each subagent prompt.

Step 3: Discover Codebase Structure

ls -la
find . -maxdepth 3 -type d   -not -path '*/node_modules/*'   -not -path '*/.git/*'   -not -path '*/__pycache__/*'   -not -path '*/.venv/*'   -not -path '*/dist/*'   -not -path '*/build/*'   2>/dev/null | head -60

Partition into scan areas (skip areas that do not exist):

Step 4: Spawn Parallel Gap-Finder Agents

Use the Agent tool to spawn all area agents in a single message (parallel execution).

For each active area, spawn one subagent with this prompt structure:

You are a gap-analysis agent for the [AREA] area of this codebase.

Your task: Cross-reference the plan below against the actual [AREA] code and find gaps.

Full Plan Content: [PASTE FULL PLAN CONTENT HERE]

Your Search Area: Scan all files under [PATHS FOR THIS AREA] Working directory: [ABSOLUTE CWD]

For each item the plan mentions that is relevant to [AREA]:

1. Does the code/file/function/endpoint/model actually exist?
2. If it exists, does it match the plan spec (correct API, behavior, types)?
3. Is it complete, or stubbed/TODO/placeholder?

Return exactly four sections:

PLANNED BUT MISSING List each thing the plan says should exist in [AREA] but does not. Format: - [TYPE] name/path: what the plan says it should be If none: write "None found."

IMPLEMENTED BUT NOT PLANNED List significant code in [AREA] the plan never mentions. Skip boilerplate, imports, logging -- only flag non-trivial things. Format: - [TYPE] name/path: brief description If none: write "None found."

PARTIAL IMPLEMENTATIONS List things that exist but do not fully match the plan. Format: - [TYPE] name/path: plan says X, code does Y If none: write "None found."

CONFIDENCE: HIGH / MEDIUM / LOW -- one sentence reason.

Be specific. Name files, functions, classes, endpoints. Read actual code files before concluding anything is missing.

Spawn all area agents in ONE message so they run in parallel.

Step 5: Aggregate the Results

Once all agents return, merge their reports:

1. Deduplicate - the same gap may appear from multiple agents
2. Rank by severity:
   • CRITICAL - plan explicitly marks as required or it is a core feature
   • HIGH - clearly in scope, zero implementation found
   • MEDIUM - partially implemented or ambiguous
   • LOW - implemented but not in the plan

Step 6: Output the Gap Report

============================================================
  PLAN GAP REPORT
  Plan: <plan-file-path>
  Repo: <cwd>
  Date: <today>
  Areas scanned: <list>
============================================================

SUMMARY
-------
  Planned but missing:   X items
  Not in plan:           Y items
  Partial:               Z items
  Total gaps:            N

------------------------------------------------------------
  PLANNED BUT MISSING  (HIGH PRIORITY)
------------------------------------------------------------
[CRITICAL]
- ...
[HIGH]
- ...
[MEDIUM]
- ...

------------------------------------------------------------
  IMPLEMENTED BUT NOT PLANNED
------------------------------------------------------------
- ...

------------------------------------------------------------
  PARTIAL IMPLEMENTATIONS
------------------------------------------------------------
- ...

------------------------------------------------------------
  AGENT CONFIDENCE
------------------------------------------------------------
  backend:        HIGH/MEDIUM/LOW
  frontend:       HIGH/MEDIUM/LOW
  tests:          HIGH/MEDIUM/LOW
  infrastructure: HIGH/MEDIUM/LOW

------------------------------------------------------------
  RECOMMENDED NEXT STEPS
------------------------------------------------------------
1. ...
2. ...
============================================================

Step 7: Offer Follow-Up Actions

After the report, offer:

• /deep-verify-plan - update the plan with these findings
• "Want me to open GitHub issues for each critical gap?"
• "Want me to create a TDD task list to close these gaps?"

Rules

• Read actual code - agents must read files before declaring something missing. If a path is uncertain, use Glob.
• No hallucination - uncertain = LOW confidence, not an invented gap.
• Parallel always - all area agents launch in one message. Never sequential.
• Adapt to repo - skip areas that do not exist. Do not fabricate.
• Plan is source of truth - implemented-but-not-planned is informational, not necessarily wrong.
• No fixes - this skill finds gaps only. It does not implement anything.