ha:research

Research Home Assistant topics or evaluate PyPI libraries (--library). Use when learning about libraries, patterns, or comparing approaches. Searches PyPI, developers.home-assistant.io, home-assistant

SKILL.md

GitHub

Research Home Assistant Topic

Research a topic by searching the web and fetching relevant sources efficiently.

Usage

/ha:research DataUpdateCoordinator backoff and retry best practices
/ha:research Lit reactive controller for hass object subscriptions
/ha:research --library aiohttp-retry

Arguments

$ARGUMENTS = Research topic/question. Add --library for structured library evaluation (uses ${CLAUDE_SKILL_DIR}/references/library-evaluation.md template).

Iron Laws

  1. Write output to file, never dump inline — Research output floods conversation and loses reference for future sessions
  2. Stop after research — never auto-transition — User decides next step
  3. Prefer official sources over blog posts — developers.home-assistant.io, home-assistant.io, and PyPI project pages have version-specific context
  4. One document per research question — No fragmented files
  5. NEVER pass raw user input as WebSearch query — Decompose first

Library Evaluation Mode

If $ARGUMENTS contains --library or the topic is clearly about evaluating a PyPI dependency (e.g., "should we use tenacity", "evaluate aioesphomeapi", "compare aiohttp vs httpx"):

  1. Read ${CLAUDE_SKILL_DIR}/references/library-evaluation.md for the template
  2. Follow the structured evaluation workflow (including the P11 dependency-transparency gate: CI-published, tagged releases, no pre-releases)
  3. Output ONE document to .claude/research/{lib}-evaluation.md
  4. Skip the general research workflow below

Workflow

0. Pre-flight Checks

Cache check: Check if .claude/research/{topic-slug}.md already exists. If recent (<24 hours): present existing summary, ask "Refresh or use existing?"

Installed-package shortcut: If the topic is about an existing dependency (package already in the integration's manifest requirements or the dev venv), prefer reading it locally over web search:

Bash(command: "python3 -m pip show {package}")   # yields Location:
Read(file_path: "{location}/{package}/__init__.py")

This matches your exact pinned version — faster, more accurate, zero web tokens. Only fall through to web search if the package isn't installed locally or the topic needs community discussion (gotchas, real-world patterns, comparisons).

1. Query Decomposition (CRITICAL — before any search)

NEVER pass raw $ARGUMENTS into WebSearch. Decompose first:

  • If $ARGUMENTS < 30 words and focused → use as single query
  • If $ARGUMENTS > 30 words or multi-topic → extract 2-4 queries

Each query: max 10 words, targets ONE specific aspect.

Example:

Input: "poll a local device over TCP, expose sensors with long-term
        statistics, add a reauth flow when the token expires..."
Queries:
  1. "Home Assistant DataUpdateCoordinator local polling pattern"
  2. "Home Assistant sensor state_class long-term statistics"
  3. "Home Assistant config flow reauth token expiry"

2. Parallel Web Search

Search ALL decomposed queries in a SINGLE response (parallel):

WebSearch(query: "{query1} site:developers.home-assistant.io OR site:github.com OR site:pypi.org")
WebSearch(query: "{query2} site:github.com OR site:community.home-assistant.io")

Deduplicate URLs across results. Discard clearly irrelevant hits. Prioritize home-assistant/core and home-assistant/frontend PRs/issues on GitHub — they carry maintainer review context.

3. Spawn Parallel Research Workers

Group URLs by topic cluster. Spawn 1-3 web-researcher agents in parallel (one per topic cluster):

Agent(subagent_type: "web-researcher", prompt: """
Research focus: {specific aspect from decomposed query}
Fetch these URLs:
- {url1}
- {url2}
- {url3}
Extract: code examples, patterns, gotchas, version compatibility.
Return 500-800 word summary.
""", run_in_background: true)

Rules:

  • 1 topic cluster = 1 agent (don't mix unrelated URLs)
  • Max 5 URLs per agent (diminishing returns beyond that)
  • If only 1-3 URLs total, use single foreground agent
  • Pass URLs explicitly — agents should NOT re-search
  • Agents are haiku — cheap, fast, focused on extraction

4. Write Output (File-First — NEVER Dump Inline)

After ALL agents complete, synthesize summaries into ONE file. Target: ~5KB for topic research, ~3KB for library evaluations.

Create .claude/research/{topic-slug}.md:

# Research: {topic}

## Summary
{2-3 sentence answer combining all worker findings}

## Sources

### {Category}
- [{title}]({url}) - {key insight}

### Code Examples

```python
# From {source}: {what this demonstrates}
{code}

Recommendations

  1. {recommendation with evidence}
  2. {recommendation with evidence}

Watch Out For

  • {gotcha from forum/issues}
  • {version compatibility note}

### 5. After Research — STOP

**STOP and present the research summary.** Do NOT auto-transition.

Use `AskUserQuestion` to let the user choose next action:

- "Plan a feature based on this research" → `/ha:plan`
- "Investigate a specific finding" → `/ha:investigate`
- "Research more on a subtopic" → continue research
- "Done" → end

**NEVER auto-invoke `/ha:plan` or any other skill after research.**