/research

name: research
description: "Use when research files (web or GitHub findings) are available and must be synthesized into a recommendation. Synthesis guidance only; it does not execute research."
allowed-tools: Read
user-invocable: false

Research Synthesis Guidance

Overview

This skill is loaded via SKILL_HINTS by `cc10x:planner` and `cc10x:bug-investigator` when the router passes research files in the prompt. It provides instructions for synthesizing web and GitHub research findings.

**This skill does NOT execute research.** Research execution is done by:

• `cc10x:researcher (web mode)` — prefers Bright Data, falls back to WebSearch/WebFetch
• `cc10x:researcher (github mode)` — prefers Octocode MCP, falls back to package/docs/GitHub web research

Synthesis Goal

After the router passes research file paths in your prompt, read the available files and produce a synthesis that: 1. Answers the knowledge gap (the `Reason` field from your prompt) 2. Identifies the top 2-3 actionable patterns 3. Lists gotchas with solutions 4. Provides specific references for debugging 5. Reflects evidence quality honestly 6. States the single finding that most changed the recommendation

What Makes Good Synthesis

**Include:**

• Cross-source confirmation (when web + GitHub agree on a pattern, it's reliable)
• Primary-source preference: prefer the source that owns the claim — spec, first-party docs, shipped code. A secondary write-up citing a primary loses to the primary.
• Conflict resolution: when sources disagree, code-backed, cross-confirmed findings override single-source prose; shipped code overrides docs (docs describe intent; code is what runs). Partial matches (one strong source only) require adaptation — state the adaptation rationale explicitly.
• Confidence calibration from the router-provided `## Research Quality` block
• Gotchas the user probably hasn't considered
• Specific code snippets only when they materially change the recommendation

**Exclude:**

• Raw dump of all findings (summarize)
• Obvious things the AI already knows
• Findings not relevant to the specific `Reason` for research

Same-Name Disambiguation

A name (package, repo, handle) is not a unique key. Researchers routinely retrieve content where one name collides across distinct entities — two npm packages publish under the same name, the same handle exists on two platforms run by different people, a repo name is forked or squatted under multiple owners. This is retrieval noise, not a source conflict.

Once the **canonical entity is resolved** — the one the project actually depends on, the owner/scope it ships under, the platform that matches the project's context — treat that resolution as authoritative:

• **Lead with the canonical entity.** Synthesis answers for the resolved package/repo/handle, not for the name in the abstract.
• **Actively reject off-target same-name matches.** Do not average them into the synthesis, do not merge their findings, do not hedge between them. A finding about the wrong `left-pad` is wrong, not low-confidence.
• **Resolve by anchor, not popularity.** Pin to the version/scope in the project's manifest (`package.json` dependency name + version), the `owner/repo` the lockfile or import path points at, the platform the handle is referenced from. The most-starred or most-trafficked same-name hit is often not the project's.
• **Surface the collision when it changed the answer.** If a researcher clearly retrieved the wrong entity, say so in one line (e.g. "GitHub findings were for `acme/foo`, but the project depends on `@acme-internal/foo` — discarded") rather than silently dropping them. This is distinct from a genuine source disagreement, which still follows the conflict-resolution rules above.

Synthesis Format

## Evidence Quality
- Web: [high / medium / low / none]
- GitHub: [high / medium / low / none]
- Overall confidence: [high / medium / low]

## Web Findings
[3-5 bullets from web research. Focus on patterns and gotchas.]

## GitHub Findings
[3-5 bullets from GitHub. Focus on real implementation patterns.]

## Synthesis

**Knowledge Gap answered:** [One sentence: what we now know that we didn't before]

**Recommended approach:** [1-3 sentences: what to do]

**What changed the recommendation most:** [single sentence]

**Top patterns to apply:**
1. [Specific, actionable pattern]
2. [Specific, actionable pattern]

**Gotchas to avoid:**
- [Gotcha]: [Solution]

**References for debugging:**
- [URL or GitHub repo path]

Handling Partial Research

If GitHub researcher returned `[GitHub phase unavailable]`:

• Note it in the synthesis header: "GitHub research unavailable — Web only"
• Use web findings only for synthesis

If BOTH unavailable:

• State clearly: "Research unavailable — all sources down. Proceeding with AI knowledge only."
• Lower confidence and rely on repo-local evidence first.

Quality weighting:

• `high`: multiple concrete sources or code-backed findings
• `medium`: one strong source or partial cross-confirmation
• `low`: indirect, sparse, or web-only/package-only signals
• `none`: no usable external findings

Memory Output

Do not edit `.cc10x/*.md` directly from this skill or from the host agent. `allowed-tools: Read` in this skill's frontmatter pre-approves Read; it does not restrict other tools, so this rule is an instruction to the host agent, not a tool restriction.

Instead, surface the most durable takeaway through the host agent's `MEMORY_NOTES`, for example:

• one research-backed gotcha worth preserving
• one reference path worth indexing
• one confidence caveat if research quality was degraded