Research Patterns

Research Patterns

What It Does

Reference conventions for how yellow-research derives slugs, formats reports, and saves output under docs/research/.

When to Use

Use when authoring or modifying yellow-research commands or agents that write research output.

Usage

Reference the sections below as preloaded context — this skill documents conventions; it is not an executable workflow.

Slug Naming

Convert the research topic to a slug for the output filename:

• Characters: [a-z0-9-] only — lowercase, hyphens, no spaces or special chars
• Max length: 40 characters
• Examples:
  • "React Server Components 2026" → react-server-components-2026
  • "How does EXA neural search work?" → exa-neural-search
  • "Competitor analysis: Notion vs Linear" → notion-vs-linear-competitor
• Collision handling: if docs/research/<slug>.md exists, append -2, -3

Output Location

All deep research saves to: docs/research/<slug>.md

Create the directory if it doesn't exist:

mkdir -p docs/research

Output Format

# <Topic Title>

**Date:** YYYY-MM-DD
**Sources:** Perplexity, EXA, Tavily (list which were used)

## Summary

[2-3 sentence executive summary]

## Key Findings

### <Subtopic 1>

[Findings with source citations]

### <Subtopic 2>

[Findings with source citations]

## Sources

- [Source Title](URL) — brief note on what was found here

Source Selection Guide

Ceramic note: Ceramic is a lexical search engine (English only, 1–50-word keyword queries). Before sending a topic to ceramic_search, rewrite it into a concise keyword-form query — drop "how do I", "what is", filler words; keep proper nouns, technical terms, version numbers. See https://docs.ceramic.ai/api/search/best-practices.md. The Ceramic MCP at https://mcp.ceramic.ai/mcp authenticates via OAuth 2.1 (browser flow on first use) — same UX as Parallel Task, no API key in plugin.json.

When to Compound Findings

After /research:deep, run /compound if the findings include:

• A novel architectural pattern worth sharing with the team
• A critical gotcha or anti-pattern discovered
• An institutional decision that will recur (e.g., "we use X instead of Y because...")
• A bug root cause that took significant investigation

Routine informational research does not need to be compounded.

Graceful Degradation

If an MCP server is unavailable (key not set, connection error, rate limit):

• Log a brief note: "Skipping [source] — unavailable"
• Continue with remaining sources
• Never fail completely if at least 1 source is available
• If all sources fail, surface the error clearly

API Key Setup

As of v2.0.0, EXA / Tavily / Perplexity API keys are stored in userConfig (system keychain). plugin.json reads ${user_config.<key>}; shell env vars are no longer wired into the MCP processes. Perplexity hard-fails at startup without a valid userConfig value (tools disappear entirely); EXA and Tavily start but tool calls error at invocation.

To configure (one-time, no restart needed):

/plugin disable yellow-research
/plugin enable yellow-research

Claude Code prompts for each key. Answer the ones you want; dismiss the rest. Stored in OS keychain (or ~/.claude/.credentials.json at 0600 on minimal Linux).

Get keys from:

• EXA: https://exa.ai/
• Tavily: https://tavily.com/
• Perplexity: https://www.perplexity.ai/settings/api

The Parallel Task and Ceramic servers use OAuth (no API key needed). Claude Code handles authentication automatically — you'll be prompted to authorize on first use of each.

CERAMIC_API_KEY is the one remaining shell-env var. It is optional and powers only the /research:setup REST live-probe (the Ceramic MCP uses OAuth). Get a REST key at https://platform.ceramic.ai/keys if you want that probe to run.

# Optional, REST live-probe only
export CERAMIC_API_KEY="your-key-here"

Power users who want a fully shell-env-driven setup can wrap each MCP in a per-MCP launcher script (see plugins/yellow-morph/bin/start-morph.sh). The plugin no longer reads *_API_KEY from shell env directly.

MCP Tool Name Verification

After installing yellow-research, always verify actual tool names before writing agent code or troubleshooting:

ToolSearch keyword: "exa"
Tool name: mcp__plugin_yellow-research_exa__...

ToolSearch keyword: "tavily"
Tool name: mcp__plugin_yellow-research_tavily__...

ToolSearch keyword: "perplexity"
Tool name: mcp__plugin_yellow-research_perplexity__...

ToolSearch keyword: "parallel"
Tool name: mcp__plugin_yellow-research_parallel__...

ToolSearch keyword: "ceramic_search"
Tool name: mcp__plugin_yellow-research_ceramic__ceramic_search

ToolSearch keyword: "ast-grep__find_code"
Tool name: mcp__plugin_yellow-research_ast-grep__find_code

ToolSearch keyword: "ast-grep__find_code_by_rule"
Tool name: mcp__plugin_yellow-research_ast-grep__find_code_by_rule

ToolSearch keyword: "ast-grep__dump_syntax_tree"
Tool name: mcp__plugin_yellow-research_ast-grep__dump_syntax_tree

ToolSearch keyword: "ast-grep__test_match_code_rule"
Tool name: mcp__plugin_yellow-research_ast-grep__test_match_code_rule

Naming convention: mcp__plugin_yellow-research_<server>__<tool>.

Or run /mcp in Claude Code to see all registered tools.

Never trust LLM-generated tool names — they may be fictitious. Empirical verification is required. If names differ from what's in agents/commands, update the allowed-tools lists and any MCP tool references in agent bodies.