Research
Perform deep codebase exploration and produce a context-compressed research documentFrom its SKILL.md
npx -y skills add brian-lai/para-programming-plugin --skill researchAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 7 stars7 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.9 KB, as published. Nobody here has run it
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, Claude will ask for one.
What It Does
-
Clarify focus — if the task description is broad or ambiguous, use AskUserQuestion 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.mdusing the template fromresearch-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
-
Update context — add the research doc path to
context/context.md'sresearch_docsarray. -
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
Claude: [Uses Explore agent to deeply investigate 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:planautomatically 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