ralph-prompt-research

Generates structured prompts for research, analysis, and planning tasks using the Ralph Wiggum technique. These prompts define clear research methodology, required sources, synthesis requirements, and concrete deliverables rather than code.

Best For:

• Codebase analysis and audits
• Security vulnerability assessments
• Technology research and comparison
• Migration planning
• Architecture design documents
• Performance analysis
• Dependency audits
• Documentation generation from code

Ralph Philosophy: This generator embraces the principle that failures are deterministic and fixable. Each research iteration builds on previous findings. Don't fear incomplete first passes—they're expected and provide data for deeper analysis in subsequent iterations.

Input Required:

1. Research objective (what you need to understand/analyze)
2. Scope (what to include/exclude)
3. Deliverable format (report, plan, document)
4. Completion promise

Generate prompt with:

```

Generate a Ralph research prompt for:

Objective: [What to research/analyze]

Scope: [What's included]

Deliverable: [What to produce]

Promise: [COMPLETION_PHRASE]

```

Step 1: Define Research Scope

Research Definition Template:

```markdown

OBJECTIVE: [What question to answer or what to analyze]

SCOPE:

Include: [What's in scope]

Exclude: [What's explicitly out of scope]

SOURCES: [Where to look for information]

DELIVERABLE: [What artifact to produce]

SUCCESS: [How to know research is complete]

```

Step 2: Map Research Phases

Standard research phases:

| Phase | Name | Purpose | Deliverable |

|-------|------|---------|-------------|

| 1 | Discovery | Identify what exists | Inventory/map |

| 2 | Analysis | Deep dive into findings | Analysis notes |

| 3 | Synthesis | Draw conclusions | Findings summary |

| 4 | Recommendations | Actionable next steps | Recommendation doc |

| 5 | Documentation | Final deliverable | Complete report |

Step 3: Define Completion Criteria

Research completion criteria must be:

• Based on coverage (examined all relevant items)
• Based on depth (sufficient analysis per item)
• Based on deliverable completeness (all sections written)

Examples:

| Research Type | Completion Criteria |

|---------------|---------------------|

| Security audit | All OWASP categories checked, all findings documented |

| Codebase analysis | All modules examined, architecture documented |

| Tech comparison | All options evaluated against all criteria |

| Migration plan | All systems inventoried, migration steps defined |

Step 4: Structure the Prompt

Use this template:

```markdown

# Research: [Research Title]

[Clear statement of what this research aims to answer or analyze]

In Scope

• [Item 1 to analyze]
• [Item 2 to analyze]
• [Item 3 to analyze]

Out of Scope

• [Explicitly excluded 1]
• [Explicitly excluded 2]

• [Source type 1]: [Where to find]
• [Source type 2]: [Where to find]
• [Source type 3]: [Where to find]

---

Objective

Create comprehensive inventory of [what to inventory].

Tasks

1. [Discovery task 1]
2. [Discovery task 2]
3. [Discovery task 3]

Deliverable: Inventory

Create [filename].md with:

```markdown

# [Inventory Title]

| # | Item | Location | Type | Notes |

|---|------|----------|------|-------|

| 1 | | | | |

| 2 | | | | |

```

Phase 1 Success Criteria

• [ ] All [scope items] examined
• [ ] Inventory file created
• [ ] No areas unexplored

Phase 1 Checkpoint

Document in inventory file:

```

DISCOVERY COMPLETE:

• Items found: [count]
• Areas examined: [list]
• Coverage: Complete/Partial

```

---

Objective

Deep analysis of each discovered item.

Analysis Framework

For each item, analyze:

• [Dimension 1]: [What to examine]
• [Dimension 2]: [What to examine]
• [Dimension 3]: [What to examine]

Tasks

1. Analyze each item against framework
2. Document findings per item
3. Identify patterns across items
4. Note anomalies or concerns

Deliverable: Analysis Notes

Create [analysis-filename].md with:

```markdown

# Analysis: [Item Name]

[Findings]

[Findings]

[Findings]

[Key takeaways for this item]

```

Phase 2 Success Criteria

• [ ] All inventory items analyzed
• [ ] Analysis notes for each item
• [ ] Patterns identified
• [ ] Anomalies documented

Phase 2 Checkpoint

```

ANALYSIS COMPLETE:

• Items analyzed: [X/Y]
• Key patterns: [list]
• Concerns identified: [count]

```

---

Objective

Synthesize findings into coherent conclusions.

Tasks

1. Review all analysis notes
2. Identify overarching themes
3. Draw conclusions from patterns
4. Prioritize findings by impact
5. Formulate key insights

Deliverable: Findings Summary

Create [findings-filename].md with:

```markdown

# Research Findings: [Topic]

[2-3 paragraphs summarizing key findings]

1. [Finding 1]: [Description and evidence]
2. [Finding 2]: [Description and evidence]
3. [Finding 3]: [Description and evidence]

• [Pattern 1]
• [Pattern 2]

1. [Concern 1]: [Details]
2. [Concern 2]: [Details]

