/research

Comprehensive research system for generating detailed investigation prompts, importing findings, and managing research notes.

Quick Start

The research system provides four specialized commands:

Copy/research:ask TOPIC="your research topic"       # Generate research prompt
/research:import TOPIC="title"                  # Import external results
/research:list                                   # View all research notes
/research:view FILE=<filename>                  # Read specific note

Overview

The research system enables:

1. Generate detailed research prompts for ChatGPT, Claude web, Perplexity, or Gemini
2. Import results from external AI tools into your project
3. Browse and reference past research findings
4. Organize findings with structured templates and indexes

Research is essential for:

• Troubleshooting difficult problems with external AI expertise
• Investigating technologies before architecture decisions
• Documenting learning from external sources
• Building knowledge base for your team

Subcommands

/research:ask - Generate Research Prompt

Generate a comprehensive, context-rich research prompt for web AI tools.

Purpose: Creates detailed 200+ line prompts that include your codebase context, exact error messages, what you've tried, and specific questions.

Command:

Copy/research:ask TOPIC="your topic" [DETAILS="constraints"] [ERROR="error message"]

Parameters:

Key Features:

• Generates 200+ lines minimum - Detailed and comprehensive
• Includes actual code snippets - 50+ lines from your codebase
• Embeds exact errors - Full stack traces if troubleshooting
• Lists attempted solutions - Shows what you've already tried
• Asks specific questions - 3+ targeted questions for the AI
• Output only - No files written, you copy to external AI tool

What Gets Generated:

The prompt includes these mandatory sections:

• Project Context - Framework, dependencies, relevant files
• Current Implementation - 50+ lines of actual code from your codebase
• The Problem - Exact error messages, stack traces, expected vs actual behavior
• What We've Already Tried - 2+ approaches with results and analysis
• Specific Questions - 3+ targeted questions to answer
• What I Need - Root cause analysis, step-by-step solution, code examples, gotchas
• Environment Details - Versions and system information
• References - Source links if citing documentation

Quality Validation:

Before outputting, the command verifies:

• Length ≥ 200 lines
• Code snippets ≥ 50 lines
• Error messages verbatim (if applicable)
• ≥ 2 tried approaches listed
• ≥ 3 specific questions included

Example:

Copy# Research OAuth issue
/research:ask TOPIC="next-auth Google OAuth unauthorized_client" ERROR="[auth][error] CallbackRouteError: unauthorized_client"
 
# Output: 250+ line prompt with code, error details, what was tried, and specific questions
# Copy output → ChatGPT/Claude web → Get expert analysis
# Then use /research:import to save the response

Workflow:

1. /research:ask TOPIC="..."
   ↓ (command generates prompt)
2. Copy prompt output
3. Paste into ChatGPT/Claude web/Perplexity
4. Get expert analysis
5. /research:import TOPIC="..." CONTENT="paste response"
   ↓ (command saves and structures results)
6. Results saved to docs/10-research/YYYYMMDD-topic-slug.md

Integration with babysit:

When /babysit detects you're stuck, it suggests:

Looks like you're stuck on this problem.
Try: /research:ask TOPIC="describe your problem"

/research:import - Import Research Results

Import research results from external AI tools into your research folder with structured formatting.

Purpose: Takes results from ChatGPT, Claude web, Perplexity, YouTube transcripts, or blog posts and saves them as organized markdown files.

Command:

Copy/research:import TOPIC="topic" [CONTENT="results"] [SOURCE="url"]

Parameters:

Key Features:

• Preserves ALL code snippets - Exactly as provided
• Generates actionable items - Concrete next steps, not vague suggestions
• Diff-first preview - Show formatted result before saving
• Updates research index - Automatically adds to docs/10-research/README.md
• Links to decisions - Can reference ADRs, Epics, or Stories

What Gets Created:

Structured research file with sections:

• Summary - 2-3 paragraph TL;DR
• Key Findings - Main takeaways as bullet points
• Implementation Approach - Step-by-step plan if applicable
• Code Snippets - All code preserved exactly as provided
• Action Items - Concrete next steps (checkboxes)
• Risks & Gotchas - Warnings and edge cases
• Story Suggestions - Potential features if research suggests work
• Raw Content Reference - Original content collapsed for reference

File Location:

docs/10-research/YYYYMMDD-topic-slug.md

Index Update:

Research entry added to docs/10-research/README.md:

Copy| Date | Topic | File | Summary |
|------|-------|------|---------|
| 2025-01-01 | OAuth 2.0 Setup | 20250101-oauth-setup.md | OAuth flows, security, best practices |

