Research Methodology

This is non-negotiable. No time pressure, no "I already know this," no user request overrides this.

Roles

USER = Decision Maker.  Approves scope, reviews findings, makes final choices.
CLAUDE = Researcher.  Investigates, synthesizes, presents options with evidence.

NEVER present a single option as "the answer."
NEVER assume user wants what you'd recommend. Present trade-offs.
"I recommend X" is fine. "Here's X" without alternatives is not.

Research Depth Calibration

This skill is used by commands at different depth levels. Match depth to context.

The methodology applies at ALL depths. Even light research must triangulate sources and present alternatives. Deep research just does it more thoroughly.

Research Areas

Research areas are selected dynamically from the catalog (references/research-catalog.md), not hardcoded. Each area has a specific scope to prevent agents from overlapping.

Area selection: Load references/research-catalog.md → evaluate trigger and brownfield conditions → select relevant areas → group into waves by dependency.

Core areas (evaluate for every project): STACK, LANDSCAPE, ARCHITECTURE, PITFALLS. Domain-specific areas (include when relevant): SECURITY, PERFORMANCE, ACCESSIBILITY, DATA, INTEGRATION. Custom areas: AI may propose with justification — always requires user confirmation.

For detailed per-area guidance (search strategies, comparison templates, scope boundaries), see references/research-areas.md.

Research Protocol

Phase 1: SCOPE DEFINITION
    ↓ (gate: research question is specific and bounded)
Phase 2: MULTI-SOURCE INVESTIGATION
    ↓ (gate: 3+ independent sources consulted per key claim)
Phase 3: EVIDENCE EVALUATION
    ↓ (gate: findings ranked by evidence quality)
Phase 4: SYNTHESIS & PRESENTATION

Phase 1: Scope Definition

1. Define the research question explicitly. "What are we trying to learn?" in one sentence.
2. Bound the scope. What is in scope? What is explicitly out of scope?
3. Identify the decision. What does the user need to DECIDE after this research?
4. Check existing knowledge. Scan codebase for existing patterns, tech already in use.

Gate: Cannot proceed until the research question is specific enough to be answered. "Research authentication" is too broad. "Compare JWT vs session-based auth for this Express API with these constraints" is specific.

Phase 2: Multi-Source Investigation

Three source categories. Minimum 2 of 3 required for key claims.

For each finding: record the source, the claim, and the confidence level.

Gate: Cannot proceed with fewer than 3 independent data points for key claims. Single-source claims must be flagged as low confidence.

Phase 3: Evidence Evaluation

1. Rank findings by evidence quality (see Evidence Standards below).
2. Identify conflicts. When sources disagree, do NOT resolve silently — present both sides with evidence quality.
3. Separate facts from opinions. FACTS are documented and verifiable. OPINIONS are blog posts, "best practices" without data, experience reports.
4. Check staleness. Documentation version matches project? Blog post date within 18 months? Package still actively maintained?

Gate: Every recommendation must cite at least one strong evidence source. Recommendations with only weak evidence must be flagged.

Phase 4: Synthesis & Presentation

1. Synthesize findings into actionable recommendations.
2. Present 2-3 options for each key decision. Never just one.
3. For each option: pros, cons, when to use, evidence supporting it.
4. Identify unknowns. What remains UNKNOWN after research? Honest gaps.
5. Conflict resolution: When sources disagree, present both with evidence quality rating. User decides.

Evidence Standards

Training data is ALWAYS weak evidence. Your training data is a snapshot of the internet at a point in time. Verify externally before presenting as fact.

Source staleness checks:

• Documentation: version must match project's version
• Blog posts: older than 18 months → flag as potentially outdated
• Codebase patterns: current code is always strong evidence
• Package stats: check last release date, open issues count

Cognitive Biases in Research

Synthesis Protocol

When multiple research agents produce output (phase-research, init), the synthesizer must:

1. Read all outputs completely. Not just summaries or first paragraphs.

2. Identify agreements. Where all agents converge → high confidence.

3. Surface conflicts. Where agents disagree → present both sides with evidence.

4. Cross-validate. If Stack recommends X but Pitfalls warns about X → highlight the tension.

5. Rank recommendations by evidence strength, not by word count or confidence language.

