| name | research-report |
| description | Convert validated deep-research JSON into a Markdown report that covers defined fields, omits uncertain claims, and renders source provenance and taxonomy coverage. Use after research-deep completes. |
Research Report
Workflow
Step 1: Locate and validate results
Find */outline.yaml, then resolve the topic, fields.yaml, and output directory. Run the installed research/validate_json.py across all result JSON files. Stop and report invalid files rather than silently generating a report from them.
Step 2: Select summary fields
Inspect valid JSON results for short fields suitable for the table of contents. Ask the user which fields to show beside each item name.
Step 3: Generate the conversion script
Create {topic}/generate_report.py. It must:
- Read every valid result JSON and
fields.yaml.
- Support flat fields and fields nested beneath category dictionaries.
- Cover all defined fields.
- Skip values containing
[uncertain], fields listed in uncertain, and empty values.
- Treat
_sources, _source_coverage, _source_file, and uncertain as reserved metadata, not Other Info.
- Collect genuine extra domain fields under
Other Info.
- Generate a table of contents and detailed item sections.
- Generate a dedicated Sources table and Source Coverage section for each item.
- Save
{topic}/report.md.
Step 4: Formatting requirements
Format complex values predictably:
- Render a list of dictionaries one record per line.
- Join short scalar lists with commas and render long lists as bullets.
- Format nested dictionaries recursively.
- Break long text into readable paragraphs or blockquotes.
Render source records as:
### Sources
| Category | Type | Title | Publication date | Credibility | Supports |
|---|---|---|---|---|---|
| Official | Official documentation | [Title](URL) | 2026-07-19 | High | technical_features.context_window |
### Source Coverage
- Official: Found — Documentation reviewed.
- Academic: Searched, no reliable source — No directly relevant paper found.
Include every category in Source Coverage. Do not promote a credibility level beyond the value recorded in the JSON.
Step 5: Execute and report
Run python {topic}/generate_report.py. Report the generated script, report path, omitted uncertain fields, and any documented source-coverage gaps.
Output
{topic}/generate_report.py{topic}/report.md
