research

Files (1)

• SKILL.md

SKILL.md (first lines)

# Research

Use this skill when the user asks to research a technical question, compare
libraries or approaches, investigate external APIs, or gather 2+ sources before
making an implementation decision.

Do not use this skill for a single library-doc lookup, a codebase-only question,
or a simple fact that can be answered directly.

## Context Discipline

Run the orchestration inline, but keep raw evidence out of the main context:

1. Route sources once and state the committed routing decision.
2. Spawn fetchers in parallel where the harness supports it.
3. Have fetchers write findings to scratch files under `$TMPDIR`.
4. Have one synthesis sub-agent read those scratch files and return the final
   answer.
5. Write the full report to `.cheese/research/<slugified-topic>.md`.
6. Delete the scratch directory after the report is written.

The caller should see only the routing decision, fetcher status, synthesis,
and the report path.

## Arguments

The entire request body is the research question. The skill always writes a
full report; the caller does not pass an output path.

Create a run directory:

```bash
RUN_ID="$(date +%Y%m%d-%H%M%S)-<slug>"
RUN_DIR="${TMPDIR:-/tmp}/cheese-flow-research-${RUN_ID}"
mkdir -p "$RUN_DIR"
```

Use a 4-6 word kebab-case slug derived from the topic.

## Phase 1: Classify

Identify:

- Primary topic
- Question type: factual lookup, how-to, comparison, pattern search, API usage
- Complexity: simple fact, focused question, comparison, or deep analysis
- Constraints: version, language, framework, performance, license, architecture

## Phase 2: Route Sources

Decide once. If a source is committed here, it must be executed in Phase 3.

```text
Is it about a specific library API, config, or migration?
  YES -> Context7, plus GitHub if real-world usage matters

Is it a factual, current, vendor, product, or "what/who/when" question?
  YES -> Tavily basic search

Is it a "how should I..." or best-practices question?
  YES -> Tavily advanced search, plus Context7 when a named library is involved

Is it about patterns in this repo?
  YES -> Codebase fetcher

Is it about how open-source projects solve something?
  YES -> GitHub fetcher, plus Tavily if written analysis would help
```

Source guide:

| Source | Best For | Notes |
| --- | --- | --- |
| Context7 | Library APIs, config, migration notes | Prefer over general web for named dependencies. |
| Tavily | Current facts, technical articles, vendor docs, best practices | Use basic for factual lookups, advanced for analysis. |
| Codebase | Local conventions, existing usage, constraints | Use repository search and reads. |
| GitHub | Real-world OSS usage patterns | Use `gh` or the harness GitHub integration. |

Emit a compact routing block:

```text
ROUTING DECISION:
- Context7: YES (library: "<library>", query: "<focused question>")
- Tavily: YES (query: "<natural-language question>", depth: basic|advanced)
- Codebase: NO (external-only question)
- GitHub: NO (not looking for OSS usage patterns)
```

## Phase 3: Execute Fetchers

Hard rule: if a source was committed in Phase 2, spawn it in Phase 3. Do not
silently skip a routed source because it seems low value later.

Every fetcher must:

1. Use only its assigned source tools.
2. Write findings to `<RUN_DIR>/<source>.md`.
3. Return exactly one status line:
   - `done: <RUN_DIR>/<source>.md`
   - `unavailable: <one-line reason>`

Scratch file schema:

```markdown
# <source> - <topic>
_Confidence: <0-100>_  _Status: <ok|unavailable>_

## Direct Answer
<1-2 sentences>

## Evidence
<quotes, snippets, key facts, or code references>

## Sources
- <URLs, file refs, library IDs, repo links>
```

### Context7 Fetcher

Use Context7 for library documentation. Resolve the library first, then query

From paulnsorensen/cheese-flow, MIT.

More from paulnsorensen/cheese-flow