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.mdskills/research/SKILL.md
GitHubResearch 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
- Write output to file, never dump inline — Research output floods conversation and loses reference for future sessions
- Stop after research — never auto-transition — User decides next step
- Prefer official sources over blog posts — developers.home-assistant.io, home-assistant.io, and PyPI project pages have version-specific context
- One document per research question — No fragmented files
- 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"):
- Read
${CLAUDE_SKILL_DIR}/references/library-evaluation.mdfor the template - Follow the structured evaluation workflow (including the P11 dependency-transparency gate: CI-published, tagged releases, no pre-releases)
- Output ONE document to
.claude/research/{lib}-evaluation.md - 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
- {recommendation with evidence}
- {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.**