Example:

Copy# After getting ChatGPT response about OAuth
/research:import TOPIC="OAuth 2.0 Setup" SOURCE="https://chatgpt.com"
 
# Prompts: "Paste the ChatGPT response"
# You paste content
# Command shows preview
# You confirm
# Results saved to docs/10-research/20250101-oauth-setup.md

Works With:

• ChatGPT responses
• Claude web conversations
• Perplexity research results
• YouTube video transcripts
• Blog post excerpts
• Conference talk notes
• Documentation pages
• Meeting notes

/research:list - Show Research Notes Index

Display all research notes in your project with a quick overview.

Purpose: Shows research notes stored in docs/10-research/ with date, topic, filename, and summary.

Command:

Copy/research:list

Parameters: None

Key Features:

• Read-only - No files written
• Shows all notes - Date, topic, filename
• Sorted by date - Newest first
• Quick action hints - Suggestions for next commands

Output Example:

## Research Notes

| Date | Topic | File |
|------|-------|------|
| 2025-01-01 | OAuth 2.0 Setup | 20250101-oauth-setup.md |
| 2024-12-31 | TypeScript Performance | 20241231-typescript-perf.md |
| 2024-12-28 | Mermaid Diagrams | 20241228-mermaid.md |

Total: 3 research notes

Quick actions:
- /research:view FILE=20250101-oauth-setup.md - Read a note
- /research:ask TOPIC="new topic" - Create new research
- /research:import - Import external content

When to Use:

• Find past research before implementing
• Look up code snippets you've researched
• Check action items from previous research

/research:view - Read Specific Research Note

Display the full content of a research note from your research folder.

Purpose: Read and review research notes to find code snippets, action items, and findings.

Command:

Copy/research:view FILE=<filename>

Parameters:

Key Features:

• Read-only - No files written
• Full content - Entire file displayed, not truncated
• Find anything - Code snippets, action items, findings

Example:

Copy# View OAuth research
/agileflow:research:view FILE=20250101-oauth-setup.md
 
# Output: Full content of the file

Output Includes:

• Complete research file content
• All code snippets from the research
• Action items with checkboxes
• Key findings and gotchas
• Risks and considerations
• References and sources

Workflow Examples

Full Research Workflow

Scenario: You're stuck on authentication and need expert help.

Copy# Step 1: Generate detailed research prompt
/research:ask TOPIC="next-auth Google OAuth unauthorized_client error" \
  ERROR="[auth][error] CallbackRouteError: unauthorized_client"
 
# Output: 250+ line detailed prompt with your code, error, what you tried, questions
# → Copy the prompt
 
# Step 2: Paste into ChatGPT/Perplexity
# → Get expert analysis back
 
# Step 3: Import the results
/research:import TOPIC="next-auth OAuth Fix" SOURCE="https://chatgpt.com"
 
# Prompts for content → paste ChatGPT response
# → Shows preview of formatted file
# → Saves to docs/10-research/YYYYMMDD-nextauth-oauth-fix.md
 
# Step 4: Reference in your work
# - Create ADR referencing the research
# - Create story based on action items
# - Check action items when implementing
 
# Step 5: Review research when implementing
/research:list                    # See all research
/research:view FILE=<filename>    # Review details

Investigating Before Architecture Decision

Copy# Step 1: Research database options
/research:ask TOPIC="PostgreSQL vs MongoDB for real-time collaboration"
 
# Step 2: Get expert comparison, use cases, tradeoffs
# → Copy response from ChatGPT/Perplexity
 
# Step 3: Import results
/research:import TOPIC="Database Selection Analysis"
 
# Step 4: Create ADR referencing research
# /adr NEW
# Mention: "See research in docs/10-research/"
 
# Step 5: Team reviews research before decision
/research:view FILE=20250101-database-selection.md

Learning from External Content

Copy# You find a great article/YouTube video about your tech
 
# Step 1: Import the content
/research:import TOPIC="Next.js App Router Advanced Patterns" \
  SOURCE="https://example.com/article"
 
# Copy/paste key sections → saves to research folder
 
# Step 2: Reference from architecture docs
# docs/04-architecture/... → "See research: [link]"
 
# Step 3: Create stories from action items
# "Per research, we should implement error boundaries"

Integration with Other Commands

babysit - Stuck Detection

When /babysit detects you're stuck on a problem:

⚠️ You're working on this for a while. Need help?

Try:
  /research:ask TOPIC="describe your problem"

ADR - Architecture Decisions

Reference research in architecture decisions:

Copy# ADR-0042: Use PostgreSQL for persistence
 
