majiayu000 Pre-Dev Research Skill (Gate 0)
Purpose: Gather comprehensive research BEFORE writing planning documents, ensuring PRDs and TRDs are grounded in codebase reality and industry best practices.
The Research-First Principle
Traditional: Request → PRD → Discover problems during implementation
Research-First: Request → Research → Informed PRD → Smoother implementation
Research prevents: Reinventing existing patterns, ignoring conventions, missing framework constraints, repeating solved problems
Step 1: Determine Research Mode
BLOCKING GATE: Before dispatching agents, determine the research mode.
| Mode | When to Use | Example |
|---|---|---|
| greenfield | No existing patterns | "Add GraphQL API" (when project has none) |
| modification | Extending existing functionality | "Add pagination to user list API" |
| integration | Connecting external systems | "Integrate Stripe payments" |
If unclear, ask:
Before starting research: Is this (1) Greenfield - new capability, (2) Modification - extends existing, or (3) Integration - connects external systems?
Mode affects agent priority:
- Greenfield → Web research primary (best-practices, framework-docs)
- Modification → Codebase research primary (repo-research)
- Integration → All agents equally weighted
Step 2: Dispatch Research Agents
Run 3 agents in PARALLEL (single message, 3 Task calls):
| Agent | Prompt Focus |
|---|---|
repo-research-analyst |
Codebase patterns for [feature]. Search docs/solutions/ knowledge base. Return file:line references. If modification mode: PRIMARY focus. |
best-practices-researcher |
External best practices for [feature]. Use Context7 + WebSearch. Return URLs. If greenfield mode: PRIMARY focus. |
framework-docs-researcher |
Tech stack docs for [feature]. Detect versions from manifests. Use Context7. Return version constraints. If integration mode: focus on SDK/API docs. |
Step 3: Aggregate Research Findings
Output: docs/pre-dev/{feature-name}/research.md
| Section | Content |
|---|---|
| Metadata | date, feature, research_mode, agents_dispatched |
| Executive Summary | 2-3 sentences synthesizing key findings |
| Research Mode | Why selected, what it means for focus |
| Codebase Research | Agent output (file:line references) |
| Best Practices Research | Agent output (URLs) |
| Framework Documentation | Agent output (version constraints) |
| Synthesis | Key patterns to follow (file:line, URL, doc ref); Constraints identified; Prior solutions from docs/solutions/; Open questions for PRD |
Step 4: Gate 0 Validation
BLOCKING CHECKLIST:
| Check | Required For |
|---|---|
| Research mode documented | All modes |
| All 3 agents returned | All modes |
| research.md created | All modes |
| At least one file:line reference | modification, integration |
| At least one external URL | greenfield, integration |
| docs/solutions/ searched | All modes |
| Tech stack versions documented | All modes |
| Synthesis section complete | All modes |
If validation fails:
- Missing agent output → Re-run that agent
- No codebase patterns (modification) → May need mode change
- No external docs (greenfield) → Try different search terms
Integration with Pre-Dev Workflow
pre-dev-full (9-gate): Gate 0 Research → Gate 1 PRD (reads research.md) → ... → Gate 3 TRD (reads research.md)
pre-dev-feature (4-gate): Gate 0 Research → Gate 1 PRD → Gate 2 TRD → Gate 3 Tasks
Research Document Usage
In Gate 1 (PRD): Reference existing patterns with file:line; cite docs/solutions/; include external URLs; note framework constraints
In Gate 3 (TRD): Reference implementation patterns; use version constraints; cite similar implementations
Anti-Patterns
- Skipping research for "simple" features - Even simple features benefit from convention checks
- Wrong research mode - Greenfield with heavy codebase research wastes time; modification without codebase research misses patterns
- Ignoring docs/solutions/ - Prior solutions are gold; prevents repeating mistakes
- Vague references without file:line - "There's a pattern somewhere" is not useful; exact locations enable quick reference