---
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:

```text
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:

- [ ] Top-level directory structure was listed
- [ ] At least one existing file per modified layer was read for pattern identification
- [ ] `project/project-manifest.md` and `DECISIONS.md` were checked for constraints
- [ ] A brief discovery summary was produced (modules, patterns, constraints, files to read)
- [ ] No patterns were introduced that contradict recorded decisions