Orienting to repo

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.

1. Purpose — Read README.md (intro + setup section). What does this repo DO?
2. Stack — Read package.json / pyproject.toml / go.mod / Gemfile / Cargo.toml. Language, framework, key deps.
3. Layout — ls the root and 1-2 levels into the main source dir. Note convention: src/, lib/, app/, pkg/, etc.
4. Conventions — Look for CLAUDE.md, AGENTS.md, CONTRIBUTING.md, .editorconfig, linter configs. These are the rules.
5. Tests — Where do they live? What runner? Read one test file to see the style.
6. CI / build — Skim .github/workflows/ or equivalent. What's enforced before merge?
7. 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