Repo Cartographer

Repo Cartographer

Use this skill when the repository is unfamiliar, large, or ambiguous.

Outcomes

• Produce a compact repository map before code edits.
• Identify the minimum set of files likely required for the task.
• Surface ambiguity early with concrete clarification questions.
• Propose 2-3 implementation paths with risk and effort tradeoffs.

Workflow

1. Task framing (no edits yet)

   • Restate the request as a single testable objective.
   • List unknowns that could cause rework.

2. Fast scan (structural map)

   • Run python skills/repo-cartographer/scripts/map_repo.py --max-files 400 --top 25.
   • Inspect entrypoints, test directories, config files, and docs.
   • If key files are missing, ask focused clarifying questions.

3. Dependency + impact sketch

   • For the candidate area, identify likely upstream/downstream effects.
   • Mark each expected touched file as:
     • required
     • probable
     • avoid unless asked

4. Path options

   • Offer 2-3 implementation options:
     • smallest change path
     • balanced path
     • robust path
   • For each: complexity, risk, verification cost.

5. Execution gate

   • Do not edit until scope is explicit.
   • Confirm intended path in one sentence.

Output Template

## Repo Map
- Language(s): ...
- Entrypoints: ...
- Test surface: ...
- High-risk zones: ...

## Task Interpretation
- Objective: ...
- Unknowns: ...

## Candidate Files
- required: ...
- probable: ...
- avoid unless asked: ...

## Implementation Paths
1) Smallest change ...
2) Balanced ...
3) Robust ...

## Clarifications Needed
- Q1 ...
- Q2 ...

Notes

• Keep this phase short and evidence-based.
• Prefer certainty over velocity when ambiguity is high.
• For large monorepos, load only relevant references from references/.