small-scripts/data/idle-draft/prompts/research.md

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

# 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.