progressive-research

Files (7)

• SKILL.md
• README.md · benchmarks/
• before-trusting-a-source.md · checklists/
• examples.md
• references.md
• research-log.md · templates/
• source-card.md · templates/

SKILL.md (first lines)

# Progressive research

Research is the #1 token sink in agent runs. Spend tokens on *finding* and *deciding*,
not on *holding* sources. Default to the cheapest tier that answers the question.

## Use this when
- The answer needs information you don't already have: web, docs, an unfamiliar API.
- You're tempted to read many pages or fetch large references.
- **Do NOT** use for decomposing a task (`decomposing-tasks`) or pure window mechanics
  (`context-budgeting`), this is about *acquiring external knowledge cheaply*.

## The loop

```
- [ ] 1 FRAME   write the exact question + what a sufficient answer looks like
- [ ] 2 SEARCH  one good query; collect pointers (titles+URLs), not content
- [ ] 3 TRIAGE  rank pointers by likely payoff; pick the 1-2 best
- [ ] 4 EXTRACT open only those; pull the few facts that answer the question
- [ ] 5 CORROBORATE for any load-bearing claim, confirm with a 2nd independent source
- [ ] 6 SYNTHESIZE write the answer + cite pointers; discard the raw sources
- [ ] 7 STOP     enough to answer? stop. else refine the query (max 2-3 cycles)
```

## Rules

1. **Frame before you search.** A question you can't state precisely produces searches you
   can't triage. Define "sufficient answer" first, it's your stop condition.
2. **Pointers before payloads.** A search returns titles + URLs. Keep those; open pages
   only after triage. Never read 10 results, read the 1-2 that triage picks.
3. **Breadth via the index, not the window.** Skim many candidates at the pointer level;
   only the winners pay the fetch cost.
4. **Extract, don't archive.** From each opened source, distill the specific facts and a
   pointer back. Drop the page. (See `context-budgeting` extract-then-discard.)
5. **Corroborate load-bearing claims.** Anything you'll act on (a version number, an API
   contract, a security claim) needs ≥2 independent sources, or an explicit "unverified"
   flag. Hand contested claims to `verifying-reasoning`.
6. **Prefer primary sources.** Official docs / source code / specs over blog summaries;
   note recency (the web has stale answers).
7. **Bounded cycles.** Refine the query at most 2-3 times. If still unanswered, report
   what's known, what's not, and the best next step, don't spiral.

## Cheapest-tier-first

| Tier | When it suffices | Cost |
|---|---|---|
| 0 own knowledge | stable, well-known facts | ~0 |
| 1 single search → pointers | "what/where/which" lookups | low |
| 2 open 1-2 primary sources | need exact detail/contract | medium |
| 3 sub-agent deep dive | wide survey, many sources | high, isolate it |

Escalate only when the current tier can't meet "sufficient answer."

## Sub-agent isolation (when available)

For wide surveys, delegate to a sub-agent: it reads many sources in *its* window and
returns only the synthesized conclusion + pointers. Your main window stays clean. If no
sub-agents: do the survey, then aggressively extract+discard before continuing.

## Runtime adaptation
- **Minimum:** a search tool + a fetch tool + filesystem read.
- Reference capabilities ("search the web", "fetch a URL"), never specific tool names.
- If only fetch (no search): start from a known primary doc and follow its links at the
  pointer level.

## Files
- `references.md`, source-quality heuristics, recency, query crafting.
- `examples.md`, worked research traces (cheap vs expensive).
- `templates/research-log.md`, frame → pointers → extracts → answer.
- `templates/source-card.md`, one card per opened source.
- `checklists/before-trusting-a-source.md`, corroboration gate.
- `benchmarks/`, tokens-per-answer and accuracy method.

From AdrianParedez/capability-fabric, Apache-2.0.

More from AdrianParedez/capability-fabric