**Research**: See [Database Comparison](../10-research/20250101-database-selection.md)
 
Based on the research findings, we decided to use PostgreSQL because...

Stories and Epics

Create work from research findings:

Copy# After importing research results
/research:import TOPIC="Auth Pattern"
 
# Then create story based on action items
/epic NEW
# Include: "Based on research: docs/10-research/20250101-auth-pattern.md"

Best Practices

Research Prompt Generation

1. Be specific with TOPIC - Don't just say "help with auth", say "next-auth 5.0 with Google OAuth"
2. Include ERROR messages - Full stack traces help tremendously
3. Document what you tried - Shows the AI you've done homework
4. Ask specific questions - "Why is X happening?" not "How do I fix this?"

Good TOPIC examples:

• "next-auth Google OAuth unauthorized_client error with Next.js 14 App Router"
• "TypeScript strict mode compilation errors in monorepo setup"
• "Stripe webhook signature validation failing in development"

Bad TOPIC examples:

• "help with authentication"
• "why is my code broken"
• "error in my app"

Research Import

1. Always cite the source - Where did you get this from?
2. Preserve code snippets exactly - Don't modify examples
3. Extract key findings - Don't just paste raw content
4. Generate action items - What should you do with this?
5. Link to decisions - Reference ADRs, Epics, Stories if relevant

Managing Research

1. Review before implementing - Don't blindly follow research
2. Check action items - Use checkboxes to track what you did
3. Keep files current - Update if you learn more
4. Reference in decisions - Link from ADRs and stories
5. Archive old research - Move outdated findings to archive directory

Research Structure

Research files are stored with ISO date prefixes:

docs/10-research/
├── README.md                                    (Index table)
├── 20250101-oauth-setup.md
├── 20241231-typescript-performance.md
└── 20241228-mermaid-diagrams.md

File Naming

YYYYMMDD-topic-slug.md

Examples:
- 20250101-oauth-setup.md
- 20241231-stripe-webhooks.md
- 20241228-typescript-strict-mode.md

Research Index

The docs/10-research/README.md maintains a table of all research notes:

Copy# Research Notes
 
| Date | Topic | File | Summary |
|------|-------|------|---------|
| 2025-01-01 | OAuth 2.0 Setup | 20250101-oauth-setup.md | OAuth flows, security, best practices |
| 2024-12-31 | TypeScript Performance | 20241231-typescript-perf.md | Optimization techniques and tsconfig tuning |
| 2024-12-28 | Mermaid Diagrams | 20241228-mermaid.md | Diagram syntax, rendering, and best practices |

When to Use Research

Before Architecture Decisions

Research tools and frameworks before recommending them:

Copy/research:ask TOPIC="PostgreSQL vs MongoDB for real-time sync"
# → Get expert comparison
/research:import  # Import results
# → Create ADR referencing the research

Feature Investigation

Deep-dive into how to implement complex features:

Copy/research:ask TOPIC="Next.js App Router middleware patterns"
/research:ask TOPIC="OAuth 2.0 implementation with security best practices"
/research:ask TOPIC="Real-time WebSocket architecture in Node.js"

Troubleshooting Difficult Problems

Get expert help when stuck:

Copy/research:ask TOPIC="TypeScript strict mode in monorepo" \
  ERROR="error TS1149: File is a CommonJS module..."

Learning & Training

Document learnings from courses, tutorials, or documentation:

Copy/research:import TOPIC="React 18 Suspense and Streaming" \
  SOURCE="https://react.dev/reference/react/Suspense"

Technology Evaluation

Compare options before adoption:

Copy/research:ask TOPIC="GraphQL vs tRPC for type-safe APIs"
/research:ask TOPIC="SvelteKit vs Next.js for new project"

Troubleshooting

Research Prompt Too Short

If you get a prompt under 200 lines, the command will regenerate. Make sure:

• TOPIC is specific (include framework versions, error types)
• ERROR includes full stack trace if troubleshooting
• Command reads your actual codebase

Import Not Updating Index

The index (docs/10-research/README.md) is automatically created and updated. If it's missing:

Copy/agileflow:research:list  # This will create the index if missing

Can't Find Research File

Use /research:list to see all available files:

Copy/research:list
# Shows all files with correct filenames for /research:view

Research Folder Doesn't Exist

First research import or list command creates the docs/10-research/ directory automatically. No manual setup needed.

Related Commands

• /babysit - Detects stuck situations and suggests research:ask
• /adr - Create architecture decisions referencing research
• /epic - Create epics based on research findings
• /story - Create stories with research references