para-research

name	para-research
description	Perform deep codebase exploration and produce a context-compressed research document for planning. Use before the para-plan skill for non-trivial tasks to gather contracts, patterns, and interface boundaries.
model	opus
effort	high

Perform deep codebase exploration and produce a context-compressed research document. This document becomes the primary input for the para-plan skill.

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

1. Clarify focus — if the task description is broad or ambiguous, ask 1-4 clarifying questions to clarify scope, depth, and any specific concerns before proceeding. Skip if the task is narrow and well-defined.

2. 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

3. 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

4. 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

5. Produce research document — write findings to context/data/YYYY-MM-DD-task-name-research.md using the template from assets/research-template.md. 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

6. Update context — add the research doc path to context/context.md's research_docs array.

7. Suggest next step — recommend using the para-plan skill, 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: Use the `para-research` skill to 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 using the `para-plan` skill 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
• The para-plan skill 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