6. Build Impact Analysis. Compare research findings against the original approach (from context inputs: PROJECT.md, ROADMAP.md, REQUIREMENTS.md). For each key aspect, categorize as KEEP (compatible), REPLACE (incompatible — state alternative), ADD (needed but not in original), REMOVE (in original but no longer needed). This gives users immediate visibility into what changed, what stayed, and why — not just what went wrong.

7. Produce SUMMARY.md with THREE clearly separated sections:

   • Findings (tài liệu tham khảo): key findings, evidence, conflicts, unknowns — auto-saved, no user action needed.
   • Impact Analysis: delta giữa original approach và research recommendations. Mỗi aspect được categorize KEEP/REPLACE/ADD/REMOVE với lý do evidence-based. Giúp user thấy ngay toàn cảnh thay đổi.
   • Decisions Requiring Confirmation: mọi quyết định kiến trúc/tech mà research recommend (project structure, framework, ORM, hosting, payment, etc.) — PHẢI được present cho user chọn trước khi áp dụng. Mỗi decision phải có 2-3 options với trade-offs.

   ## Findings (Reference Material)
   [Key findings, evidence, comparisons — informational only]
   
   ## Impact Analysis
   | # | Aspect | Original Approach | Research Recommends | Change | Reason |
   |---|--------|-------------------|---------------------|--------|--------|
   | 1 | [aspect] | [from PROJECT/ROADMAP] | [finding] | KEEP/REPLACE/ADD/REMOVE | [why] |
   
   ## Decisions Requiring Confirmation
   [Each decision that needs user choice before it can be applied to REQUIREMENTS.md or ROADMAP.md]
   
   | # | Decision | Research Recommends | Alternatives | Status |
   |---|----------|-------------------|-------------|--------|
   | 1 | Project structure | Turborepo monorepo | Single app, Polyrepo | Pending user choice |
   | 2 | Database | Supabase PostgreSQL | PlanetScale, Neon | Pending user choice |
   

   The calling command (init, phase-research) is responsible for presenting these decisions to the user. SUMMARY.md only extracts and lists them.

8. Frame output as findings, not instructions. Follow research-boundaries rules for output framing, language choice (descriptive not prescriptive), and header templates. See core-principles/references/research-boundaries.md for full rules and examples.

Gate: SUMMARY.md must address conflicts. If it mentions none, the synthesizer missed something — there are always trade-offs.

Anti-Shortcut System

Red Flags — STOP

These thoughts mean you are about to violate the methodology:

Common Rationalizations

Quick Reference

IRON LAW:
  RESEARCH BEFORE DECISIONS. EVIDENCE BEFORE ASSUMPTIONS.
  Training data is not evidence. Cite sources or flag as assumption.

AREAS (dynamic from catalog):
  Select areas based on trigger + brownfield conditions.
  Core: STACK, LANDSCAPE, ARCHITECTURE, PITFALLS
  Domain: SECURITY, PERFORMANCE, ACCESSIBILITY, DATA, INTEGRATION
  Custom: max 2, requires user confirmation, max 8 total

WAVE ORDER (dynamic from dependencies):
  wave = max(wave[deps]) + 1
  Areas with no deps → Wave 1. Spawn all per wave in one message.

PROTOCOL:
  1. Scope (bound the question)
     → gate: specific research question
  2. Investigate (3+ sources, 2+ categories)
     → gate: 3+ independent data points per key claim
  3. Evaluate (rank evidence, surface conflicts)
     → gate: every recommendation cites strong evidence
  4. Synthesize (options, trade-offs, unknowns)

DEPTH:
  Deep (phase-research, init): dynamic areas from catalog, parallel agents, full output
  Medium (brainstorm): 2 rounds, inline
  Light (plan): 1 area, focused, 1-2 pages

SOURCES (min 2 of 3 categories):
  Web (docs, benchmarks, issues) | Codebase (patterns, deps) | Ecosystem (stats, releases)

NEVER:
  Single option without alternatives | Claims without sources |
  Skip areas at Deep depth | Trust training data alone |
  Resolve conflicts silently | Skip codebase scan

Common Mistakes

Research Orchestration

This section defines the complete orchestration flow for deep research (used by /st:init and /st:phase-research). Commands delegate to this flow instead of implementing their own.

The orchestration accepts parameters from the calling command:

• context_inputs: files to read for research context
  • Examples: PROJECT.md, CONTEXT.md, ROADMAP.md, REQUIREMENTS.md, ARCHITECTURE.md
  • Used to extract: domain, tech decisions, constraints, greenfield/brownfield status
