# CodeMap Workflow Skills

## Start Here: Context Routing

For broad work, choose the narrowest CodeMap context tool before implementing. Use `explore_task` when files are unclear, `search_codebase` for known names, `find_related_files` for related-file questions, and `get_file` for known paths.

## Brainstorming (design before code)

For new features or vague requirements, design first — never write production code before the design is approved.

1. Call `explore_task` to gather real codebase context.
2. Ask clarifying questions one at a time until scope is clear.
3. Propose 2–3 approaches with trade-offs, referencing real files from CodeMap.
4. Write a design doc (`docs/specs/YYYY-MM-DD-<topic>.md`) covering goal, approach, affected files, and open questions.
5. Self-review the spec, then wait for user approval before touching any file.

## Test-Driven Development

For new functionality or bug fixes, follow RED → GREEN → REFACTOR strictly.

- **RED**: `search_codebase("test <feature>")` to find patterns, write a minimal failing test, run with the host agent test runner and confirm it **fails**.
- **GREEN**: Use `symbol` to read the target, implement only the minimum to pass, run with the host agent test runner and confirm it **passes**.
- **REFACTOR**: Clean up, run the host agent test runner again, then call `diff(mode="working")` before declaring done.

No production code before a failing test exists.

## Writing Plans

Use after a design is approved and before implementation begins.

1. Re-ground with CodeMap using the narrowest context tool for the task.
2. Use `codemap://agent-pack/templates/implementation-plan`.
3. Write exact steps, files/modules, interfaces, edge cases, and verification commands.
4. Remove decisions from the implementer; record assumptions explicitly.
5. Wait for approval when the task is high-risk or product-facing.

## Executing Plans

Use when implementing an approved plan.

1. Call `diff(mode="working")` before edits and preserve unrelated user changes.
2. Execute one plan step at a time.
3. If reality contradicts the plan, revise the plan instead of broad improvisation.
4. Run planned verification, inspect diff, then refresh local index.

## Verification Before Completion

Use after every file-changing task.

1. Call `diff(mode="working")`.
2. Run the smallest relevant build/test command.
3. Call `refresh_local_index` after local edits.
4. Decide whether `reimport` and `reimport(wait=true)` are needed for cloud graph/insights or cloud indexing.
5. Report changed behavior, verification results, skipped checks, and residual risk.

## Feature Area Investigation

Use when the task involves a named product area (billing, auth, import history, graph, CLI commands, integrations, etc.).

1. Call `explore_task(query)` — review likely files, entrypoints, and recommended reads.
2. Call `get_file(path=[...])` on the top results to survey outlines without loading full files.
3. Use `symbol` for the most relevant component, service, or controller.
4. If still unclear, call `find_related_files` anchored to the best file found.

## Symbol-Level Debugging

Use when a bug or behavior centers on a specific function, class, component, or method.

1. `search_codebase(symbol_name)` if the file is unknown.
2. `symbol(action="context", symbol_name, file_path)` for the exact body.
3. `symbol` when call flow or impact matters.
4. Read only adjacent files needed to explain or change the behavior.

Do not read an entire large file to inspect one symbol when CodeMap can return symbol context.

## Interpreting CodeMap Output

After any CodeMap tool returns ranked files, symbols, or related files:

1. Read the summary first — decide if it is enough to act before expanding.
2. Prefer high-ranked results before low-ranked ones.
3. Follow `nextSteps`, `resourceUris`, and suggested tool calls before opening raw files.
4. Use ranking signals to filter: exact path/symbol match = strong; fuzzy keyword = weak.
5. Stop expanding context once the edit or answer is grounded enough.

When results look weak or noisy, refine the query, anchor to a known file or symbol, or switch tool — including switching to direct `Read`/grep. Don't loop on MCP calls that aren't converging; two non-converging calls is the signal to drop to raw reads.

## Token-Efficient Code Review

Use when reviewing changes in a CodeMap-indexed repository.

1. Start with `diff(mode="working")` or `diff(mode="refs")`.
2. For changed symbols, use `symbol` instead of full-file reads.
3. Use `symbol` for risky public API or shared behavior changes.
4. Lead findings by severity. Mention test gaps and residual risk.

Review behavior and integration risks — avoid summarizing broad context unless it supports a finding.
