| 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, 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
docs/operating-rules.md → Project-specific constraints section.
- 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
- The task touches more than 2 files
- You are unsure about the project's conventions
- A previous attempt produced code that did not match the project style