• output_dir: where to save research results
  • Examples: .superteam/research/, .superteam/phases/[name]/research/
• research_context: label for the research session
  • Examples: "init", "phase 3: Authentication", "Q2 Stack Review"
• commit_message: format for the final commit
  • Example: "research: {research_context} — {areas}"

Step 1 — Select research areas

1. Read context_inputs files: extract domain, tech decisions, constraints, greenfield/brownfield status
2. Load research area catalog (references/research-catalog.md)
3. For each catalog area: evaluate trigger AND brownfield conditions:
   • Greenfield: include area if trigger matches
   • Brownfield: check brownfield condition — SKIP, ADJUST focus, or KEEP as-is
4. If custom areas seem needed: propose separately with justification, ask user to confirm (custom areas are never auto-included)

Step 2 — Build research plan and persist

1. Build dependency graph from selected areas' needs fields
2. Group into waves: wave = max(wave[deps]) + 1
3. Save RESEARCH-PLAN.md to output_dir before presenting to user:

# Research Plan

Created: [date]
Context: [research_context]
Status: planning

## Selected Areas

| Area | Focus | Wave | Status |
|------|-------|------|--------|
| STACK | [focus] | 1 | pending |
| ARCHITECTURE | [focus] | 2 | pending |
...

## Wave Structure

Wave 1: [areas] → Wave 2: [areas] → ...

## Decisions
- [area] included because: [reason]
- [area] skipped because: [reason]

4. Present research plan to user:

   RESEARCH PLAN — [research_context]
   
   Wave [N] (parallel, [M] agents):
     ├─ [AREA]: [focus description]
     └─ [AREA]: [focus description]
   ...
   Total: [X] agents, [Y] waves
   Saved: [output_dir]/RESEARCH-PLAN.md
   Adjust areas or proceed?
   

5. If config.research_auto_approve is true: display plan and proceed immediately (EXCEPT: if custom areas proposed, always pause for confirmation)
6. If false (default): wait for user to approve, adjust areas, or skip research
7. On approval: update RESEARCH-PLAN.md status to in-progress

Step 3 — Execute waves

1. For each wave: make ALL Agent() calls in a SINGLE message (foreground parallel with tree view). NEVER use run_in_background: true. All agents MUST run in foreground so the orchestrator can read outputs immediately.
2. Each agent receives: context from context_inputs, relevant prior wave outputs, specific focus area
3. Each agent follows this skill's methodology at Deep depth
4. MANDATORY WAIT GATE per wave: do NOT proceed until ALL agents have completed AND you have READ their output files
5. After each wave completes: update RESEARCH-PLAN.md — set completed areas' status to done

Step 4 — Synthesize

1. After all waves complete, spawn synthesizer agent
2. Synthesizer reads all output files from all waves
3. Compiles key findings, identifies conflicts between recommendations
4. Extract all architectural/tech decisions that research agents recommended — list them in "Decisions Requiring Confirmation" section of SUMMARY.md. These are NOT confirmed until the calling command presents them to the user.
5. Writes SUMMARY.md to output_dir (with both "Findings" and "Decisions Requiring Confirmation" sections)
6. If conflicts with existing project docs found: note them for the calling command to resolve (do NOT auto-update)

Step 5 — Present findings

RESEARCH SUMMARY — [research_context]
Areas researched: [list of areas]

Key findings (reference material — auto-saved):
  1. [finding]
  2. [finding]

Decisions requiring confirmation (NOT yet applied):
  1. [decision] — [recommended option] vs [alternatives]
  2. [decision] — [recommended option] vs [alternatives]

Conflicts found:
  [if any: describe + suggest resolution]

Present findings as reference material. Decisions are listed but NOT confirmed here — the calling command (init step 5.5, phase-research) is responsible for presenting each decision individually for user choice.

Wait for user review, answer follow-up questions if needed.

Step 6 — Save and commit

1. All research files already saved to output_dir during execution
2. Update RESEARCH-PLAN.md status to completed
3. Follow superteam:atomic-commits
4. Commit using commit_message format provided by the calling command

Resuming interrupted research

If RESEARCH-PLAN.md exists with status in-progress:

1. Read the plan: identify which areas are done vs pending
2. Skip completed waves
3. Resume from the first wave with pending areas
4. Continue the normal flow from Step 3

