---
name: "context-discovery"
description: "Use MCP tools to trace behavior that spans multiple modules or history sources."
license: "MIT"
compatibility: "cline, claude, opencode, amp, codex, gemini, cursor, pi"
hint: "Use before starting work to understand codebase context via available MCP tools"
user-invocable: true
---

# Context Discovery

## When to Use

Use this skill **before and during implementation** when:
- Starting work on an unfamiliar module or feature
- The task involves multiple files or systems
- You need to understand existing patterns before coding
- Previous decisions or discussions may be relevant
- You want to avoid duplicating existing functionality

## What It Does

Leverages available MCP tools to proactively discover context about the codebase, existing patterns, decisions, and related work. Instead of relying solely on grep/read cycles, it uses purpose-built discovery tools.

## Discovery Workflow

### Step 1: File Discovery

Find the relevant files using `fff`:

```
fff auth                        # Find auth-related files
fff "*order*"                   # Find order-related files by pattern
fff config                      # Find config files
```

Scan the results to identify the module structure. `fff` returns frecency-ranked results — the files you access most appear first.

### Step 2: Pattern Discovery via `sem`

Once you know the relevant files, use `sem` to understand the code's history and structure:

```
sem blame path/to/file.ts        # See who changed each line and when
sem diff main..HEAD -- path/     # See what changed in this area
sem summary path/to/             # Get a summary of the module
```

`sem` provides entity-level diffs (function-level, not just file-level), making it easier to understand what actually changed.

### Step 3: Historical Context via `ctx`

Search past agent sessions for relevant context:

```
ctx search "auth implementation patterns"   # Past work on auth
ctx search "this module" path/to/module/    # Past discussions about this area
ctx search "decision" "why did we" path/    # Past decision-making
```

`ctx` indexes agent sessions, so you can find past discussions, decisions, and patterns the agent has already encountered.

### Step 4: Project Knowledge via `qmd`

Query durable project knowledge:

```
qmd query "What architecture decisions exist for X?"
qmd search "authentication patterns"
qmd get ADR-001        # Get a specific ADR
```

`qmd` stores project learnings, ADRs, conventions, and gotchas that persist across sessions.

### Step 5: Code Structure via `codebase-memory-mcp`

For large codebases, use the code graph to understand structure:

```
search_graph("OrderHandler")              # Find the function/class
trace_path("OrderHandler", calls)         # What does it call?
trace_path("OrderHandler", callers)       # What calls it?
get_code_snippet("package.OrderHandler")  # Read the source
get_architecture()                         # Project overview
```

### Step 6: External Context via `context7`

Look up documentation for libraries and frameworks:

```
context7 "express.js middleware API reference"
context7 "react useEffect cleanup pattern"
```

## Decision Tree

```
Where to look depends on what you need:
┌─────────────────────────────┬─────────────────┐
│ Need this                    │ Use this tool    │
├─────────────────────────────┼─────────────────┤
│ Find files by name/pattern  │ fff              │
│ Find what changed recently  │ sem diff         │
│ Find past agent discussions │ ctx search       │
│ Find ADRs / project memory  │ qmd query        │
│ Understand code structure   │ codebase-memory  │
│ Look up external docs       │ context7         │
│ Find related PRs            │ github MCP       │
└─────────────────────────────┴─────────────────┘
```

## When Not to Use Context Discovery

- **Simple tasks**: For well-known code, grep + read is faster
- **Already familiar**: If you know the codebase well, skip steps
- **External APIs**: Use `context7` or web search instead
- **Configuration-only changes**: Straightforward edits don't need deep context

## Integration with Other Skills

- Use after `/blindspots` to investigate surfaced unknowns
- Use before `implementation-logger` to establish baseline understanding
- Results from context discovery feed into implementation decisions
- Document surprising finds in implementation log

## Tips

- **Start broad, narrow fast**: Use `fff` to find candidates, then `sem`/`qmd` for depth
- **Prefer recent context**: `ctx` and `git log` give you recent work, which is most relevant
- **Limit discovery**: 2-5 minutes is usually enough
- **Document what you find**: Add significant discoveries to implementation log or qmd