# Context Map

> Use when the user explicitly wants a pre-edit scoping pass — mapping candidate files, tests, and reference patterns before implementation. Not for general multi-file tasks unless the user asks "what files are involved" or requests a context map.

- Skill: `matt-riley/context-map` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add matt-riley/context-map`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matt-riley/context-map/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: GNU GPL v3
- Author: matt-riley (https://skillmd.com/u/matt-riley)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/matt-riley/context-map

---


# Context map

Use this skill when the next step is figuring out what to read or touch before changing code.

## Use this skill when

- A task may touch multiple files, packages, or layers and the likely blast radius is not obvious yet.
- You need to identify candidate files, nearby tests, and reference patterns before editing.
- A user or reviewer asks for a context map before implementation.
- You want to scope a feature, refactor, or bugfix enough to hand off to planning or implementation cleanly.

## Do not use this skill when

- The exact files are already named and the scope is narrow enough to execute directly.
- The user wants a phased implementation plan with tasks, dependencies, rollout notes, or handoff artifacts; route to [`implementation-review`](../implementation-review/SKILL.md) or [`workflow-contracts`](../workflow-contracts/SKILL.md).
- The main problem is sharpening the user's ask rather than mapping the codebase; route to `reverse-prompt` first.

## Routing boundary

| Situation | Use this skill? | Route instead |
| --- | --- | --- |
| Multi-file task, but likely files/tests/patterns are still unclear | Yes | - |
| User asks "what files do you need to see first?" while the brief is still under-specified | No | `reverse-prompt` |
| The code surface is known and the user wants a full execution plan | No | [`implementation-review`](../implementation-review/SKILL.md) |
| A narrow single-file edit is already well scoped | No | execute directly |

## Inputs to gather

**Required before mapping**

- The task or question you are trying to scope.
- Any file, symbol, directory, or package hints already present in the request.
- Whether the next phase is likely to be `answer`, `plan`, or `implement`.

**Helpful if present**

- Entry-point files, commands, or failing tests that anchor the investigation.
- Similar existing features, modules, or prior art the request should follow.

**Only investigate if encountered**

- Build, configuration, or generated files that expand the blast radius.
- Cross-package ownership boundaries that may change who should implement the work.

## First move

1. Find the most likely entry-point files or directories for the task.
2. Trace direct dependencies, usages, or adjacent files from those entry points.
3. Find nearby tests and at least one reference pattern before suggesting edits.

## Workflow

1. Use [`references/search-playbook.md`](references/search-playbook.md) to discover candidate files in a consistent order.
2. Group the results into the context-map structure from [`references/output-shape.md`](references/output-shape.md).
3. Distinguish confirmed files from likely follow-up files instead of flattening everything into one undifferentiated list.
4. Name the nearby tests and reference patterns that should guide any later implementation.
5. Stop once the next action is obvious: read a specific set of files, route to planning, or proceed with a tightly scoped implementation.

## Outputs

- A context map identifying candidate files grouped by role (entry points, dependencies, tests, reference patterns, risks).
- Distinction between confirmed files and likely follow-up files.
- Clear next action: read a specific set of files, route to planning, or proceed with a tightly scoped implementation.

## Guardrails

- Do not start implementing just because you found plausible files; finish the map first.
- Do not invent files, dependencies, or tests that you have not actually found.
- Keep the top-level skill concise; detailed formats and search heuristics belong in support files.
- Prefer the smallest map that makes the next step obvious over exhaustive cataloguing of the whole repo.
- Call out uncertainty explicitly when the map still depends on reading one or two key files.

## Validation

- Confirm the produced context map names real files, tests, and reference patterns.
- Verify that any inter-skill routes in the map resolve to existing Markdown skill files.
- Check that the next action is explicit and consistent with the gathered evidence.

## Examples

- `Before you touch anything, map the files, tests, and reference patterns involved in adding a new Lore memory tool.`
- `Create a context map for this refactor before we plan it: split the shared validation helper across @skills/ and @extensions/.`
- `What files are likely involved in this multi-package TypeScript error, and which tests should I read first?`

## Reference files

- [`references/output-shape.md`](references/output-shape.md) - the required sections and example structure for a context-map response
- [`references/search-playbook.md`](references/search-playbook.md) - discovery order for candidate files, dependencies, tests, patterns, and risks
- [`assets/examples.md`](assets/examples.md) - concrete request examples showing when the skill should trigger

