# research-codebase (Unified Skill)

## Core Instructions (SKILL.md)

# Research Codebase

Document and explain the codebase as it exists today.

## Core Rule

You are a documentarian, not an evaluator.

## Procedure

1. Understand the research question and clarify the focus if needed.
2. Decompose the question into searchable components.
3. Use `references/search-patterns.md` for search strategy and preferred commands.
4. Read the identified files completely.
5. Generate the report using `references/report-template.md`.

## Rules

- Describe what exists, where it exists, and how it works.
- Provide file references for claims.
- Show relationships between components.
- Do not recommend improvements or refactors.


---

## Reference: report-template.md

```markdown
# Research: [Topic]

Date: [ISO date]
Question: [Original research question]

## Summary

[2-3 paragraph high-level overview]

## Architecture Overview

[Describe the overall architecture]

## Key Components

### Component 1: [Name]

Location: `path/to/file.ext:123`
Purpose: [What it does]
Used by: [What depends on this]
Depends on: [What this depends on]

How it works:
[Step-by-step explanation]

Key methods or functions:
- `functionName()` (line 123): [What it does]

## Data Flow

1. [Step 1]
2. [Step 2]
3. [Step 3]

File references:
- Step 1: `path/to/file.ext:123`
- Step 2: `path/to/file.ext:456`

## Patterns and Conventions

- [Pattern]: [Purpose and evidence]

## Configuration

- Env vars: [If relevant]
- Config files: [If relevant]

## Error Handling

- Error types: [If relevant]
- Error handlers: [If relevant]

## Testing

- Test files: [If relevant]
- Coverage or patterns: [If determinable]

## Dependencies

- External libraries: [If relevant]
- Internal dependencies: [If relevant]

## Entry Points

1. `path/to/file.ext:123` - [Why it matters]

## Related Documentation

- [Doc path or README section]

## Open Questions

- [ ] [Anything still unclear]
```


---

## Reference: search-patterns.md

## Research Search Patterns

Use fast search tools first.

```bash
# Find auth-related files
rg --files | rg "auth"

# Search for authentication patterns
rg -n "authenticate" .
rg -n "login" .

# Look for middleware or hooks
rg -n "middleware" .
rg -n "useAuth" .

# Find configuration
rg -n "auth" config .env.example
```

Research questions usually break down into:
- Where the logic lives
- What entry points exist
- How state is managed
- Where validation happens
- How errors are handled
- What the end-to-end flow looks like


---