| name | para-research |
| description | Perform deep codebase exploration and produce a context-compressed research document. Triggers on: "research this codebase", "explore the code", "para research", "investigate before planning", "deep dive into", "analyze the codebase".
|
Skill: para-research
Perform deep codebase exploration and produce a context-compressed research document. This document becomes the primary input for para-plan.
Usage
para-research [task-description]
para-research --scope=frontend # Focus research on a specific area
para-research --specs # Emphasize API contract analysis
If no task description is provided, ask for one.
What It Does
-
Clarify focus -- if the task description is broad or ambiguous, ask the user to clarify scope, depth, and any specific concerns before proceeding. Skip if the task is narrow and well-defined.
-
Deep codebase exploration -- perform thorough investigation across the relevant area:
- File structure and organization across the relevant area
- Key interfaces and contracts (OpenAPI specs, TypeScript interfaces, Protobuf, shared types)
- Test patterns, test coverage, and test framework conventions
- Dependency map for affected components (what depends on what)
- Error handling and graceful degradation patterns
- Logging and observability patterns
-
API contract analysis -- if the project has OpenAPI/Swagger specs, interface files, or shared type definitions:
- Parse specs and cross-reference with actual implementation
- Flag any inconsistencies between spec and implementation
- Document the canonical source of truth for each contract
-
Pattern recognition -- identify conventions, idioms, and anti-patterns that should inform planning:
- How errors are handled and propagated
- How dependencies are injected or wired
- How config is managed (env vars, config files, feature flags)
- Naming conventions, file organization patterns
-
Produce research document -- write findings to context/data/YYYY-MM-DD-task-name-research.md using research-template.md (co-located in this skill directory). The document should be:
- High-signal, low-noise -- include what matters for planning, not exhaustive file listings
- Structured for context compression -- a planner reading only this document should have sufficient context to create a detailed plan
- Honest about gaps -- explicitly call out what's undocumented, inconsistent, or surprising
-
Update context -- add the research doc path to context/context.md's research_docs array.
-
Suggest next step -- recommend running para-plan, noting the research doc is available as input.
Options
--scope=<area>
Focus research on a specific area of the codebase (e.g., frontend, api, auth, database). Without this flag, research covers the entire codebase relevant to the task description.
--specs
Emphasize API contract analysis. Spend more effort on finding, parsing, and cross-referencing OpenAPI specs, interface definitions, and shared types. Useful when the task involves integration work or API changes.
Research Quality Criteria
The research document should pass this test: Could a Staff+ engineer read this document and create a detailed implementation plan without additional codebase exploration?
If the answer is no, the research is not deep enough. Specifically:
- Every component mentioned should include its key files, public API, and dependencies
- Every interface boundary should have its contract documented
- Patterns should be described with concrete examples (file paths, function names), not vague descriptions
- Gaps and inconsistencies should be specific and actionable
Context Update
After producing the research document, update context/context.md:
{
"research_docs": ["context/data/YYYY-MM-DD-task-name-research.md"],
"last_updated": "{ISO timestamp}"
}
If research_docs doesn't exist in the metadata, add it.
Example
User: para-research rewrite-auth-middleware
Agent: [Deeply investigates auth-related code]
[Discovers existing middleware, session handling, token storage, OAuth flow]
[Cross-references OpenAPI spec with actual endpoints]
[Finds inconsistency: spec says JWT, implementation uses opaque tokens]
Creates: context/data/2025-12-18-rewrite-auth-middleware-research.md
Key findings:
- Auth middleware in src/middleware/auth.ts (450 lines, no tests)
- Session tokens stored in Redis with 24h TTL
- OpenAPI spec and implementation disagree on token format
- No graceful degradation when Redis is unavailable
Suggest running para-plan to create an implementation plan using this research.
Notes
- Research is optional but strongly recommended for non-trivial tasks
- The research doc lives in
context/data/ alongside specs and other input files
para-plan automatically checks for research docs and uses them as primary input- Research docs should be treated as snapshots -- they may become stale as the codebase changes
