| name | repo-exploration |
| description | Use before any implementation to understand the codebase structure, existing patterns, dependency graph, and project conventions. |
Repo Exploration
Use this skill to build a mental model of the codebase before making changes.
Required steps
1. Structural discovery
- List the top-level directory structure.
- Identify the module map: where handlers, services, repositories, models, and tests live.
- Read
ARCHITECTURE.md if it exists. At minimal profile for single-file Small tasks: skip ARCHITECTURE.md unless it is referenced by the task description or appears to contain non-template content (>50 lines of substantive text).
- Read
CONTRIBUTING.md or equivalent docs if they exist.
2. Pattern identification
Read at least one existing file in each layer you will modify and note:
- Naming convention (files, functions, variables, types)
- Error handling pattern (custom error types? wrapped errors? error codes?)
- Logging pattern (structured? which library?)
- Test convention (table-driven? test fixtures? mocks or fakes?)
- Import organization (stdlib first? grouped? aliased?)
3. Dependency graph
Before cross-file changes:
- Trace imports from the file you will change.
- Identify shared types, interfaces, and constants.
- Check for circular dependency risks.
4. Constraint check
- Read
project/project-manifest.md for project-local constraints.
- Read
DECISIONS.md if it exists.
- Do not introduce patterns that contradict recorded decisions.
Output
After discovery, produce a brief summary:
Modules involved: [list]
Existing patterns: [key observations]
Constraints: [project-specific rules that apply]
Files to read before coding: [list]
Use this skill when
- Starting work on an unfamiliar module or when the task touches more than 2 files
- You are unsure about conventions or a previous attempt didn't match the project style
Conformance self-check
Before completing codebase exploration, verify: