Initial commit
This commit is contained in:
Zhongwei Li
323
skills/pre-dev-research/SKILL.md
Normal file
323
skills/pre-dev-research/SKILL.md
Normal file
@@ -0,0 +1,323 @@
|
||||
---
|
||||
name: pre-dev-research
|
||||
description: |
|
||||
Gate 0 research phase for pre-dev workflow. Dispatches 3 parallel research agents
|
||||
to gather codebase patterns, external best practices, and framework documentation
|
||||
BEFORE creating PRD/TRD. Outputs research.md with file:line references.
|
||||
|
||||
trigger: |
|
||||
- Before any pre-dev workflow (Gate 0)
|
||||
- When planning new features or modifications
|
||||
- Invoked by /ring-pm-team:pre-dev-full and /ring-pm-team:pre-dev-feature
|
||||
|
||||
skip_when: |
|
||||
- Trivial changes that don't need planning
|
||||
- Research already completed (research.md exists and is recent)
|
||||
|
||||
sequence:
|
||||
before: [pre-dev-prd-creation, pre-dev-feature-map]
|
||||
|
||||
related:
|
||||
complementary: [pre-dev-prd-creation, pre-dev-trd-creation]
|
||||
|
||||
research_modes:
|
||||
greenfield:
|
||||
description: "New feature with no existing patterns to follow"
|
||||
primary_agents: [best-practices-researcher, framework-docs-researcher]
|
||||
secondary_agents: [repo-research-analyst]
|
||||
focus: "External best practices and framework patterns"
|
||||
|
||||
modification:
|
||||
description: "Changing or extending existing functionality"
|
||||
primary_agents: [repo-research-analyst]
|
||||
secondary_agents: [best-practices-researcher, framework-docs-researcher]
|
||||
focus: "Existing codebase patterns and conventions"
|
||||
|
||||
integration:
|
||||
description: "Connecting systems or adding external dependencies"
|
||||
primary_agents: [framework-docs-researcher, best-practices-researcher, repo-research-analyst]
|
||||
secondary_agents: []
|
||||
focus: "API documentation and integration patterns"
|
||||
---
|
||||
|
||||
# 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 patterns that already exist
|
||||
- Ignoring project conventions
|
||||
- Missing framework constraints
|
||||
- Repeating solved problems
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Determine Research Mode
|
||||
|
||||
**BLOCKING GATE:** Before dispatching agents, determine the research mode.
|
||||
|
||||
Ask the user or infer from context:
|
||||
|
||||
| Mode | When to Use | Example |
|
||||
|------|-------------|---------|
|
||||
| **greenfield** | No existing patterns to follow | "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, I need to understand the context:
|
||||
|
||||
1. **Greenfield** - This is a completely new capability with no existing patterns
|
||||
2. **Modification** - This extends or changes existing functionality
|
||||
3. **Integration** - This connects with external systems/APIs
|
||||
|
||||
Which mode best describes this feature?
|
||||
```
|
||||
|
||||
**Mode affects agent priority:**
|
||||
- Greenfield → Web research is primary (best-practices, framework-docs)
|
||||
- Modification → Codebase research is primary (repo-research)
|
||||
- Integration → All agents equally weighted
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Dispatch Research Agents
|
||||
|
||||
**Run 3 agents in PARALLEL** (single message, 3 Task calls):
|
||||
|
||||
```markdown
|
||||
## Dispatching Research Agents
|
||||
|
||||
Research mode: [greenfield|modification|integration]
|
||||
Feature: [feature description]
|
||||
|
||||
Launching parallel research:
|
||||
1. ring-pm-team:repo-research-analyst
|
||||
2. ring-pm-team:best-practices-researcher
|
||||
3. ring-pm-team:framework-docs-researcher
|
||||
```
|
||||
|
||||
**Agent Prompts:**
|
||||
|
||||
### repo-research-analyst
|
||||
```
|
||||
Research the codebase for patterns relevant to: [feature description]
|
||||
|
||||
Research mode: [mode]
|
||||
- If modification: This is your PRIMARY focus - find all existing patterns
|
||||
- If greenfield: Focus on conventions and project structure
|
||||
- If integration: Look for existing integration patterns
|
||||
|
||||
Search docs/solutions/ knowledge base for prior related solutions.
|
||||
Return findings with exact file:line references.
|
||||
```
|
||||
|
||||
### best-practices-researcher
|
||||
```
|
||||
Research external best practices for: [feature description]
|
||||
|
||||
Research mode: [mode]
|
||||
- If greenfield: This is your PRIMARY focus - go deep on industry standards
|
||||
- If modification: Focus on specific patterns for this feature type
|
||||
- If integration: Emphasize API design and integration patterns
|
||||
|
||||
Use Context7 for framework documentation.
|
||||
Use WebSearch for industry best practices.
|
||||
Return findings with URLs.
|
||||
```
|
||||
|
||||
### framework-docs-researcher
|
||||
```
|
||||
Analyze tech stack and fetch documentation for: [feature description]
|
||||
|
||||
Research mode: [mode]
|
||||
- If greenfield: Focus on framework setup and project structure patterns
|
||||
- If modification: Focus on specific APIs being used/modified
|
||||
- If integration: Focus on SDK/API documentation for external services
|
||||
|
||||
Detect versions from manifest files.
|
||||
Use Context7 as primary documentation source.
|
||||
Return version constraints and official patterns.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Aggregate Research Findings
|
||||
|
||||
After all agents return, create unified research document:
|
||||
|
||||
**File:** `docs/pre-dev/{feature-name}/research.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: [YYYY-MM-DD]
|
||||
feature: [feature name]
|
||||
research_mode: [greenfield|modification|integration]
|
||||
agents_dispatched:
|
||||
- repo-research-analyst
|
||||
- best-practices-researcher
|
||||
- framework-docs-researcher
|
||||
---
|
||||
|
||||
# Research: [Feature Name]
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[2-3 sentences synthesizing key findings across all agents]
|
||||
|
||||
## Research Mode: [Mode]
|
||||
|
||||
[Why this mode was selected and what it means for the research focus]
|
||||
|
||||
---
|
||||
|
||||
## Codebase Research (repo-research-analyst)
|
||||
|
||||
[Paste agent output here]
|
||||
|
||||
---
|
||||
|
||||
## Best Practices Research (best-practices-researcher)
|
||||
|
||||
[Paste agent output here]
|
||||
|
||||
---
|
||||
|
||||
## Framework Documentation (framework-docs-researcher)
|
||||
|
||||
[Paste agent output here]
|
||||
|
||||
---
|
||||
|
||||
## Synthesis & Recommendations
|
||||
|
||||
### Key Patterns to Follow
|
||||
1. [Pattern from codebase] - `file:line`
|
||||
2. [Best practice] - [URL]
|
||||
3. [Framework pattern] - [doc reference]
|
||||
|
||||
### Constraints Identified
|
||||
1. [Version constraint]
|
||||
2. [Convention requirement]
|
||||
3. [Integration limitation]
|
||||
|
||||
### Prior Solutions to Reference
|
||||
1. `docs/solutions/[category]/[file].md` - [relevance]
|
||||
|
||||
### Open Questions for PRD
|
||||
1. [Question that research couldn't answer]
|
||||
2. [Decision that needs stakeholder input]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Gate 0 Validation
|
||||
|
||||
**BLOCKING CHECKLIST** - All must pass before proceeding to Gate 1:
|
||||
|
||||
```
|
||||
Gate 0 Research Validation:
|
||||
□ Research mode determined and documented
|
||||
□ All 3 agents dispatched and returned
|
||||
□ research.md created in docs/pre-dev/{feature}/
|
||||
□ At least one file:line reference (if modification mode)
|
||||
□ At least one external URL (if greenfield mode)
|
||||
□ docs/solutions/ knowledge base searched
|
||||
□ Tech stack versions documented
|
||||
□ Synthesis section completed with recommendations
|
||||
```
|
||||
|
||||
**If validation fails:**
|
||||
- Missing agent output → Re-run that specific agent
|
||||
- No codebase patterns found (modification mode) → Escalate, may need mode change
|
||||
- No external docs found (greenfield mode) → Try different search terms
|
||||
|
||||
---
|
||||
|
||||
## Integration with Pre-Dev Workflow
|
||||
|
||||
### In pre-dev-full (9-gate workflow):
|
||||
```
|
||||
Gate 0: Research Phase (NEW - this skill)
|
||||
Gate 1: PRD Creation (reads research.md)
|
||||
Gate 2: Feature Map
|
||||
Gate 3: TRD Creation (reads research.md)
|
||||
...remaining gates
|
||||
```
|
||||
|
||||
### In pre-dev-feature (4-gate workflow):
|
||||
```
|
||||
Gate 0: Research Phase (NEW - this skill)
|
||||
Gate 1: PRD Creation (reads research.md)
|
||||
Gate 2: TRD Creation
|
||||
Gate 3: Task Breakdown
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Research Document Usage
|
||||
|
||||
**In Gate 1 (PRD Creation):**
|
||||
```markdown
|
||||
Before writing the PRD, load:
|
||||
- docs/pre-dev/{feature}/research.md
|
||||
|
||||
Required in PRD:
|
||||
- Reference existing patterns with file:line notation
|
||||
- Cite knowledge base findings from docs/solutions/
|
||||
- Include external URLs for best practices
|
||||
- Note framework constraints that affect requirements
|
||||
```
|
||||
|
||||
**In Gate 3 (TRD Creation):**
|
||||
```markdown
|
||||
The TRD must reference:
|
||||
- Implementation patterns from research.md
|
||||
- Version constraints from framework analysis
|
||||
- Similar implementations from codebase research
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Research Mode | Primary Agent(s) | Secondary Agent(s) |
|
||||
|---------------|-----------------|-------------------|
|
||||
| greenfield | best-practices, framework-docs | repo-research |
|
||||
| modification | repo-research | best-practices, framework-docs |
|
||||
| integration | all equally weighted | none |
|
||||
|
||||
| Validation Check | Required For |
|
||||
|-----------------|--------------|
|
||||
| file:line reference | modification, integration |
|
||||
| external URL | greenfield, integration |
|
||||
| docs/solutions/ searched | all modes |
|
||||
| version documented | all modes |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
1. **Skipping research for "simple" features**
|
||||
- Even simple features benefit from convention checks
|
||||
- "Simple" often becomes complex during implementation
|
||||
|
||||
2. **Not using research mode appropriately**
|
||||
- Greenfield with heavy codebase research wastes time
|
||||
- Modification without codebase research misses patterns
|
||||
|
||||
3. **Ignoring docs/solutions/ knowledge base**
|
||||
- Prior solutions are gold - always search first
|
||||
- Prevents repeating mistakes
|
||||
|
||||
4. **Vague references without file:line**
|
||||
- "There's a pattern somewhere" is not useful
|
||||
- Exact locations enable quick reference during implementation
|
||||
Reference in New Issue
Block a user