research-report

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