Context Gap Analysis

Context Gap Analysis

Systematic methodology for checking what you need, what exists, and finding the simplest path forward.

Core Principle: "What if it's already done? Check before you build."

Why This Matters

90% of Claude Code "hallucinations" happen because the agent doesn't have the context it needs. This skill forces a context check before any implementation, preventing wasted effort and wrong assumptions.

When to Use This Skill

ALWAYS use before:

• Starting any implementation
• Planning any feature
• Proposing any solution

Do NOT skip for:

• "Simple" tasks (often already implemented)
• "Obvious" implementations (often exist in codebase)
• Time pressure (30 seconds now saves hours later)

The Solution Hierarchy

Check these in order - most tasks don't need new work:

For Code Tasks

1. ALREADY DONE - Feature exists, just needs config
2. SCAFFOLDED - Structure exists, needs small completion
3. SIMILAR EXISTS - Related feature can be extended
4. PATTERN EXISTS - Codebase has pattern to follow
5. NEW BUILD - Must create from scratch (rare!)

For GTM/Knowledge Tasks

1. ALREADY DONE - Synthesis doc answers the question
2. CONTEXT EXISTS - 80% of needed info is in existing docs
3. SIMILAR EXISTS - Related battlecard/persona/content to adapt
4. TEMPLATE EXISTS - Framework or template to follow
5. TRUE GAP - Need new research or content (rare!)

Reality check: ~40% of tasks are "already done" - the context already exists somewhere in your system.

The Context Gap Protocol

Step 1: Enumerate What You Need (30 seconds)

Before searching, list your context requirements:

## Context Requirements for: [TASK]

### Must Know (Blocking)
- [ ] Does this feature already exist?
- [ ] What's the current implementation status?
- [ ] What configuration is needed?

### Should Know (Important)
- [ ] What patterns does codebase use for this?
- [ ] What external APIs are involved?

### User Clarification Needed
- [ ] Any preferences not captured in code?
- [ ] Success criteria undefined?

Step 2: Search the Codebase (2-5 minutes)

Use specific search patterns:

# 1. Find files by name pattern
Glob: "**/*{keyword}*.{ts,py,js}"

# 2. Search for key terms
Grep: pattern="{feature}|{related_term}" output_mode=files_with_matches

# 3. Read discovered files
Read: [each discovered file]

Step 3: Classify the Gap (1 minute)

Step 4: Present Findings

Output structured results:

## Context Gap Analysis Complete

**Task:** [Original request]
**Verdict:** [GAP TYPE]

| Component | Status | Location |
|-----------|--------|----------|
| [Feature] | [EXISTS/MISSING] | [path or N/A] |

**Simplest Path Forward:**
[Specific action - NOT "let's plan this"]

Example: Slack Integration

Task: "Spec out the Slack integration"

Search Results:

• Glob: "**/*slack*.ts" → Found: src/clients/slack.ts
• Grep: "slack|webhook" → Found: src/phases/alert.ts, src/index.ts

Reading Files:

• slack.ts: Full client implemented
• alert.ts: Full phase implemented
• index.ts: Wired into pipeline

Gap Classification: CONFIG GAP

Evidence:

• Client: EXISTS (slack.ts:1-45)
• Phase: EXISTS (alert.ts:1-141)
• Wiring: EXISTS (index.ts:195)
• Secret: MISSING (SLACK_WEBHOOK_URL not set)

Simplest Path: wrangler secret put SLACK_WEBHOOK_URL

Outcome: Zero code changes needed. Saved ~2 hours of unnecessary spec work.

GTM Examples

Example 1: "Write a blog post about [topic]"

Task: "Write a blog post about our triage automation capabilities"

Search Results:

• Glob: "**/*content*strategy*" → Found: content_strategy.md
• Glob: "**/*messaging*" → Found: messaging_framework.md, value_propositions.md
• Glob: "**/*pain*point*" → Found: customer_pain_points_synthesis.md

Reading Files:

• content_strategy.md: Content pillars defined, topics mapped
• messaging_framework.md: Key messages by persona
• customer_pain_points_synthesis.md: Validated pain points with evidence

Gap Classification: NO GAP

Evidence:

• Content strategy: EXISTS (pillars, topics, SEO keywords)
• Messaging: EXISTS (value props by persona)
• Pain points: EXISTS (synthesis with customer quotes)

Simplest Path: Read synthesis docs, apply messaging framework to topic.

Time Saved: 2-3 hours of context gathering that would have been redundant.

Example 2: "Research competitor [X]"

Task: "I need competitive positioning against [competitor name]"

Search Results:

• Glob: "**/*battlecard*" → Found: battlecards/ folder with 8 files
• Glob: "**/*competitive*" → Found: competitive_intelligence_synthesis.md

Reading Files:

• battlecard_[competitor].md: Full battlecard exists
• competitive_intelligence_synthesis.md: Cross-competitor patterns

Gap Classification: NO GAP

Evidence:

• Battlecard: EXISTS (strengths, weaknesses, talk tracks)
• Synthesis: EXISTS (competitive landscape overview)

Simplest Path: Read existing battlecard. Check if last_updated is recent; if stale, do targeted refresh.

Time Saved: 1-2 hours of research already done.

Example 3: "Prepare for sales call with [persona]"

Task: "Help me prepare for a call with a VP of Engineering"

Search Results:

• Glob: "**/*persona*" → Found: buyer_personas.md
• Glob: "**/*objection*" → Found: objections_synthesis.md

Reading Files:

• buyer_personas.md: VP Engineering profile exists (priorities, pain points, decision criteria)
• objections_synthesis.md: Common objections with responses

Gap Classification: NO GAP

Evidence:

• Persona: EXISTS (priorities, metrics they care about)
• Objections: EXISTS (responses with evidence)

Simplest Path: Read persona profile + objections doc. Cross-reference with any company-specific research if available.

Time Saved: 30-60 minutes of prep work.

Quality Gates

Before Proposing Any Solution

• Searched codebase for existing implementation?
• Classified the gap type with evidence?
• Checked if config-only solution exists?
• Identified simplest path forward?