research-output

name	research-output
description	Create organized, copyright-safe research artifacts under output/research/. Always applies to evidence, guideline, citation, article, source-review, or literature turns.

Research output

When to use this

Use this whenever the turn involves research, evidence, guidelines, literature, articles, source review, citations, clinical thresholds, or instrument provenance.

How to do it

Required output structure

The host has already created:

$FORMTASTIC_RUN_DIR/output/research/
  README.md
  materials/
  sources/
  searches/
  notes/
  extracts/

For research turns, populate it consistently:

1. Write $FORMTASTIC_RUN_DIR/output/research/bundle.json.
2. Write one search transcript per meaningful query under $FORMTASTIC_RUN_DIR/output/research/searches/.
3. Write one source note per selected source under $FORMTASTIC_RUN_DIR/output/research/sources/.
4. Persist lawfully available source materials under $FORMTASTIC_RUN_DIR/output/research/materials/<source-id>/ when they are needed for auditability (for example, open-access PDFs, PubMed XML/metadata, HTML snapshots of guideline pages, or text/JSON metadata exports).
5. Write extraction notes under $FORMTASTIC_RUN_DIR/output/research/extracts/ when a source supports specific questions, thresholds, answer choices, or recommendations.
6. Write synthesis notes under $FORMTASTIC_RUN_DIR/output/research/notes/ when the bundle contains cross-source conclusions.
7. Write $FORMTASTIC_RUN_DIR/output/findings.json as the compact UI-facing summary derived from the bundle.

bundle.json shape

Use stable ids and relative file references:

{
  "topic": "Headache red-flag triage",
  "question": "What evidence supports migraine intake red flags?",
  "searchedAt": "2026-05-06T00:00:00.000Z",
  "searches": [
    {
      "id": "search-guidelines-1",
      "provider": "NICE",
      "query": "headache red flags migraine NICE CG150",
      "url": "https://www.nice.org.uk/guidance/cg150",
      "selectedSourceIds": ["nice-cg150"],
      "transcriptFile": "searches/search-guidelines-1.md"
    }
  ],
  "sources": [
    {
      "id": "nice-cg150",
      "kind": "guideline",
      "title": "NICE CG150 Headaches in over 12s",
      "url": "https://www.nice.org.uk/guidance/cg150",
      "publisher": "NICE",
      "year": 2012,
      "accessedAt": "2026-05-06T00:00:00.000Z",
      "relevance": "Supports urgent headache assessment red flags.",
      "sourceFile": "sources/nice-cg150.md",
      "extractFile": "extracts/nice-cg150-red-flags.md",
      "materials": [
        {
          "kind": "html",
          "path": "materials/nice-cg150/guidance.html",
          "url": "https://www.nice.org.uk/guidance/cg150",
          "contentType": "text/html",
          "note": "Locally saved guideline page snapshot for audit."
        }
      ]
    }
  ],
  "notes": [
    {
      "heading": "Red-flag triage",
      "text": "Thunderclap onset, neurologic deficit, cancer/immunosuppression, fever, and acute glaucoma symptoms are actionable triage contexts.",
      "sourceIds": ["nice-cg150"],
      "noteFile": "notes/red-flag-triage.md"
    }
  ],
  "limitations": []
}

Supporting file expectations

• searches/*.md: query string, date/access time, provider/site, filters, top candidate ids/titles, selected ids, rejected ids when important, and why. Include selected source ids and any DOI, PMID, PubMed URL, guideline URL, or canonical identifier in plain text so the search trail is recoverable with grep.
• sources/*.md: self-contained citation metadata, source id, title, citation string, DOI, PMID, PubMed URL, canonical/full-text URL, abstract or short metadata summary when available, local material references, and your paraphrased relevance note. Do not write "see bundle.json" placeholders; the file must remain useful on its own.
• materials/<source-id>/...: source materials that are lawful to persist for audit/replay. Prefer durable filenames such as article.pdf, pubmed.xml, guideline.html, metadata.json, or landing-page.html. For every local material, record the relative path, original URL, DOI/PMID/canonical id when known, content type, and checksum when practical in bundle.json under the matching source's materials[]. If the full text is not open or should not be copied, do not store it locally; instead store a materials[] record with the DOI/PMID/URL and explain the limitation in the source note.
• Each selected source needs an explicit material disposition in both bundle.json and sources/*.md:
  • local-open-material: a lawful local source snapshot exists and materials[].path points to it.
  • metadata-only: no full source snapshot is saved, but DOI/PMID/URL and metadata are enough to re-find the source.
  • not-available: no lawful local source material or metadata snapshot could be saved; record the durable locator and the limitation.
• extracts/*.md: short paraphrased extraction tied to form design decisions; include source id, local material filenames when used, plus DOI/PMID/URL identifiers in plain text, and do not copy full article/guideline text.
• notes/*.md: cross-source synthesis and limitations.

Validation

Before the visible reply claims research is ready, validate:

curl -sS -X POST "$FORMTASTIC_OUTPUT_VALIDATOR_URL?kind=research-bundle" \
  -H 'content-type: application/json' \
  --data-binary @"$FORMTASTIC_RUN_DIR/output/research/bundle.json"

If validation fails, fix bundle.json first.

Pitfalls

• Store metadata, abstracts/snippets where available, and your own concise extraction notes.
• Persist full PDFs/HTML only when they are openly/lawfully retrievable for this workflow. Do not bypass paywalls, DRM, authentication, or terms of use.
• Do not paste copied full article text or large chunks of copyrighted guidelines into Markdown notes; reference a lawful local material path or DOI/ PMID/URL instead.
• Do not hallucinate identifiers; only cite source ids you actually found or that are already present in the form/library context.