User request: $ARGUMENTS

Thoroughness Level

FIRST: Determine level before exploring. Parse from natural language (e.g., "quick", "do a quick search", "thorough exploration", "very thorough") or infer from query complexity.

Level	Behavior	Triggers
quick	No research file, no todos, 1-2 searches, immediate return	"where is", "find the", "locate", single entity lookup
medium	Research file, 3-5 todos, core + immediate deps only	specific bug, single feature, bounded scope
thorough	Full memento, trace deps + primary callers + tests	multi-area feature, "how do X and Y interact"
very-thorough	Unbounded exploration, ALL callers/callees/implementations	"comprehensive", "all", "architecture", "security audit", onboarding

State: **Thoroughness**: [level] — [reason] then proceed.

---

Explore Codebase Skill

Find all files relevant to a specific query so main agent masters that topic without another search.

Loop: Determine thoroughness → Search → Expand todos → Write findings → Repeat (depth varies by level) → Compress output

Research file: /tmp/explore-{topic-kebab-case}-{YYYYMMDD-HHMMSS}.md

Purpose

Main agent has limited context window. You spend tokens now on structured exploration so main agent can go directly to relevant files without filling their context with search noise.

1. You search exhaustively (uses your tokens on exploration)
2. Return overview + complete file list with line ranges
3. Main agent reads only those files → context stays focused
4. Main agent does ALL thinking/analysis/problem-solving

Scope: Only files relevant to the query. NOT a general codebase tour.

Metaphor: Librarian preparing complete reading list. After reading, patron passes any test without returning.

Success test: Main agent can answer ANY question, make decisions, understand edge cases, know constraints—no second search needed. If they'd need to search again, you missed a file.

Phase 1: Initial Scoping

1.0 Determine Thoroughness

State: **Thoroughness**: [level] — [reason]. Quick mode: skip to search, return results immediately.

1.1 Create todo list (skip for quick)

Todos = areas to explore, not search mechanics. Start small, expand as complexity emerges.

- [ ] Core {topic} implementation
- [ ] {topic} dependencies / callers (scale to level)
- [ ] Config, tests (thorough+)
- [ ] (expand as discoveries reveal complexity)
- [ ] Compile output

1.2 Create research file (skip for quick)

Path: /tmp/explore-{topic-kebab-case}-{YYYYMMDD-HHMMSS}.md (use SAME path for ALL updates)

# Research: {topic}
Started: {timestamp} | Query: {original query}

## Search Log
### {timestamp} - Initial scoping
- Searching for: {keywords}
- Areas to explore: {list}

## Findings
(populated incrementally)

## Files Found
(populated incrementally)

Phase 2: Iterative Exploration

Quick: Skip — 1-2 searches, return. Medium: core + immediate deps. Thorough: deps + callers + tests. Very-thorough: unbounded.

Memento Loop (medium+)

1. Mark todo in_progress → 2. Search → 3. Write findings to research file → 4. Expand todos as complexity emerges (all levels) → 5. Complete → 6. Repeat

Expansion depth: medium focuses on critical gaps; thorough adds imports/deps; very-thorough traces everything. But ALL levels expand when discoveries reveal unexpected complexity.

NEVER proceed without writing findings first.

Todo Expansion Triggers (medium+)

Discovery	Add todos for
Function call	Trace callers
Import	Trace imported module
Interface/type	Find implementations
Service	Config, tests, callers
Route/handler	Middleware, controller, service chain
Error handling	Error types, fallbacks
Config reference	Config files, env vars
Test file	Note test patterns

Research File Update Format

After EACH step append:

### {timestamp} - {what explored}
- Searched: {query/pattern}
- Found: {count} relevant files
- Key files: path/file.ts:lines - {purpose}
- New areas: {list}
- Relationships: {imports, calls}

Todo Evolution Example

Query: "Find files related to authentication"

Initial:

- [ ] Core auth implementation
- [ ] Auth dependencies
- [ ] Auth callers
- [ ] Auth config and tests
- [ ] Compile final output

After exploring core auth (discovered JWT, Redis sessions, OAuth):

