| name | orienting-to-repo |
| description | Use when starting substantive work in an unfamiliar repo, before diving into task-specific grep or edits — especially when the task touches business logic, public API, build, or infra, or you don't yet know the repo's purpose, stack, conventions, or layout |
Orienting to a Repo
Overview
Before substantive work in a repo you don't already understand, build a brief mental model. Jumping to task-specific grep is a trap: you find symbol X without learning that symbol X is one of three competing implementations and the project is mid-migration. Five minutes of orientation prevents an hour of wrong-direction work.
Core principle: Understand what the repo IS before you change it.
When to Use
- First substantive change in a repo you haven't worked in this session
- After a
/clear or /compact in a repo
- Task touches business logic, public API, build config, or CI
When NOT to Use
- One-line typo fix
- Renaming a single local variable
- Already oriented in this session (rely on conversation context)
- User explicitly says "skip orientation"
The Orientation Pass
Run these in parallel where possible. Time-box to ~5 minutes, not 30.
- Purpose — Read
README.md (intro + setup section). What does this repo DO?
- Stack — Read
package.json / pyproject.toml / go.mod / Gemfile / Cargo.toml. Language, framework, key deps.
- Layout —
ls the root and 1-2 levels into the main source dir. Note convention: src/, lib/, app/, pkg/, etc.
- Conventions — Look for
CLAUDE.md, AGENTS.md, CONTRIBUTING.md, .editorconfig, linter configs. These are the rules.
- Tests — Where do they live? What runner? Read one test file to see the style.
- CI / build — Skim
.github/workflows/ or equivalent. What's enforced before merge?
- Entry point — Find and read the main entry file (top of
main.py, index.ts, cmd/<name>/main.go).
Capture the Model — Briefly
After the pass, write a short scratch summary (3-5 bullets) in your reply to the user. Cover:
- Purpose (one sentence)
- Stack
- Where the relevant code for the current task lives
- Conventions to follow (linter, test framework, doc style)
- Any "watch out for X" you noticed (active migration, deprecated dir, etc.)
Do NOT create a REPO_MAP.md file or any persistent artifact. The map goes stale instantly and lies to future sessions. Keep the model in conversation context only.
Quick Reference
| Look for | To learn |
|---|
| README.md | Purpose, install, basic usage |
| CONTRIBUTING.md / CLAUDE.md / AGENTS.md | Project-specific rules |
| package metadata file | Language + dependencies |
| .github/workflows or .gitlab-ci.yml | What CI enforces |
| Existing test file | Test framework + style |
git log -20 --oneline | What's active right now |
Common Mistakes
| Mistake | Fix |
|---|
Jumping straight to grep "<task-symbol>" | Run the orientation pass first |
Reading every file under src/ | Read the entry point, then trace from there |
| Skipping CI config | Skipped CI = surprised by failed build on PR |
| Producing a REPO_MAP.md artifact | Don't. Keep the model in chat context. |
| Spending 30+ minutes orienting | You're over-investing. Time-box ~5 min. |
Red Flags — STOP and Orient
- About to grep for a task-specific symbol in a repo you haven't read the README of
- About to edit a file in a stack you haven't confirmed (TS vs JS, Python 2 vs 3, etc.)
- "I'll figure out the conventions as I go" — no, find them now
- "The user wants this fast" — fast and wrong is slower than oriented and right
