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.

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.