context-map

name: context-map description: 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. license: GNU GPL v3 metadata: version: 1.0.0 # x-release-please-version category: workflow audience: general-coding-agent maturity: draft kind: task

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-planner or workflow-contracts.
• The main problem is sharpening the user's ask rather than mapping the codebase; route to reverse-prompt first.

Routing boundary

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 to discover candidate files in a consistent order.
2. Group the results into the context-map structure from 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

• Read the skill once as the target agent and confirm the next action is obvious within a few seconds.
• Confirm the top-level file links every support file directly from ## Reference files.
• Run node skills/skill-authoring/scripts/validate-skill-library.mjs skills/context-map/SKILL.md.
• Smoke test with one request that should trigger the skill and one near-miss that should not:
  • should trigger: Before editing, map the files, tests, and patterns involved in adding retry logic to @extensions/lore/
  • should not trigger: Update the typo in @README.md

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 - the required sections and example structure for a context-map response
• references/search-playbook.md - discovery order for candidate files, dependencies, tests, patterns, and risks
• assets/examples.md - concrete request examples showing when the skill should trigger