• Total items examined: [X]
• Categories: [list]
• Analysis coverage: [X%]

```

Phase 3 Success Criteria

• [ ] All findings synthesized
• [ ] Conclusions supported by evidence
• [ ] Priorities established
• [ ] Summary document complete

---

Objective

Provide actionable recommendations based on findings.

Tasks

1. Develop recommendations for each finding
2. Prioritize by impact and effort
3. Identify dependencies between recommendations
4. Create action timeline (if applicable)

Deliverable: Recommendations

Add to findings document or create separate:

```markdown

# Recommendations

1. [Recommendation]

- Rationale: [Why]

- Effort: [Low/Medium/High]

- Impact: [Low/Medium/High]

- Dependencies: [Any]

[...]

[...]

1. First: [Recommendation X]
2. Then: [Recommendation Y]
3. Finally: [Recommendation Z]

```

Phase 4 Success Criteria

• [ ] All findings have recommendations
• [ ] Priorities assigned
• [ ] Implementation order defined
• [ ] Dependencies identified

---

Objective

Produce final polished deliverable.

Tasks

1. Compile all sections into final document
2. Add executive summary
3. Review for completeness
4. Ensure actionability
5. Format consistently

Deliverable: Final Report

Create [final-report].md with all sections:

1. Executive Summary
2. Scope and Methodology
3. Findings
4. Analysis
5. Recommendations
6. Appendix (raw data if needed)

Phase 5 Success Criteria

• [ ] All sections complete
• [ ] Executive summary written
• [ ] Consistent formatting
• [ ] No TODO items
• [ ] Actionable and clear

---

Completeness Checklist

• [ ] Phase 1: Discovery complete, inventory exists
• [ ] Phase 2: All items analyzed, notes exist
• [ ] Phase 3: Findings synthesized, summary exists
• [ ] Phase 4: Recommendations provided, prioritized
• [ ] Phase 5: Final document complete

Quality Checklist

• [ ] All conclusions supported by evidence
• [ ] Recommendations are actionable
• [ ] Document is well-organized
• [ ] No sections are missing content
• [ ] Executive summary captures key points

When ALL of the following are true:

• All 5 phases completed
• All deliverables created
• Completeness checklist verified
• Quality checklist verified

Output: [COMPLETION_PHRASE]

```

RESEARCH PROGRESS:

Phase 1 (Discovery): [COMPLETE/IN PROGRESS]

Phase 2 (Analysis): [COMPLETE/IN PROGRESS/NOT STARTED]

Phase 3 (Synthesis): [COMPLETE/IN PROGRESS/NOT STARTED]

Phase 4 (Recommendations): [COMPLETE/IN PROGRESS/NOT STARTED]

Phase 5 (Documentation): [COMPLETE/IN PROGRESS/NOT STARTED]

Items examined: [X/Y]

Deliverables created: [list]

```

• Document what information is missing
• List sources already examined
• Identify the specific gap
• Do NOT skip analysis or output false promise

```

Example 1: Security Audit

Input:

• Objective: Identify security vulnerabilities in authentication module
• Scope: src/auth/ directory
• Deliverable: Security audit report with findings and fixes
• Promise: SECURITY_AUDIT_COMPLETE

Generated Prompt:

```markdown

# Research: Authentication Security Audit

Identify security vulnerabilities in the authentication module following OWASP guidelines and provide remediation recommendations.

In Scope

• All files in src/auth/
• Authentication flows (login, signup, password reset)
• Session management
• Token handling
• Input validation

Out of Scope

• Authorization (permissions, roles)
• Third-party auth providers
• Frontend security

• Code files: src/auth/*/.ts
• Tests: tests/auth/*/.ts
• Configuration: auth-related config files
• Dependencies: auth-related npm packages

---

Tasks

1. List all files in auth module
2. Identify all entry points (routes)
3. Map authentication flows
4. Identify external dependencies
5. List all sensitive operations

Deliverable: auth-inventory.md

```markdown

# Auth Module Inventory

| File | Purpose | Entry Points | Sensitive Ops |

|------|---------|--------------|---------------|

| Package | Version | Security Notes |

1. Login: [path]
2. Signup: [path]

[...]

```

Phase 1 Success

• [ ] All auth files listed
• [ ] All entry points identified
• [ ] Flows mapped
• [ ] Dependencies inventoried

---

Security Analysis Framework

For each component, check:

• A1 Injection: SQL, NoSQL, command injection risks
• A2 Broken Auth: Weak passwords, session issues
• A3 Sensitive Data: Password storage, token exposure
• A4 XXE: XML parsing vulnerabilities
• A5 Access Control: Proper authorization checks
• A6 Misconfiguration: Insecure defaults
• A7 XSS: User input handling
• A8 Deserialization: Unsafe object handling
• A9 Components: Vulnerable dependencies
• A10 Logging: Insufficient monitoring

Tasks

1. Analyze each file against OWASP framework
2. Check password hashing implementation
3. Review JWT token handling
4. Examine session management
5. Check input validation

Deliverable: security-analysis.md

Per-file analysis with vulnerabilities found.

---

Tasks

1. Categorize all vulnerabilities by severity
2. Identify systemic issues
3. Calculate risk scores
4. Prioritize by exploitability

Deliverable: security-findings.md

```markdown

