Research Format Skill

Composes the canonical Markdown report for claimpipelinev1.

This skill is a report composer, not a researcher and not a publisher. It writes output/report.md from compact structured research state. HTML, PDF, and QMD outputs are generated later by the publishing phase from output/report.md.

Required Inputs

When invoked by research, use only:

The formatter must not read these files in the main path:

• synthesis/raw_research.md (deprecated; not a formatter input)
• synthesis/claim_bank.json
• collect/inventory.json
• full Graphify outputs
• collect/graphify-out/GRAPH_REPORT.md

Missing claim slices are fatal. Do not fall back to claim_bank.json.

Required Outputs

• output/assembly_plan.json
• output/sections/<section_id>.md
• output/sections/<section_id>.meta.json
• output/report.md
• output/formatter_audit.json

Do not write output/report.qmd, output/report.html, or output/report.pdf. Those belong to publishing.

Citation Contract

All citations use one global format:

[Source Title](url)

Numeric citations such as [1](url) or [1] are disallowed. Mixed citation styles fail the formatter audit.

Composition Flow

1. Build the assembly plan:

``bash python3 ~/.claude/skills/research-format/scripts/reportcomposer.py \ build-plan --run-dir "$rundir" ``

1. For each assembly-plan section, read only:

- sectionbriefpath, - claimslicepath, - graph hints matching the same section_id, - format preferences.

1. Compose output/sections/<section_id>.md.

- Start with ## <Section Title>. - Open with a short summary. - Include every mustincludeclaimid from requiredclaims. - Include optional claims only when useful for the selected depth. - Preserve missing-evidence notes and contradictions. - Use graph hints only for central entities, cross-links, and relationship language inside the existing planned section. - Do not let graph hints create, remove, or reorder sections.

1. Emit output/sections/<section_id>.meta.json.

- claimidsused must include all required claims used in prose, tables, or diagrams. - sourceidsused must be a subset of the section sourcerecords. - crosslinks must reference existing planned section IDs only. - warnings should record skipped optional claims, weak evidence, or unresolved overlap.

1. Assemble the canonical report:

``bash python3 ~/.claude/skills/research-format/scripts/reportcomposer.py \ assemble --run-dir "$rundir" ``

1. Run the audit:

``bash python3 ~/.claude/skills/research-format/scripts/reportcomposer.py \ audit --run-dir "$rundir" ``

Formatting is not complete until formatter_audit.json has no errors.

Writing Rules

• The report must be useful as Markdown without any rendered format.
• Every factual sentence must be grounded in claims from the active section slice.
• The formatter may omit low-salience optional claims unless depth is comprehensive or audit-oriented.
• Do not invent claims, URLs, source titles, statistics, or graph relationships.
• Tables are preferred for comparisons of three or more comparable items.
• Mermaid diagrams are allowed only when they clarify a process or relationship.
• Paragraphs longer than five sentences should be split into bullets, tables, or subheadings.

Assembler Rules

The assembler may:

• concatenate sections in approved order,
• normalize heading levels,
• build the table of contents,
• generate a source list from actually used source IDs,
• remove duplicate intros,
• fix light transitions,
• flag or lightly merge obvious overlaps.

The assembler may not:

• reread evidence,
• reinterpret claims,
• rewrite whole sections,
• add uncited factual content,
• silently drop unique claims.

Legacy Raw-Research Mode

densityscan.py, coverageaudit.py, rawresearch.md, and claimindex.json are legacy compatibility mechanisms. They are not used for new claimpipelinev1 runs.