ringpre-dev-research

name: "ring: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. license: MIT compatibility: opencode metadata: trigger: | - Before any pre-dev workflow (Gate 0) - When planning new features or modifications - Invoked by /ring:pre-dev-full and /ring:pre-dev-feature skip_when: | - Trivial changes that don't need planning - Research already completed (research.md exists and is recent)

sequence: before: [ring:pre-dev-prd-creation, ring:pre-dev-feature-map]

related: complementary: [ring:pre-dev-prd-creation, ring:pre-dev-trd-creation]

research_modes: greenfield: description: "New feature with no existing patterns to follow" primary_agents: [ring:best-practices-researcher, ring:framework-docs-researcher] focus: "External best practices and framework patterns"

modification: description: "Changing or extending existing functionality" primary_agents: [ring:repo-research-analyst] focus: "Existing codebase patterns and conventions"

integration: description: "Connecting systems or adding external dependencies" primary_agents: [ring:framework-docs-researcher, ring:best-practices-researcher, ring:repo-research-analyst] 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 existing patterns, ignoring conventions, missing framework constraints, repeating solved problems

Step 1: Determine Research Mode

BLOCKING GATE: Before dispatching agents, determine the research mode.

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 4 agents in PARALLEL (single message, 4 Task calls):

Task invocation for product-designer:

Task(
  subagent_type="ring:product-designer",
  model="opus",
  prompt="Analyze user needs for [feature]. Mode: ux-research. Return: problem validation, preliminary personas, competitive analysis, design constraints."
)

Step 2.5: Handle Topology Configuration

If TopologyConfig is provided (from command's topology discovery):

1. Persist in research.md frontmatter:

---
feature: {feature-name}
gate: 0
date: {YYYY-MM-DD}
research_mode: greenfield | modification | integration
agents_dispatched: 4
topology:
  scope: fullstack | backend-only | frontend-only
  structure: single-repo | monorepo | multi-repo
  modules:  # Only if monorepo or multi-repo
    backend:
      path: {path}
      language: golang | typescript
    frontend:
      path: {path}
      framework: nextjs | react | vue
  doc_organization: unified | per-module
  api_pattern: direct | bff | other  # Only if scope=fullstack
---

Document Placement (based on topology.structure):

Multi-repo directory creation:

# Create directories in both repos
mkdir -p "{backend.path}/docs/pre-dev/{feature-name}"
mkdir -p "{frontend.path}/docs/pre-dev/{feature-name}"

Multi-repo sync note: Add this footer to research.md for multi-repo:

---
**Sync Status:** This document is maintained in both repositories.
- Primary: {backend.path}/docs/pre-dev/{feature-name}/research.md
- Mirror: {frontend.path}/docs/pre-dev/{feature-name}/research.md

2. Adjust agent dispatch for multi-module projects:

If topology.structure is monorepo or multi-repo:

• ring:repo-research-analyst: Run ONCE per module path
  • Backend: Search {topology.modules.backend.path} for patterns
  • Frontend: Search {topology.modules.frontend.path} for patterns
• Combine findings in single research.md with module sections:

  ### Codebase Research
  
  #### Backend Module ({path})
  [Agent output for backend]
  
  #### Frontend Module ({path})
  [Agent output for frontend]
  

3. TopologyConfig flows to all subsequent gates:

• Gate 1 (PRD): Reads topology from research.md frontmatter
• Gate 2 (Feature Map): Uses topology for domain mapping
• Gate 7 (Task Breakdown): Tags tasks with target: based on topology

Step 3: Aggregate Research Findings

Output:

• single-repo/monorepo: docs/pre-dev/{feature-name}/research.md
• multi-repo: Both {backend.path}/docs/pre-dev/{feature-name}/research.md AND {frontend.path}/docs/pre-dev/{feature-name}/research.md

Step 4: Gate 0 Validation

BLOCKING CHECKLIST:

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
• No UX research (product-designer) → Re-run product-designer agent

Integration with Pre-Dev Workflow

ring:pre-dev-full (10-gate): Gate 0 Research → Gate 1 PRD (reads research.md) → ... → Gate 3 TRD (reads research.md)

ring:pre-dev-feature (5-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

1. Skipping research for "simple" features - Even simple features benefit from convention checks
2. Wrong research mode - Greenfield with heavy codebase research wastes time; modification without codebase research misses patterns
3. Ignoring docs/solutions/ - Prior solutions are gold; prevents repeating mistakes
4. Vague references without file:line - "There's a pattern somewhere" is not useful; exact locations enable quick reference