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):

ring:repo-research-analyst

ring:best-practices-researcher

ring:framework-docs-researcher

ring:product-designer

ux-research

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):

docs/pre-dev/{feature-name}/research.md

docs/pre-dev/{feature-name}/research.md

{backend.path}/docs/pre-dev/{feature-name}/research.md

{frontend.path}/docs/pre-dev/{feature-name}/research.md

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

monorepo

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

Standards Loading (MANDATORY)

This skill is a research/analysis skill and does NOT require WebFetch of language-specific standards.

Purpose: This skill gathers research BEFORE technical decisions are made. Standards are loaded in TRD (Gate 3) after research establishes context.

However, research agents dispatched by this skill (e.g.,

ring:framework-docs-researcher

Blocker Criteria - STOP and Report

Cannot Be Overridden

These requirements are NON-NEGOTIABLE:

• MUST dispatch all 4 research agents in parallel
• MUST determine research mode BEFORE dispatching agents
• MUST include product/UX research via

  ring:product-designer

• MUST aggregate findings into research.md with file:line references
• MUST search docs/solutions/ for prior solutions
• MUST document tech stack versions from manifests
• CANNOT skip synthesis section

Severity Calibration

Pressure Resistance

Anti-Rationalization

When This Skill Is Not Needed

• Trivial changes that don't need planning (< 1 hour work)
• research.md already exists and is recent (< 7 days old)
• Bug fixes with known root cause requiring no design research
• Documentation-only updates
• Pure refactoring with no new functionality
• Configuration changes requiring no architectural research