cf:research · diff
v2.0.0 to v3.0.0
68 added, 41 removed. Audit A to A.
---
name: hapo:research
- description: "Research technical solutions and analyze architectures. Acts as a command facade to trigger the 'researcher' subagent for multi-source verification and deep report synthesis."
+ description: "Research technical decisions with proportional depth, traceable evidence, explicit uncertainty, and project-fit recommendations."
user-invocable: true
- when_to_use: "Invoke for deep technical research and solution evaluation before building."
+ when_to_use: "Use for external technical facts, architecture comparisons, or decisions whose uncertainty needs multi-source evidence."
category: research
- keywords: [research, evaluation, analysis, solutions]
- argument-hint: "<topic_or_question>"
+ keywords: [research, evidence, evaluation, architecture, comparison]
+ argument-hint: "<topic_or_decision>"
metadata:
author: haposoft
- version: "2.0.0"
+ version: "3.0.0"
---
- # Research (Delegation Facade)
+ # Research — proportional evidence for a decision
- **Mantra:** Return ranked recommendations with sources; never an unsorted list of options.
+ Return a decision-ready answer, not a search diary or an unsorted option list.
+ Research evaluates choices; it does not implement them or invent certainty.
- This skill acts as a **Command Facade**. When invoked, the main Orchestrator MUST NOT attempt to run WebSearch itself. Instead, it must instantly delegate the operation to the Specialized Subagent.
+ ## 1. Frame the decision
- ## Execution Sequence
+ Restate the decision, project constraints, affected consumers, and what evidence
+ would change the answer. Inspect current repository sources first whenever local
+ fit matters. Ask the user only when a missing choice materially changes scope or
+ safety; otherwise label bounded assumptions and continue.
- ### Phase 1: Clarification (Scope Lock)
- Before delegating, briefly assess the `[topic]`.
- - Is it vague? (e.g. "Research React"). If yes, immediately reject and demand the user specify the context (e.g. "Research SEO capabilities of React Server Components").
- - If solid, proceed.
+ ## 2. Select depth
- ### Phase 2: Agent Delegation
- Call the `Agent` tool to invoke the `researcher` subagent. Use `TaskCreate` only for task-list tracking when the workflow needs persistent task state.
- **Instructions to pass to Researcher:**
- ```text
- Conduct comprehensive research on: [topic]
- Constraint 1: ALWAYS use native `WebSearch` as the primary search method.
- Constraint 2: Validate key claims with multiple credible sources. Prioritize official docs, maintainers, release notes, and strong production references.
- Constraint 3: Use direct `WebFetch` only when search results are insufficient or raw source inspection is required.
- Constraint 4: Limit total search calls to a maximum of 5 distinct queries.
- Constraint 5: Stop excessive "chain-searching". Synthesize decisively once the evidence is sufficient.
- Output Format: Must strictly follow the 'Standard Research Report' layout.
- ```
+ Choose the smallest depth that can support the decision:
- ### Phase 3: The Standard Report Format (Mandatory)
- The subagent MUST return the findings formatted EXACTLY according to the built-in specification template.
+ | Depth | Route when | Evidence work |
+ |---|---|---|
+ | Quick | One low-risk, reversible fact or known option | Resolve the fact from one authoritative source; add a repository anchor when project fit matters. |
+ | Standard | Several viable options or a material integration choice | Verify material claims across at least two independent authoritative sources where available; compare fit and tradeoffs. |
+ | Deep | High blast radius, hard-to-reverse architecture, security/compliance, substantial cost, or conflicting evidence | Complete Standard, then run a separate contradiction-and-gap round; use at least three independent sources for disputed material claims where available. |
- Instruct the Researcher Subagent with this strict requirement:
- > "Use the template at .claude/skills/specs/templates/research.md verbatim. Do not add sections beyond it."
+ Escalate depth when evidence conflicts, a primary source is missing, or a finding
+ changes the decision boundary. Do not inflate source counts with mirrors or
+ articles that repeat the same upstream claim. Stop when new evidence no longer
+ changes the ranking, limitations, or unresolved gaps.
- ## Post-Execution
- Once the `researcher` completes the Task and returns the Markdown output, save it based on context:
+ ## 3. Gather evidence
- ### Output Routing
- | Context | Save to | Example |
- |---|---|---|
- | Active spec exists (`specs/<feature>/`) | `specs/<feature>/research.md` | `specs/auth-login/research.md` |
- | No active spec (system-wide / general) | `specs/_shared/Research-<slug>-<date>.md` | `specs/_shared/Research-mv3-best-practices-2026-04-11.md` |
+ - Repository claims: cite a resolvable `path:line` anchor from current bytes.
+ - External claims: prefer current official documentation, standards, research
+ papers, maintainer material, and release notes. Browse when facts may have
+ changed; record the source date or applicable version.
+ - For each material claim record: claim, URL or repository anchor, authority,
+ date/version, applicability to this project, and status
+ `confirmed | inferred | unresolved`.
+ - A source count is not confidence. Explain conflicts, missing primary evidence,
+ version mismatch, and why a source does or does not apply.
- ### Rules
- 1. **Feature research** → Always save inside the active spec folder. If `specs/<feature>/` doesn't exist yet, create it.
- 2. **System-wide research** → Save to `specs/_shared/`. Create the directory if it doesn't exist.
- 3. **Never** save to `plans/reports/` or `docs/`. All research belongs in `specs/`.
- 4. Conclude the workflow by providing the user with the saved file path.
+ Use delegated researchers only as optional acceleration when two or more
+ independent evidence tracks can be bounded. The controller owns the question,
+ source reconciliation, and final recommendation. If delegation is unavailable,
+ unauthorized, or not useful, research sequentially with the same evidence bar.
+
+ ## 4. Synthesize
+
+ For comparisons, rank only viable options and name a winner when evidence and
+ project fit support one. For every ranked option include fit, decisive evidence,
+ tradeoffs, adoption/operational risks, and limitations. If evidence cannot choose
+ a winner, return `unresolved` plus the smallest fact or experiment that would.
+
+ Use the four mandatory H2 sections from
+ `.claude/skills/specs/templates/research.md`. Keep claim records and comparisons
+ inside `## Evidence Summary`; do not add or reorder mandatory H2 headings.
+
+ ## 5. Output and persistence
+
+ Default to a concise answer in chat. Persist only when:
+
+ 1. one explicitly resolved active Spec requires durable `research.md`; save to
+ that exact `specs/<feature>/research.md`, preserving its existing lifecycle; or
+ 2. the user explicitly requests a durable report and approves its destination.
+
+ Do not create a Spec or `_shared` archive merely to save an answer. The
+ controller performs any authorized write after reviewing and redacting the
+ output; delegated researchers never write reports or task state. Always state
+ depth used, decisive evidence, recommendation, limitations, and unresolved gaps.
+
+ ## Handoff boundary
+
+ Research may recommend Brainstorm or Specs when a material product/design choice
+ remains. It never starts Develop, edits implementation code, claims user approval,
+ or presents source/installed evidence as live-system proof.