This makes research resilient to session interruptions — the plan on disk is the source of truth.

Context Budget

Rule: Light research (/st:plan) resolves with SKILL.md alone. Deep research (/st:phase-research, /st:init) loads references/research-catalog.md for area selection and references/research-areas.md for execution guidance.

Integration

Used by:

• /st:init — dynamic-wave research (areas selected from catalog, grouped by dependencies)
• /st:phase-research — dynamic research agents from catalog + synthesizer
• /st:brainstorm — 2-round inline research (broad → focused)
• /st:plan — optional focused research when AI recommends it

Skills that pair with research-methodology:

• superteam:project-awareness — provides framework detection for codebase-aware research
• superteam:wave-parallelism — parallel research agents follow wave protocol (dynamic waves from catalog dependencies)
• superteam:verification — research findings verified before feeding into plans
• superteam:handoff-protocol — research state (sources, findings, conflicts) captured on pause

Agents:

• phase-researcher — spawned by phase-research and init. Each instance covers one research area. Follows this skill's methodology.
• research-synthesizer — spawned after all researchers complete. Follows synthesis protocol from this skill.

Quick Reference

IRON LAW:
  RESEARCH BEFORE DECISIONS. EVIDENCE BEFORE ASSUMPTIONS.
  Training data is not evidence. Cite sources or flag as assumption.

AREAS (dynamic from catalog):
  Select areas based on trigger + brownfield conditions.
  Core: STACK, LANDSCAPE, ARCHITECTURE, PITFALLS
  Domain: SECURITY, PERFORMANCE, ACCESSIBILITY, DATA, INTEGRATION
  Custom: max 2, requires user confirmation, max 8 total

WAVE ORDER (dynamic from dependencies):
  wave = max(wave[deps]) + 1
  Areas with no deps → Wave 1. Spawn all per wave in one message.

PROTOCOL:
  1. Scope (bound the question)
     → gate: specific research question
  2. Investigate (3+ sources, 2+ categories)
     → gate: 3+ independent data points per key claim
  3. Evaluate (rank evidence, surface conflicts)
     → gate: every recommendation cites strong evidence
  4. Synthesize (options, trade-offs, unknowns)

DEPTH:
  Deep (phase-research, init): dynamic areas from catalog, parallel agents, full output
  Medium (brainstorm): 2 rounds, inline
  Light (plan): 1 area, focused, 1-2 pages

SOURCES (min 2 of 3 categories):
  Web (docs, benchmarks, issues) | Codebase (patterns, deps) | Ecosystem (stats, releases)

NEVER:
  Single option without alternatives | Claims without sources |
  Skip areas at Deep depth | Trust training data alone |
  Resolve conflicts silently | Skip codebase scan

Common Mistakes

Research Orchestration

This section defines the complete orchestration flow for deep research (used by /st:init and /st:phase-research). Commands delegate to this flow instead of implementing their own.

The orchestration accepts parameters from the calling command:

• context_inputs: files to read for research context
  • Examples: PROJECT.md, CONTEXT.md, ROADMAP.md, REQUIREMENTS.md, ARCHITECTURE.md
  • Used to extract: domain, tech decisions, constraints, greenfield/brownfield status
• output_dir: where to save research results
  • Examples: .superteam/research/, .superteam/phases/[name]/research/
• research_context: label for the research session
  • Examples: "init", "phase 3: Authentication", "Q2 Stack Review"
• commit_message: format for the final commit
  • Example: "research: {research_context} — {areas}"

Step 1 — Select research areas

1. Read context_inputs files: extract domain, tech decisions, constraints, greenfield/brownfield status
2. Load research area catalog (references/research-catalog.md)
3. For each catalog area: evaluate trigger AND brownfield conditions:
   • Greenfield: include area if trigger matches
   • Brownfield: check brownfield condition — SKIP, ADJUST focus, or KEEP as-is
4. If custom areas seem needed: propose separately with justification, ask user to confirm (custom areas are never auto-included)

Step 2 — Build research plan and persist

1. Build dependency graph from selected areas' needs fields
2. Group into waves: wave = max(wave[deps]) + 1
3. Save RESEARCH-PLAN.md to output_dir before presenting to user:

# Research Plan

Created: [date]
Context: [research_context]
Status: planning