- [x] Core auth implementation → AuthService, middleware/auth.ts
- [ ] Auth dependencies
- [ ] Auth callers
- [ ] Auth config and tests
- [ ] JWT token handling
- [ ] Redis session storage
- [ ] OAuth providers
- [ ] Compile final output

Phase 3: Compress Output

3.1 Final research file update

## Exploration Complete
Finished: {timestamp} | Files: {count} | Queries: {count}
## Summary
{Brief structural summary}

3.2 Generate structured output

## OVERVIEW

[Dense paragraph about THE QUERIED TOPIC: how relevant files relate,
entry points, data flow within that area. NOT a general codebase overview.
Factual/structural ONLY—NO diagnosis, recommendations, opinions.]

## FILES TO READ

(Only files relevant to the query)

MUST READ:
- path/file.ts:50-120 - [1-line reason why relevant to query]

SHOULD READ:
- path/related.ts:10-80 - [1-line reason]

REFERENCE:
- path/types.ts - [1-line reason]

3.3 Mark all todos complete

Overview Guidelines

Overview describes the queried topic area only, not the whole codebase.

GOOD content (structural knowledge about the topic):

• File organization: "Auth in src/auth/, middleware in src/middleware/auth.ts"
• Relationships: "login handler → validateCredentials() → TokenService"
• Entry points: "Routes in routes/api.ts, handlers in handlers/"
• Data flow: "Request → middleware → handler → service → repository → DB"
• Patterns: "Repository pattern, constructor DI"
• Scope: "12 files touch auth; 5 core, 7 peripheral"
• Key facts: "Tokens 15min expiry, refresh in Redis 7d TTL"
• Dependencies: "Auth needs Redis (sessions) + Postgres (users)"
• Error handling: "401 for auth failures, 403 for invalid tokens"

BAD content (prescriptive—convert to descriptive):

• Diagnosis: "Bug is in validateCredentials() because..."
• Recommendations: "Refactor to use..."
• Opinions: "Poorly structured..."
• Solutions: "Fix by adding null check..."

Overview = dense map of the topic area, not diagnosis or codebase tour.

What You Do NOT Output

