rails-deep-research

---
name: rails-deep-research
description: Conduct thorough, multi-source research on any Rails or Ruby topic — architecture patterns, gem comparisons, security advisories, performance benchmarks, migration guides, or industry best practices. Produces structured reports with cited sources. Use for complex topics that need synthesis across multiple sources.
license: MIT
---

# Rails Deep Research

Conduct comprehensive, multi-source research on complex Rails and Ruby topics. Systematically gather, evaluate, and synthesize information into structured reports with proper citations.

**Autonomy principle:** Operate independently. Infer what the user needs from the query. Only stop for critical ambiguity or incomprehensible questions — not for every missing detail.

## When to Use

Activate this skill when the request matches any of these:

- "Research X", "deep dive on X", "what's the best approach for X in Rails"
- Architecture decisions: "Should we use Sidekiq or Solid Queue?", "Pundit vs CanCanCan?"
- Security: "What are the current Rails security best practices?", "Are there known vulnerabilities in gem X?"
- Performance: "How should we approach caching in Rails 8?", "What's the fastest way to serialize JSON?"
- Migration: "How do we upgrade from Rails 7 to Rails 8?", "How to move from Sidekiq to Solid Queue?"
- "Pros and cons of X", "benchmark X vs Y in Ruby"
- White paper, briefing, or technical overview of a Rails topic

## When NOT to Use

- Simple factual lookups (1–2 searches) — use web search directly
- Looking for a specific gem — use `rails-gem-finder`
- Questions answerable from the current codebase — read the code
- Security scanning of this specific app — use `rails-security-audit`

## Research Methodology

### Phase 1: Orient

Before searching, define:
1. **Core question** — what specifically needs to be answered?
2. **Audience** — developer implementing it, architect deciding, team lead evaluating options?
3. **Scope** — Rails version, Ruby version, deployment environment, existing constraints?
4. **Output format** — decision recommendation, comparison table, migration guide, reference doc?

### Phase 2: Multi-Angle Search

Run searches across multiple angles simultaneously. Cast a wide net:

```
# Official docs and changelogs
webSearch("Rails 8 <topic> official documentation")
webSearch("site:api.rubyonrails.org <topic>")
webSearch("site:guides.rubyonrails.org <topic>")

# Community and expert sources
webSearch("<topic> Rails best practices 2025 2026")
webSearch("<topic> ruby performance benchmark site:github.com")
webSearch("<gem-a> vs <gem-b> rails site:reddit.com")
webSearch("<topic> site:stackoverflow.com ruby on rails")

# Security and advisories
webSearch("site:rubysec.com <topic>")
webSearch("<gem-name> CVE vulnerability")
webSearch("site:github.com/advisories <gem-name>")

# Real-world experience
webSearch("<topic> rails case study production")
webSearch("<topic> rails thoughtbot blog")
webSearch("<topic> rails gorails site:gorails.com")
webSearch("<topic> ruby weekly newsletter")
```

### Phase 3: Read Sources

`webFetch` every promising URL — don't rely on search snippets for technical decisions. Actually read:
- Official Rails guides and API docs
- GitHub READMEs and CHANGELOGs
- Benchmark articles and performance reports
- Community discussions (blog posts, conference talks)

### Phase 4: Evaluate and Triangulate

For each key claim, check it against at least 2 independent sources. Flag claims with only 1 source as "unverified." For benchmark data, note the Rails/Ruby version and environment.

Source credibility hierarchy for Rails:
1. **Rails core team** — official guides, blog posts, GitHub issues from core team members
2. **Major contributors** — DHH, tenderlove, matthewd, eileencodes
3. **Established community** — Thoughtbot, Evil Martians, Shopify Engineering, Basecamp/37signals
4. **Popular blogs** — GoRails, RubyGuides, RubyWeekly, Honeybadger blog
5. **Stack Overflow/Reddit** — useful for common questions, lower authority for architecture

### Phase 5: Synthesize

Produce a structured report — see output format below.

## Using the Workflow Tool for Deep Research

For complex multi-angle research, fan out to parallel agents:

```javascript
export const meta = {
  name: 'rails-deep-research',
  description: 'Multi-source deep research on a Rails topic',
  phases: [{ title: 'Search' }, { title: 'Synthesize' }],
}

const ANGLES = [
  { label: 'official-docs',   prompt: `Search official Rails/Ruby documentation for: ${args.topic}` },
  { label: 'community',       prompt: `Search community blogs, GoRails, Thoughtbot, Evil Martians for: ${args.topic}` },
  { label: 'benchmarks',      prompt: `Search for performance benchmarks and real-world measurements for: ${args.topic}` },
  { label: 'security',        prompt: `Search for security advisories, CVEs, and security considerations for: ${args.topic}` },
  { label: 'gems',            prompt: `Search RubyGems and GitHub for relevant gems and libraries for: ${args.topic}` },
]

phase('Search')

const findings = await parallel(
  ANGLES.map(angle => () =>
    agent(
      `${angle.prompt}\n\nUse web search and fetch full pages of promising results. Return:\n- key findings with source URLs\n- specific version requirements or caveats\n- any conflicting information across sources\n\nBe thorough — search multiple queries, read multiple pages.`,
      { label: `research:${angle.label}`, phase: 'Search' }
    )
  )
)

phase('Synthesize')

const report = await agent(
  `Synthesize these research findings into a comprehensive report on: ${args.topic}\n\nFindings:\n${findings.filter(Boolean).join('\n\n---\n\n')}\n\nProduce a structured report with:\n1. Executive Summary (3-5 sentences)\n2. Key Findings (cited)\n3. Recommendations (specific, actionable)\n4. Trade-offs and Caveats\n5. Source List\n\nWrite for a senior Rails developer making a real decision.`,
  { label: 'synthesize', phase: 'Synthesize' }
)

return { report }
```

## Output Format

Structure reports as:

```markdown
# Research: [Topic]

## Executive Summary
3–5 sentences: what was found, what is recommended, key caveat.

## Key Findings

### [Finding 1]
[Detail with source citation]

### [Finding 2]
...

## Recommendations

1. **[Specific action]**: [Why, with conditions]
2. **[Alternative]**: [When to use instead]

## Trade-offs

| Option | Pros | Cons | Best for |
|--------|------|------|----------|
| ...    | ...  | ...  | ...      |

## Caveats and Open Questions

## Sources

- [Source 1](url) — [why trustworthy]
- [Source 2](url)
```

## Best Practices

1. **Search multiple angles** — official docs, community, benchmarks, security, GitHub issues all give different signal
2. **Read, don't skim** — fetch and read full pages for important claims
3. **Check the date** — Rails and Ruby evolve fast; a 2021 blog post may be wrong for Rails 8
4. **Note version specificity** — a Rails 6 pattern may have a better Rails 8 equivalent
5. **Triangulate** — one source ≠ truth, especially for performance claims
6. **Present trade-offs honestly** — every approach has weaknesses; say so