75add58246
Research and topic_ideas runs get --allowedTools WebSearch,WebFetch; research template mandates >=1 web search for related stories with full-URL + access-date citations under the dossier's status labels. Claude-Session: https://claude.ai/code/session_01YQDoWNM7XPPii28khFWoMc
117 lines
5.8 KiB
Markdown
117 lines
5.8 KiB
Markdown
You are producing the **research file** for one topic in an O'Reilly Consulting
|
|
writing dossier. This is unattended, headless work — there is no human in the loop
|
|
until a reviewer samples your output later. Follow this brief exactly.
|
|
|
|
## Item
|
|
|
|
- Dossier: `$dossier`
|
|
- Topic: `$slug`
|
|
- Topic brief (read first, in full): $overview_path
|
|
- Commissioning brief (read second, in full): $agent_path
|
|
- Dossier commissioning guide (dossier-specific rules): $dossier_agents_path
|
|
- Project-root voice and citation rules (read before writing a single line): $agents_root_path
|
|
- Source register (existing sources for this dossier — read before searching for new
|
|
ones; do not duplicate a source it already lists): $source_register_path
|
|
|
|
Evidence you may cite must live under one of these directories (you have read access
|
|
via `--add-dir`; do not invent paths outside them):
|
|
|
|
$evidence_dirs
|
|
|
|
## What to produce
|
|
|
|
Write a Markdown research file with two kinds of content, matching what the topic
|
|
brief's evidence section and the commissioning brief already point at, extended with
|
|
anything new and relevant you find under the evidence directories above:
|
|
|
|
1. **Objective evidence** — concrete examples, code references (file path + line range,
|
|
not just "the script does X"), measurables, named findings. Every claim is sourced.
|
|
2. **Subjective stories** — case-study-like narratives that make the evidence concrete
|
|
for a reader (a scene, a named organisation's experience, a practitioner's account)
|
|
— still sourced, but framed as narrative rather than a bare statistic.
|
|
|
|
## Required: web search for current stories (before writing Subjective stories)
|
|
|
|
You have `WebSearch` and `WebFetch` available. Before writing the **Subjective
|
|
stories** section, run **at least one `WebSearch`** for recent stories, case
|
|
studies, or practitioner accounts directly related to this topic — derive your
|
|
query terms from the topic brief (`$overview_path`) and commissioning brief
|
|
(`$agent_path`), not from the dossier title alone. This is not optional and not
|
|
decorative: a research file with zero web search calls and zero web-sourced
|
|
entries is incomplete.
|
|
|
|
- Web-sourced entries go in Subjective stories (or Objective evidence, if the
|
|
find is a concrete measurable rather than a narrative) alongside the local
|
|
evidence-dir findings — web search **complements** the local evidence dirs,
|
|
it never replaces them. Local evidence-dir citation rules above are
|
|
unchanged.
|
|
- Cite the **full URL** and the **access date** (today's date) for every
|
|
web-sourced entry, e.g. `https://example.com/post (accessed 2026-08-02)`.
|
|
- Apply the dossier's status-label family correctly to web sources: a company
|
|
engineering-blog post is "Named organisation, self-reported"; vendor
|
|
marketing or a vendor's own benchmark is "Vendor data, treat with caution";
|
|
an industry survey is "Research-survey finding"; use "GOES synthesis / bet"
|
|
only for your own synthesis, never for a source you found.
|
|
- **Only cite a URL actually returned by `WebSearch` or fetched via
|
|
`WebFetch`.** Never construct, guess, or paraphrase a plausible-looking URL.
|
|
A fabricated URL is grounds for outright rejection at human sampling —
|
|
treat it as equivalent to citing a dead file path.
|
|
|
|
## Citation rules (non-negotiable — read `$agents_root_path` for the full statement)
|
|
|
|
- **Cite the file, not the concept.** Any code or spec reference must name the file
|
|
path and the line range: `path/to/file.py:120-145`, not "the script does X."
|
|
- **Cite the requirement ID where one exists** (e.g. `H-*`, `AU-*`, `WT-*`, `KX-*`,
|
|
`BRK-*`, `WF-*` prefixes in the agent-runtimes spec) — quote the ID, not a prose
|
|
paraphrase.
|
|
- **Quote metric markers verbatim** where GOES research uses them (`{p.3}`, `{s.4}`,
|
|
`{t.00:14:32}`) — do not renumber or invent markers.
|
|
- Use the dossier's status-label family and apply it correctly:
|
|
- `ai` / `ai-technical` dossiers use **implementation maturity**: "Implemented and
|
|
running in production" / "Designed and specified, implementation in progress" /
|
|
"Spec-only / future." A claim about an `implemented` feature may report a deployed
|
|
behaviour or measured metric; a `spec-only` claim may not.
|
|
- `devops-2020` / `devops-2020-technical` dossiers use **evidence quality**: "Named
|
|
organisation, self-reported" / "Research-survey finding" / "GOES synthesis / bet" /
|
|
"Vendor data, treat with caution." Label every cited source with the correct one.
|
|
- Every source you cite gets an explicit status label. Do not present an unlabelled
|
|
claim as settled fact.
|
|
|
|
## Required structure
|
|
|
|
```markdown
|
|
# Research: <topic title, sentence case>
|
|
|
|
## Objective evidence
|
|
|
|
<bulleted or short-paragraph entries, each with file/line or source citation and
|
|
status label>
|
|
|
|
## Subjective stories
|
|
|
|
<narrative entries, each still sourced and status-labelled>
|
|
|
|
## Register delta
|
|
|
|
<a bulleted list of every source used in this file that `$source_register_path` does
|
|
NOT already list — path, one-line description, proposed status label. If every source
|
|
you used is already in the register, write "None — all sources already registered."
|
|
This section is the only place new sources are proposed; you do not edit the register
|
|
file itself.>
|
|
```
|
|
|
|
All headings are **sentence case** ("Objective evidence," not "Objective Evidence").
|
|
|
|
## Output
|
|
|
|
Write the complete Markdown file to exactly this path, and nothing else — do not touch
|
|
any other file in the repository, do not edit the source register, do not create the
|
|
canonical `$slug.research.md` file yourself:
|
|
|
|
$output_path
|
|
|
|
The dispatcher validates this file (non-empty, starts with a top-level heading, every
|
|
absolute `/home/...` path you cite resolves on disk) and promotes it to its canonical
|
|
location itself. If any cited absolute path does not exist, your output will be
|
|
rejected — verify paths before citing them, don't guess.
|