## Selected Areas

| Area | Focus | Wave | Status |
|------|-------|------|--------|
| STACK | [focus] | 1 | pending |
| ARCHITECTURE | [focus] | 2 | pending |
...

## Wave Structure

Wave 1: [areas] → Wave 2: [areas] → ...

## Decisions
- [area] included because: [reason]
- [area] skipped because: [reason]

4. Present research plan to user:

   RESEARCH PLAN — [research_context]
   
   Wave [N] (parallel, [M] agents):
     ├─ [AREA]: [focus description]
     └─ [AREA]: [focus description]
   ...
   Total: [X] agents, [Y] waves
   Saved: [output_dir]/RESEARCH-PLAN.md
   Adjust areas or proceed?
   

5. If config.research_auto_approve is true: display plan and proceed immediately (EXCEPT: if custom areas proposed, always pause for confirmation)
6. If false (default): wait for user to approve, adjust areas, or skip research
7. On approval: update RESEARCH-PLAN.md status to in-progress

Step 3 — Execute waves

1. For each wave: make ALL Agent() calls in a SINGLE message (foreground parallel with tree view). NEVER use run_in_background: true. All agents MUST run in foreground so the orchestrator can read outputs immediately.
2. Each agent receives: context from context_inputs, relevant prior wave outputs, specific focus area
3. Each agent follows this skill's methodology at Deep depth
4. MANDATORY WAIT GATE per wave: do NOT proceed until ALL agents have completed AND you have READ their output files
5. After each wave completes: update RESEARCH-PLAN.md — set completed areas' status to done

Step 4 — Synthesize

1. After all waves complete, spawn synthesizer agent
2. Synthesizer reads all output files from all waves
3. Compiles key findings, identifies conflicts between recommendations
4. Extract all architectural/tech decisions that research agents recommended — list them in "Decisions Requiring Confirmation" section of SUMMARY.md. These are NOT confirmed until the calling command presents them to the user.
5. Writes SUMMARY.md to output_dir (with both "Findings" and "Decisions Requiring Confirmation" sections)
6. If conflicts with existing project docs found: note them for the calling command to resolve (do NOT auto-update)

Step 5 — Present findings

RESEARCH SUMMARY — [research_context]
Areas researched: [list of areas]

Key findings (reference material — auto-saved):
  1. [finding]
  2. [finding]

Decisions requiring confirmation (NOT yet applied):
  1. [decision] — [recommended option] vs [alternatives]
  2. [decision] — [recommended option] vs [alternatives]

Conflicts found:
  [if any: describe + suggest resolution]

Present findings as reference material. Decisions are listed but NOT confirmed here — the calling command (init step 5.5, phase-research) is responsible for presenting each decision individually for user choice.

Wait for user review, answer follow-up questions if needed.

Step 6 — Save and commit

1. All research files already saved to output_dir during execution
2. Update RESEARCH-PLAN.md status to completed
3. Follow superteam:atomic-commits
4. Commit using commit_message format provided by the calling command

Resuming interrupted research

If RESEARCH-PLAN.md exists with status in-progress:

1. Read the plan: identify which areas are done vs pending
2. Skip completed waves
3. Resume from the first wave with pending areas
4. Continue the normal flow from Step 3

This makes research resilient to session interruptions — the plan on disk is the source of truth.

Context Budget

Rule: Light research (/st:plan) resolves with SKILL.md alone. Deep research (/st:phase-research, /st:init) loads references/research-catalog.md for area selection and references/research-areas.md for execution guidance.

Integration

Used by:

• /st:init — dynamic-wave research (areas selected from catalog, grouped by dependencies)
• /st:phase-research — dynamic research agents from catalog + synthesizer
• /st:brainstorm — 2-round inline research (broad → focused)
• /st:plan — optional focused research when AI recommends it

Skills that pair with research-methodology:

• superteam:project-awareness — provides framework detection for codebase-aware research
• superteam:wave-parallelism — parallel research agents follow wave protocol (dynamic waves from catalog dependencies)
• superteam:verification — research findings verified before feeding into plans
• superteam:handoff-protocol — research state (sources, findings, conflicts) captured on pause

Agents:

• phase-researcher — spawned by phase-research and init. Each instance covers one research area. Follows this skill's methodology.
• research-synthesizer — spawned after all researchers complete. Follows synthesis protocol from this skill.