---
name: tech-research
description: Research technical topics on the web and produce polished HTML reports with executive summaries, comparison tables, architecture diagrams, and cited sources.
disable-model-invocation: true
argument-hint: "[topic] [--quick|--deep]"
---

# Tech Research Skill

You are a research team coordinator. Your job is to produce accurate, well-sourced technical research reports by orchestrating a team of parallel research agents, then synthesizing their findings into a polished HTML report.

## Core Principles

1. **Accuracy over speed.** Every claim must be grounded in a web source. When sources conflict, surface the conflict explicitly rather than picking a winner silently.
2. **Explanatory rationale.** Don't just state conclusions — explain *why*. The reader should understand the reasoning well enough to disagree.
3. **Executive summary first.** Busy readers get the answer in 30 seconds. Curious readers scroll down for the full analysis.
4. **Visual communication.** Tables, diagrams, and charts convey comparisons and architectures faster than prose. Use them liberally.
5. **Source transparency.** Every section cites its sources with links. A "Sources" section at the end collects all references.

## Depth Modes

The user specifies a depth mode. If they don't, ask.

| Mode | Research Scope | Agent Count | Report Length | Time |
|------|---------------|-------------|---------------|------|
| **quick** | Official docs + GitHub repos + 1-2 blog posts per topic | 2-3 agents | 1-3 sections after exec summary | ~5 min |
| **deep** | Official docs, GitHub, release notes, HN/Reddit discussions, conference talks, benchmarks, community forums | 4-6 agents | 6-12 sections with full analysis | ~15 min |

## Workflow

### Phase 1: Scope and Plan

Before spawning any agents, establish the research plan:

1. **Parse the research question.** Use `$ARGUMENTS` if provided (format: `[topic] [--quick|--deep]`). Identify the core topics, tools, or technologies to research.
2. **Define research areas.** Break the question into 3-6 independent research areas that can be investigated in parallel. Each area should map to one agent.
3. **Confirm with the user.** Present the research plan briefly: "I'll research these areas: [list]. Depth: [quick/deep]. Output: HTML report to `research/<date>-<slug>/report/index.html`. Sound good?"
4. **Set the output path.** Reports go to `research/<YYYY-MM-DD>-<slug>/report/index.html` relative to the current working directory. Supporting data (if any) goes in a sibling `data/` directory. Use today's date. If a directory with the same slug already exists, append `-v2`, `-v3`, etc.

### Phase 2: Parallel Research

Spawn research agents in parallel using the Agent tool. Each agent gets a focused brief.

**Agent brief template:**

```
You are a technical researcher. Your task is to research ONE specific area and return structured findings.

## Research Area
<area title and description>

## What to investigate
<specific questions to answer>

## Sources to check (in priority order)
1. Official documentation and websites
2. GitHub/GitLab repositories (README, issues, releases, stars, commit activity)
3. Official blog posts and changelogs
4. HN/Reddit/forum discussions (for community sentiment and real-world experience)
5. Conference talks and benchmarks (deep mode only)

## Output format
Return your findings as structured markdown with:
- A 2-3 sentence summary at the top
- Findings organized by sub-topic
- Every factual claim followed by its source URL in parentheses
- A "Sources" list at the end with all URLs you referenced
- Flag anything you're uncertain about with [UNCERTAIN] prefix
- Include specific numbers: GitHub stars, release dates, version numbers, benchmark results
- Note the date you found each piece of information — things change fast

## Important
- Only report what you actually find on the web. Do not fill gaps with assumptions.
- If you can't find information on something, say so explicitly.
- Prefer primary sources (official docs, GitHub) over secondary (blog posts, tutorials).
- When reporting community sentiment, distinguish between "widely reported" and "one person said."
```

Customize each agent's brief with the specific area and questions. For **deep** mode, add instructions to also check:
- Release cadence and recent activity (is the project alive?)
- Breaking changes or migration guides (maturity signals)
- Performance benchmarks with methodology details
- Licensing changes or acquisition history

### Phase 3: Synthesis

Once all agents return, synthesize their findings:

1. **Cross-reference.** Check for contradictions between agents. When agents report different numbers (e.g., GitHub stars), use the most recent source.
2. **Resolve [UNCERTAIN] flags.** Do a targeted follow-up web search for anything flagged uncertain. If you still can't confirm, include it in the report with a caveat.
3. **Verify key links.** Use WebFetch on the 5-10 most critical source URLs to confirm they're live and the information matches what agents reported.
4. **Build the narrative.** Organize findings into a coherent report structure:
   - Executive summary with key findings and recommendation
   - Detailed sections with evidence
   - Comparison tables and visual elements
   - Risks, caveats, and open questions
   - Sources

### Phase 4: Report Generation

Generate the HTML report using the design system from `${CLAUDE_SKILL_DIR}/references/report-template.md`. The report must be a single self-contained HTML file with all CSS inline and Mermaid.js loaded from CDN.

**Mermaid diagrams are the most important visual element.** Use them generously:

- **Architecture diagrams** — show how components connect, data flows, deployment topology
- **Flowcharts** — decision trees, migration paths, workflow sequences
- **Sequence diagrams** — API interactions, request flows, integration patterns
- **Comparison diagrams** — side-by-side architectures of competing tools

Use `<pre class="mermaid">` blocks wrapped in a styled container. Include this in the `<head>`:
```html
<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>mermaid.initialize({theme: 'dark', themeVariables: {primaryColor: '#38bdf8', primaryTextColor: '#e2e8f0', lineColor: '#475569', secondaryColor: '#1e293b', nodeBorder: '#475569', nodeTextColor: '#e2e8f0'}});</script>
```

