explore

name	explore
description	Codebase exploration — find integration points, existing patterns, and related code

Explore

Command: pasture:explore — Codebase exploration — find integration points, existing patterns, and related code

General-purpose codebase exploration skill. Searches the codebase for integration points, existing patterns, data flow, dependencies, and potential conflicts relevant to a topic or feature.

See ../protocol/CONSTRAINTS.md for coding standards.

[explore-topic-structured]

• Given: a topic or feature
• When: exploring
• Then: follow the depth-scoped checklist and produce structured findings
• Should not: produce an unstructured list of file paths

[explore-depth-quick-scan]

• Given: depth is quick-scan
• When: exploring
• Then: grep for keywords, check obvious entry points
• Should not: read entire modules or trace full dependency graphs

[explore-depth-standard-research]

• Given: depth is standard-research
• When: exploring
• Then: trace data flow, map dependencies, read related modules
• Should not: skip tracing how data flows through the relevant code paths

[explore-depth-deep-dive]

• Given: depth is deep-dive
• When: exploring
• Then: build full dependency graph, perform architectural analysis, identify all touchpoints
• Should not: miss transitive dependencies or indirect consumers

[explore-code-refs]

• Given: code references
• When: documenting
• Then: use file:line citation format
• Should not: reference files without line numbers for specific code

[explore-phase1-recording]

• Given: Phase 1 context
• When: recording findings
• Then: add a structured comment on the REQUEST task via bd comments add
• Should not: only produce output without updating the REQUEST task

When to Use

• Phase 1 (s1_3-explore): Spawned by /pasture:user-request after user confirms research depth. Findings recorded as REQUEST task comment.
• Standalone: Any agent needing to understand codebase structure for a topic. Invoke directly with a topic and depth.

Inputs

Parameter	Required	Description
topic	Yes	The feature or concept to explore (e.g., "session management", "CLI command registration")
depth	Yes	One of: quick-scan, standard-research, deep-dive
request-task-id	Phase 1 only	Beads task ID to record findings as comment

Exploration Checklist

1. Entry Points

Where would this feature plug in?

• CLI commands, subcommands, flag definitions
• API routes, handlers, middleware
• Event handlers, hooks, lifecycle callbacks
• Configuration loaders, init functions

2. Data Flow

What existing data structures, types, or schemas are relevant?

• Type definitions, interfaces, structs
• Database schemas, migration files
• Protobuf/OpenAPI/JSON schemas
• Configuration types

3. Dependencies

What modules/packages would this feature depend on or extend?

• Direct imports and consumers
• Shared utilities, helpers, constants
• External packages and their versions
• Build system integration (Nix flakes, package.json, go.mod)

4. Existing Patterns

How do similar features work in this codebase?

• Naming conventions (files, functions, types, tests)
• DI patterns (constructor injection, functional options, context)
• Error handling conventions (error types, wrapping, logging)
• Test structure (fixtures, mocks, test helpers, BDD style)

5. Conflicts

Are there existing implementations that would need modification or could conflict?

• Overlapping functionality that might be duplicated
• Shared state that could race or deadlock
• Configuration keys or CLI flags that could collide
• Import cycles or circular dependencies

Depth Scoping

Depth	Scope	Tools	Deliverable
quick-scan	Grep for keywords, check obvious entry points, scan file tree	Glob, Grep	1-paragraph summary per checklist item
standard-research	Trace data flow, map dependencies, read related modules, check test patterns	Glob, Grep, Read	Per-section structured findings with file:line citations
deep-dive	Full dependency graph, architectural analysis, identify all touchpoints, trace transitive consumers	Glob, Grep, Read, Bash (build/dep tools)	Complete architectural map with dependency diagram and risk assessment

Output Format

Structured Findings

## Explore Findings: <topic>

**Depth:** <quick-scan|standard-research|deep-dive>
**Date:** <YYYY-MM-DD>

### Entry Points

| File | Line | Type | Description |
|------|------|------|-------------|
| `src/cli/commands.ts` | 42 | CLI subcommand | `register` function adds command to CLI router |
| `src/api/routes.ts` | 118 | HTTP handler | `POST /sessions` endpoint |

### Data Flow

User input → CLI parser (src/cli/parse.ts:30) → Command handler (src/commands/session.ts:15) → Service layer (src/services/session.ts:42) → Repository (src/db/session-repo.ts:28) → Database

**Relevant types:**
- `SessionConfig` at `src/types/session.ts:12` — configuration schema
- `SessionState` at `src/types/session.ts:45` — runtime state enum

### Dependencies

**Direct:**
- `src/services/session.ts` imports `src/db/session-repo.ts`
- `src/commands/session.ts` imports `src/services/session.ts`

**Shared utilities:**
- `src/utils/logger.ts` — structured logging (used by all services)
- `src/utils/config.ts` — configuration loader

**External:**
- `better-sqlite3@11.0.0` — database driver
- `zod@3.23.0` — schema validation

### Existing Patterns

**Naming:** Commands use `<verb>-<noun>.ts` (e.g., `create-session.ts`)
**DI:** Constructor injection via factory functions (see `src/services/index.ts:20`)
**Tests:** Vitest with `describe/it` blocks, fixtures in `tests/fixtures/`
**Errors:** Custom error classes extending `AppError` at `src/errors/base.ts:5`

### Conflicts

- `src/services/auth.ts:88` — existing session cleanup logic may overlap
- `src/types/session.ts:45` — `SessionState` enum may need new values
- No import cycles detected

Phase 1 Integration

When invoked as part of Phase 1 (s1_3-explore), record findings on the REQUEST task:

bd comments add {{request-task-id}} \
  "Explore findings ({{depth}}):
  - Entry points: {{list of files/functions with line numbers}}
  - Related types: {{existing types/schemas with locations}}
  - Dependencies: {{modules this would use}}
  - Patterns: {{how similar features work here}}
  - Conflicts: {{potential issues or 'none'}}"

Standalone Use

When used outside Phase 1, produce the structured findings directly as output. No beads comment is needed unless a task ID is provided.

/pasture:explore
Topic: "Nix flake module system"
Depth: deep-dive

This produces the full architectural map without requiring a REQUEST task context.