references/report-writer.md
# Writing the report
You turn the research notes into one report that answers the question. You do
not search or read new pages. A claim that is not in the notes, with a URL,
does not go in the report.
## Read first
Read every notes file in the folder you were given. When the assignment names
an earlier report and its notes, read those too. Where they disagree with the
new notes, the new notes win. The report has to stand on its own. The reader
is not sent back to the earlier file.
Paths may contain spaces. Quote them in shell commands.
## Shape
```markdown
# {Title: about six words, with a verb, stating the finding}
{One paragraph that answers the question, then the stakes and the context the reader needs. Someone who stops here should still know the answer.}
## {Signpost heading that states a specific finding}
{Prose. **Bold** the figures and names a reader would scan for. Cite a checkable claim as ([Source](URL)).}
## {Next finding}
{Same form.}
## Conclusion
{One or two paragraphs on what the findings imply. Nothing restated from above.}
```
Use one section for each part of the question, and give each named entity,
region or mechanism its own subsection with its figures.
## Headings
Sentence case. A reader who reads only the headings should get the argument.
Put the specific result in the heading.
| Writes the finding | Names the topic |
|---|---|
| Migratory geese forage 370 extra hours a year | Effects of climate on geese |
| Usage pricing costs more past 50 seats | Pricing |
## Prose
Use a table when several items share the same fields. Each section adds a step
in the argument.
Cite the claims a reader would want to check: figures, dates, and attributed
positions. Use `([Source](URL))` inline. Skip a finding whose note has no URL.
When the notes disagree, say so in the paragraph and say which source you take
and why. State what nobody confirmed. Take a position the evidence supports,
and say what is still open without filling it with "may" or "possibly".
The conclusion is the implication. It is not a summary of the sections.
references/researcher.md
# Researching one subtopic
You cover only the subtopic you were given. Other work is covering the rest.
Your notes are the only material the report writer gets. It will not search
again, so every finding the report might use has to be in the file, with its
URL.
## Before you search
Use `tavily-search` for every search and page read. If it isn't installed, run
`npx skills add tavily-ai/skills --skill tavily-search` and read its SKILL.md
before continuing. Follow that skill for how to write a query, when to extract
a page, and when to save large results and filter them. Do that before the
first search.
## How to gather
1. Name the gaps that stand between you and the key questions.
2. Search for those gaps. Run independent searches in parallel.
3. Extract the pages you expect to cite. A snippet is a lead. A number, a date,
or a quote needs the page.
4. Repeat until a stop condition below is met.
Prefer the authoritative source, and cite that page. That is the institution
in a position to know: the company's own site, the paper, the filing, the
dataset, the official docs, a government or regulator, or a standards body.
Use another source when it adds a fact the authoritative page does not, and
say which is which.
When a page is long, or you are opening several at once, save the response and
filter it the way `tavily-search` describes, and write the notes from that
result. Keep the URL next to the fact.
Search again with different words when a query is thin. Repeating the same
query returns the same pages. For a recent topic, trust what you just
retrieved over your training data.
A subtopic usually takes about eight searches and extracts. Stop by twelve.
## When to stop
- The key questions have sourced answers.
- New searches return pages you already have.
- You are approaching twelve calls.
## What may go in the notes
Write a finding only when you can point at the page it came from. When several
pages support the same fact, cite the authoritative page. Cite a news story,
blog, or aggregator only when that page does not state the fact. When two
sources disagree, record both, authoritative first, and the disagreement.
When you cannot find a reliable source, write that as a gap. A gap is a useful
result.
Leave out a claim that is only a prediction, an unnamed source, or a number
that appears on aggregators and nowhere else, unless you label it that way in
the finding.
## Notes file
Save the file at the path in your assignment. The parent folder exists. Use
these sections, and no other top-level sections:
```markdown
# {Subtopic}
## {Key question}
### Takeaway
{One or two sentences.}
### Cited findings
- {Fact} — [Authoritative source](URL)
- {Fact only another source has} — [Secondary source](URL)
- {Fact} — [Authoritative source](URL); contradicted by [Other source](URL)
### Inferences
- {What the findings support, beyond what any one page states.}
### Gaps
- {What you could not answer, and what you tried.}
```
Repeat the key-question section for each question you were given. Every bullet
under Cited findings has a URL, and that URL is the authoritative page when
one exists. A fact with no URL goes under Gaps instead.
SKILL.md
---
name: tavily-research
description: |
Research a topic in depth with Tavily. Use this skill when a question needs many sources gathered and weighed together: analysing a market, policy, technology or trend, comparing options across several criteria, reviewing the literature, or any request to research, investigate or analyze something in depth. A single fact or answer to find, even one with many clues, is a tavily-search task. For one CRM record use tavily-entity, for a table of matches use tavily-list, and for a recurring check use tavily-monitor.
allowed-tools: Bash(tvly *)
---
# Tavily research
Use this when the answer has to be built from many sources. A single fact or
answer to find is a search: follow `tavily-search` instead.
Search and read pages as `tavily-search` describes. Load it only if it isn't
loaded yet.
## Steps
### 1. Ask only when the answer would change the research
Ask when a term has two meanings, the user assumed a place, or a name is two
different entities. Otherwise start.
### 2. Split the question
Split into subtopics that do not overlap and that together cover the question.
Carry the user's limits with every subtopic: dates, places, and what is out of
scope. Use 3 subtopics when you are unsure, 4 for a comparison with separate
criteria, 5 for separate entities, regions or domains, and more only for a
large set.
### 3. Research the subtopics together
**With subagents:** choose a title of 3 to 6 words, create
`research_notes/{title}/` and `reports/` in the working directory, and start
one general-purpose subagent per subtopic in the same turn. Give each the
subtopic, the key questions, the user's limits, the absolute path of its notes
file, and this first step: read `references/researcher.md` at its absolute path
next to this skill.
**On your own:** run each subtopic's searches in parallel, as `tavily-search`
describes, and extract the main sources for each. Keep the findings and their
URLs in your context. Don't write notes files.
### 4. Fill thin parts, then write
Before writing, run another round for any part of the question that would
leave its section thin.
### 5. Write and deliver the answer
Follow `references/report-writer.md`. On your own, write it once, as
your reply. Save it to `reports/{title}.md` only when the user asked for a
file, and then give the path after the report. With subagents, have one agent
write `reports/{title}.md` from the notes, then give the user the full report
in your reply, followed by its path.
If this conversation already produced a report on the subject, build on it:
research only what is new or needs checking again.