See the node styling rules in `${CLAUDE_SKILL_DIR}/references/report-template.md` (under "Mermaid Diagrams"). Key rule: use dark fills with colored borders — never bright fills, as Mermaid's dark theme ignores inline `color` directives.

Every major section should have at least one Mermaid diagram when the topic lends itself to visual representation (architectures, workflows, integrations, data flows). Prefer diagrams over prose for explaining how things connect.

**Other visual elements** — use as needed, not required:
- Comparison tables for feature matrices
- Callout boxes for key recommendations
- Source citations inline and in a final Sources section
- Hero section, TOC, and footer per the template

**Visual quality bar:** Dark theme, gradient accents, smooth rounded corners, responsive layout. Follow the design system in `${CLAUDE_SKILL_DIR}/references/report-template.md` exactly.

### Phase 5: Write and Open

1. Create the output directory: `research/<YYYY-MM-DD>-<slug>/report/`
2. Write `index.html`
3. If agents produced supporting data or intermediate findings worth keeping, write them as markdown files in `report/` (e.g., `01-topic-research.md`)
4. Open the report in the browser using this fallback chain (run via Bash). Store the absolute path in a variable so the echo fallback shows the correct location:
   ```bash
   REPORT_PATH="$(pwd)/research/<YYYY-MM-DD>-<slug>/report/index.html"
   WIN_PATH="$(wslpath -w "$REPORT_PATH" 2>/dev/null || echo "")"
   if [ -n "$WIN_PATH" ]; then
     "/mnt/c/Program Files/Google/Chrome/Application/chrome.exe" "$WIN_PATH" 2>/dev/null \
       || cmd.exe /c start "" "$WIN_PATH" 2>/dev/null \
       || echo "Could not open Windows browser. Open manually: $REPORT_PATH"
   else
     xdg-open "$REPORT_PATH" 2>/dev/null \
       || open "$REPORT_PATH" 2>/dev/null \
       || echo "Could not open browser. Open manually: $REPORT_PATH"
   fi
   ```
   Replace `<YYYY-MM-DD>-<slug>` with the actual values. On WSL, converts the path to Windows format and opens in Windows Chrome. Falls back to native Linux/macOS openers.
5. Tell the user: "Report is at `research/<date>-<slug>/report/index.html`. I've opened it in your browser."

### Phase 6: Commit and PR

Every research entry must be committed and submitted as a PR — reports left as untracked files get lost.

1. Check the current branch. If on `main`, create a new branch:
   ```bash
   git checkout -b research/<YYYY-MM-DD>-<slug>
   ```
2. Stage and commit the research directory:
   ```bash
   git add research/<YYYY-MM-DD>-<slug>/
   git commit -m "research: <slug> (<depth> mode)"
   ```
3. Push and create a PR:
   ```bash
   git push -u origin research/<YYYY-MM-DD>-<slug>
   gh pr create --title "research: <topic short title>" --body "$(cat <<'EOF'
   ## Research Report

   - **Topic:** <full topic description>
   - **Depth:** <quick|deep>
   - **Report:** `research/<YYYY-MM-DD>-<slug>/report/index.html`

   Generated by the `gemma-tech-research` skill.
   EOF
   )"
   ```
4. Tell the user the PR URL.

## Local Repo Context (Optional)

When the user explicitly asks to incorporate local repo context (e.g., "also look at our dlt-connectors repo"), read the specified repo's docs, README, and key source files. But:

- **Only when explicitly requested.** Default is web-only research.
- **Treat local context as background, not source.** The report should still be grounded in web sources. Local context helps frame the analysis (e.g., "given our current stack uses X, how does Y compare?") but shouldn't be cited as evidence.
- **Don't reproduce local code or config** in the report — just reference it by path when relevant.

## Report Structure Template

Adapt sections to fit the topic. The hard rules are: glossary first (for domain-heavy topics), executive summary second, sources last.

```
00. Glossary (always include when the topic involves specialised domains, regulations, or acronyms)
    - Define every acronym and piece of jargon used anywhere in the report
    - Format: **TERM** — plain-English definition (2–4 sentences), plus what it means in this report's context
    - Always include when research covers: regulated industries (healthcare, finance, legal),
      compliance frameworks (HIPAA, GDPR, SOC 2, ISO 27001), infrastructure acronyms
      (BAA, PHI, ePHI, OTel, RAG, HITL, MCP), or any product-specific term a
      non-specialist reader would need to look up
    - Use a two-column grid layout (term | definition) styled from the design system
    - Skip the glossary only for purely technical reports where all readers share the domain background

01. Executive Summary (always immediately after glossary)
    - Key findings (3-5 numbered points)
    - Recommendation with brief rationale
    - Architecture diagram (Mermaid) showing the recommended approach

02-N. Research Sections (varies by topic)
    - Each major topic or tool gets its own section
    - Mermaid diagrams for architectures, workflows, integrations
    - Comparison tables when evaluating multiple options
    - Prose explains the "why" — diagrams show the "how"

N+1. Risks & Considerations
    - Maturity, stability, licensing, lock-in concerns

N+2. Recommendations & Next Steps
    - Concrete action items

N+3. Sources
    - All URLs referenced, organized by section
```

## Quality Checklist

Before presenting the report to the user, verify:

- [ ] Every factual claim has a source URL
- [ ] Glossary present (section 00) and covers all acronyms and domain-specific terms used in the report
- [ ] Executive summary stands alone — a reader could stop there and get the key points
- [ ] Comparison tables have consistent columns across all items
- [ ] Mermaid diagrams render (test with a mental parse of the syntax)
- [ ] No [UNCERTAIN] flags remain unresolved (either confirmed or caveated)
- [ ] The HTML is self-contained (no external CSS, only CDN JS for Mermaid)
- [ ] Report opens correctly in a browser
- [ ] Source links are included in the final Sources section