# Security Findings

• [Vulnerability]: [Location] - [Impact]

[...]

[...]

[...]

• Critical: X
• High: X
• Medium: X
• Low: X

```

---

Tasks

1. Provide fix for each vulnerability
2. Prioritize fixes by risk
3. Estimate effort for each fix
4. Identify quick wins

Deliverable: remediation-plan.md

```markdown

# Remediation Plan

1. [Fix]: [How] - [Effort]

[...]

[...]

```

---

Deliverable: AUTH-SECURITY-AUDIT.md

Complete report with:

1. Executive Summary
2. Methodology
3. Findings by Severity
4. Detailed Vulnerability Descriptions
5. Remediation Plan
6. Verification Steps

---

When audit report complete with all vulnerabilities documented and remediation provided:

Output: SECURITY_AUDIT_COMPLETE

```

Example 2: Technology Comparison

Input:

• Objective: Compare React vs Vue vs Svelte for new frontend
• Scope: Team skills, project requirements, ecosystem
• Deliverable: Comparison report with recommendation
• Promise: FRAMEWORK_COMPARISON_COMPLETE

Generated Prompt:

```markdown

# Research: Frontend Framework Comparison

Compare React, Vue, and Svelte to recommend the best framework for the new frontend project based on team skills, project requirements, and ecosystem.

In Scope

• Learning curve for team
• Performance characteristics
• Ecosystem (libraries, tools)
• Community and support
• Project requirements fit
• Long-term maintainability

Out of Scope

• Mobile development (React Native, etc.)
• SSR frameworks (Next.js, Nuxt, SvelteKit)
• Backend considerations

---

Tasks

1. Document team's current skills
2. List project requirements
3. Identify key evaluation criteria
4. Gather framework documentation

Deliverable: evaluation-criteria.md

```markdown

# Evaluation Framework

• Current experience: [frameworks]
• Available learning time: [duration]
• Team size: [N]

• [Requirement 1]
• [Requirement 2]

[...]

| Criterion | Weight | Reason |

|-----------|--------|--------|

| Learning curve | 25% | Team has limited React experience |

| Performance | 20% | App will be data-heavy |

[...]

```

---

Analysis Framework

For each framework:

• Learning Curve: Time to productivity
• Performance: Bundle size, runtime speed, memory
• Ecosystem: Available libraries, tools, IDE support
• Community: Documentation, Stack Overflow, GitHub activity
• Hiring: Developer availability
• Architecture: How it fits project patterns

Deliverable: framework-analysis.md

```markdown

# React Analysis

[Analysis]

[Analysis]

[... repeat for Vue and Svelte]

```

---

Tasks

1. Score each framework on each criterion
2. Apply weights
3. Calculate overall scores
4. Identify dealbreakers

Deliverable: comparison-matrix.md

```markdown

# Framework Comparison Matrix

| Criterion | Weight | React | Vue | Svelte |

|-----------|--------|-------|-----|--------|

| Learning Curve | 25% | 3 | 4 | 4 |

| Performance | 20% | 3 | 4 | 5 |

[...]

| Weighted Total | | X.X | X.X | X.X |

```

---

Deliverable: recommendation.md

```markdown

# Framework Recommendation

Rationale

[Why this framework is best for this team and project]

Advantages

• [Advantage 1]
• [Advantage 2]

Concerns and Mitigations

• [Concern 1]: [How to address]

Implementation Approach

1. [Step 1]
2. [Step 2]

[...]

```

---

Deliverable: FRAMEWORK-COMPARISON-REPORT.md

---

When complete comparison with recommendation:

Output: FRAMEWORK_COMPARISON_COMPLETE

```

Research Methodology

• Define scope explicitly (what's in/out)
• Use consistent analysis framework
• Document evidence for conclusions
• Separate findings from opinions

Deliverables

• Create artifacts as you go
• Use consistent format
• Include data to support conclusions
• Make recommendations actionable

DO:

• Define clear scope boundaries
• Create deliverables at each phase
• Support conclusions with evidence
• Provide actionable recommendations
• Track progress systematically

DON'T:

• Skip the discovery phase
• Make recommendations without evidence
• Leave sections incomplete
• Output promise before documentation

```bash

/ralph-wiggum:ralph-loop "[paste generated prompt]" --completion-promise "YOUR_PROMISE" --max-iterations 50

```

Recommended iterations by research complexity:

• Simple audit (single module): --max-iterations 30-40
• Comparison (3-5 options): --max-iterations 40-60
• Full codebase analysis: --max-iterations 70-100
• Complex planning: --max-iterations 60-80

---

For single-task prompts, see ralph-prompt-single-task.

For multi-task prompts, see ralph-prompt-multi-task.

For project-level prompts, see ralph-prompt-project.