Research

Research the codebase to find and explain specific topics. This is a read-only skill - it discovers and documents information but does not modify code.

When to Use

• •Understanding where something is configured (e.g., "Where is Stripe configured?")
• •Learning how a feature works (e.g., "How does authentication work?")
• •Finding implementation details (e.g., "Where are RSS feeds fetched and parsed?")
• •Locating infrastructure definitions (e.g., "Where are the Kubernetes manifests for the API?")
• •Mapping dependencies and data flows

Input

A research question about the codebase. Examples:

• •"Where is Stripe configured?"
• •"How does authentication work?"
• •"Where are RSS feeds fetched and parsed?"
• •"Where do we define Kubernetes manifests for the API service?"

If no question is provided, ask for clarification before proceeding.

Workflow

1. Interpret the Research Topic

Rewrite the question as a clear, concrete research goal:

• •"Where is Stripe configured?" → "Find where and how Stripe API keys are configured and used"
• •"How does authentication work?" → "Identify the main entry points for authentication and session handling"

If the topic is ambiguous, make a reasonable assumption and state it in the report.

2. Explore the Codebase

Use a top-down search strategy:

1. •High-level scan: Identify relevant directories and key modules
2. •Pattern matching: Use Glob and Grep to find likely matches by name, keywords, and patterns
3. •Deep reading: Read the most relevant files in detail

3. Build an Organized Understanding

Identify:

• •Which files, directories, and modules are involved
• •Main functions, types, or components that implement the feature
• •Related configuration (YAML, env, Terraform, Kubernetes, CI, etc.)
• •Important relationships:
  • •Call chains or data flows
  • •Entry points and public APIs
  • •Integration with external services or other modules

4. Report Back Clearly

Produce a structured report including:

• •Topic: The research question answered
• •Locations: List of relevant paths (files/directories)
• •Summary: Short explanation for each location
• •Architecture notes: Key interactions or data flows
• •Follow-ups: Suggestions for next investigations

Output Format

Use the template at references/templates/research-findings.md for comprehensive reports.

For quick answers, use this minimal format:

## Research: [Topic]

### Locations
- `path/to/file` — [what it does]
- `path/to/dir/` — [what it contains]

### Summary
[How these pieces work together]

### Architecture Notes
[Key data flows or interactions]

### Follow-ups
- [Suggestion for next investigation]

Constraints

• •Read-only: Do NOT modify any files
• •No implementation: Do NOT create tests or code changes
• •Focused: Keep the report focused on the requested topic
• •High-value: Prefer insights over exhaustive file listings
• •Clear: Structure findings so a human can quickly follow

Example

Research Question: "How does authentication work?"

Research Goal: Identify the main entry points for authentication
and session handling.

Locations:
- `pkg/auth/handler.go` — HTTP handlers for login/logout/refresh
- `pkg/auth/jwt.go` — JWT token generation and validation
- `pkg/auth/middleware.go` — Authentication middleware for protected routes
- `pkg/auth/session/` — Session storage and management
- `config/auth.yaml` — Authentication configuration (token TTL, providers)

Summary:
Authentication uses JWT tokens with refresh token rotation. The
middleware validates tokens on protected routes and injects user
context. Sessions are stored in Redis with configurable TTL.

Architecture Notes:
- Login flow: handler.go → jwt.go (generate) → session/ (store)
- Request flow: middleware.go → jwt.go (validate) → inject user context
- Supports OAuth providers via config/auth.yaml

Follow-ups:
- Review token refresh logic for security
- Document the OAuth provider setup process
- Add integration tests for session expiration

Begin by interpreting the research question and planning the exploration strategy.