• NO diagnosis (describe area, don't identify bugs)
• NO recommendations (don't suggest fixes/patterns)
• NO opinions (don't comment on quality)
• NO solutions (main agent's job)

Search Strategy

1. Extract keywords from query
2. Search broadly: Glob (**/auth/**, **/*payment*), Grep (functions, classes, errors), common locations (src/, lib/, services/, api/)
3. Follow graph exhaustively (ADD TODOS FOR EACH):
   • Imports/exports, ALL callers, ALL callees, implementations, usages
4. Supporting files (DON'T SKIP):
   • Tests (*.test.ts, *.spec.ts, __tests__/) — expected behavior
   • Config (.env, config/, env vars) — runtime behavior
   • Types (types/, *.d.ts, interfaces) — contracts
   • Error handling (catch blocks, error types, fallbacks)
   • Utilities (shared helpers)
5. Non-obvious:
   • Middleware/interceptors, event handlers, background jobs, migrations, env-specific code
6. Verify: Skim files, note specific line ranges (not entire files)

Priority Criteria

Priority	Criteria
MUST READ	Entry points, core business logic, primary implementation, critical dependencies
SHOULD READ	Callers/callees, error handling, related modules, tests, config
REFERENCE	Types, utilities, boilerplate, tangential code

Completeness > brevity.

Key Principles

Principle	Rule
Memento style	Write findings BEFORE next search (research file = external memory)
Todo-driven	Every discovery needing follow-up → todo (no mental notes)
Exhaustive	Keep expanding until truly done (don't stop early)
Incremental	Update research file after EACH step (not at end)
Compress last	Output only after exploration complete

Never Do

• Proceed without writing findings to research file
• Keep discoveries as mental notes instead of todos
• Skip todo list
• Generate output before exploration complete
• Forget to expand todos on new leads

Final Checklist

• All todos completed (no pending items)
• Research file complete (incremental findings)
• Completeness (master topic from these files alone?)
• Coverage (configs, utilities, error handlers, tests?)
• Overview dense + structural (no opinions)
• File list has precise line ranges, prioritized, 1-line reasons

Key question: After MUST READ + SHOULD READ, will main agent know everything needed?

Example 1: Payment Timeout Bug

Query: "Find files related to the payment timeout bug"

## OVERVIEW

Payment: 3 layers. `PaymentController` (routes/payments.ts:20-80) HTTP, `PaymentService` (services/payment.ts) logic, `PaymentClient` (clients/stripe.ts) external calls. Timeout 30s default in config/payments.ts. Retry logic services/payment.ts:150-200 catches timeouts, retries 3x. Tests: happy path covered, timeout scenarios only tests/payment.test.ts:200-280.

## FILES TO READ

MUST READ:
- src/services/payment.ts:89-200 - Core processing, timeout/retry logic
- src/clients/stripe.ts:50-95 - External API calls where timeouts occur

SHOULD READ:
- src/config/payments.ts:1-30 - Timeout configuration
- tests/payments/payment.test.ts:200-280 - Timeout test cases

REFERENCE:
- src/routes/payments.ts:20-80 - HTTP layer
- src/types/payment.ts - Type definitions

Bad: "Timeout bug caused by retry logic not respecting total budget. Recommend circuit breaker." — NO. Describe structurally, don't diagnose.

Example 2: Authentication

Query: "Find files related to authentication"

## OVERVIEW

JWT (RS256) in httpOnly cookies. 15min expiry, refresh tokens Redis 7d TTL. Flow: POST /login (routes/auth.ts:15-40) → AuthController.login() → AuthService.authenticate() → UserRepository.findByEmail(). Bcrypt cost 12. Middleware middleware/auth.ts validates JWT, attaches user. Refresh: AuthService.refreshToken() issues new token if refresh valid. Logout: clears cookie, blacklists token in Redis (checked every request). Rate limit: 5/15min/IP. Failed logins → audit_logs. OAuth (Google, GitHub) in services/oauth.ts.

## FILES TO READ

MUST READ:
- src/services/auth.ts:1-150 - Core auth (authenticate, refresh, logout, tokens)
- src/middleware/auth.ts:15-85 - JWT validation, user context, blacklist check
- src/services/tokenBlacklist.ts:1-60 - Redis token invalidation

SHOULD READ:
- src/routes/auth.ts:15-100 - Routes, validation, rate limiting
- src/repositories/user.ts:30-80 - User lookup, password verify
- src/services/oauth.ts:1-120 - OAuth providers
- src/utils/crypto.ts:10-45 - Hashing, signing utilities
- tests/auth/auth.test.ts:1-250 - Expected behaviors
- tests/auth/auth.integration.ts:1-150 - Redis/DB integration

REFERENCE:
- src/types/auth.ts - Types/interfaces
- src/config/auth.ts - JWT secret, expiry, bcrypt rounds, rate limits
- src/middleware/rateLimit.ts:20-50 - Rate limiting impl
- prisma/schema.prisma:45-70 - User model, audit_logs

Comprehensive coverage — after reading, understand auth completely.

Example 3: ORM Usage

Query: "Find all files that use the ORM"

## OVERVIEW

Prisma ORM. Schema prisma/schema.prisma: 8 models (User, Order, Product, Category, Review, Cart, CartItem, Address). Client singleton src/db/client.ts, imported everywhere. Repository pattern: src/repositories/{model}.repository.ts. Services use repositories, never Prisma directly. 12 migrations in prisma/migrations/. Raw queries: repositories/report.repository.ts:50-80 (analytics), repositories/search.repository.ts:30-60 (full-text search).

## FILES TO READ

MUST READ:
- prisma/schema.prisma - Model definitions
- src/db/client.ts:1-30 - Prisma singleton
- src/repositories/user.repository.ts:1-120 - Repository pattern example

SHOULD READ:
- src/repositories/order.repository.ts:1-150 - Complex relations
- src/repositories/report.repository.ts:50-80 - Raw SQL
- src/services/user.service.ts:30-100 - Service→repository usage

REFERENCE:
- prisma/migrations/ - 12 migration files
- src/types/db.ts - Generated types