# Repo Cartographer

> Build a fast, evidence-based map of an unfamiliar repository before editing. Use when you need to reduce wrong assumptions, identify likely change points, and propose minimal-impact implementation paths.

- Skill: `arjun-bali-ds/repo-cartographer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add arjun-bali-ds/repo-cartographer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arjun-bali-ds/repo-cartographer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: arjun-bali-ds (https://skillmd.com/u/arjun-bali-ds)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/arjun-bali-ds/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

```markdown
## 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/`.