Gap Analysis

Scan the project and identify practice gaps before writing code.

What Is a Gap?

A gap is one of:

1. Missing domain — The project should have it but doesn't (no tests, no error handling)
2. Weak implementation — The domain exists but lacks best practices (database with no indexes, auth with hardcoded secrets)
3. New technology domain — A domain being introduced that the project hasn't used before (WebSockets, file uploads, payments)

When to Run

• Greenfield project: Every domain is a gap — assess all of them.
• Joining an existing codebase or starting a major feature (3+ new files): Scan the existing code for quality gaps.
• Task introduces a new technology domain: That domain is a gap regardless of how well the rest of the project is set up.

When NOT to Run

• Fixing a typo, renaming, or formatting
• Editing a single existing file with a small change
• Reading, explaining, or reviewing code

Workflow

Step 1 — Detect Project State

Read dependency files (package.json, requirements.txt, go.mod, Cargo.toml) and scan the file tree. Note what frameworks, databases, and tools are in use. For a greenfield project, note "no code yet — all domains are gaps."

Step 2 — Assess Each Practice Domain

Work through the domains in the reference file. For each domain, assess whether it is COVERED (follows best practices) or a GAP (missing or weak).

Do not just check whether a file exists. Read the code and assess whether it follows best practices:

Step 3 — Identify New Domains in the Current Task

Consider what you are about to build. Does it introduce any technology domains the project hasn't used before? Common new domains:

• Authentication/JWT
• WebSockets / real-time
• File uploads
• Payments / billing
• Caching (Redis, in-memory)
• Email / notifications
• Queuing / background jobs

Each new domain is a gap, even if existing domains are well covered.

Step 4 — Record the Gap Report

Update .skill-discovery-state.json with your findings:

{
  "done": true,
  "interval": 5,
  "timestamp": 1711361234,
  "writeCount": 0,
  "skillsInstalled": false,
  "summary": "Assessed 8 domains. Gaps: no tests, error handling is generic try/catch, no security headers. New domain: JWT authentication.",
  "gaps": ["testing", "error-handling", "security", "jwt-authentication"]
}

Use date +%s to get the current timestamp.

Set done to true to release the write gate. Set skillsInstalled to false (skill-search will update this if it installs skills).

After Gap Analysis

Run the skill-search skill to find skills that fill the gaps you identified. Pass it your gaps list.

Do Not Override Good Decisions

If the project has an established pattern for a domain AND that pattern follows best practices, mark it COVERED and move on. The goal is to fill gaps and improve weak implementations, not override good decisions already made.