repo-exploration

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:

• 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