---
description: General report orchestration and shared report anatomy
agent: Reports
mode: subagent
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->

# General Reports

Use this doc for report briefs, report outlines, cross-domain reports, and
quality checks before export. Keep domain analysis in the domain agents; this
agent owns report structure, evidence traceability, and handoff contracts.

## Intake

Collect only what changes the report outcome:

- Audience, decision, deadline, cadence, and confidentiality level.
- Report type: one-off, baseline, recurring scorecard, audit, board pack,
  campaign review, incident review, or client handoff.
- Evidence sources, capture dates, tool outputs, and known gaps.
- Required exports: Markdown only, HTML, PDF, DOCX, slides, or archive bundle.
- Follow-up path: worker tasks, custom client agent, scheduled routine, or none.

## Report Anatomy

Use this default shape unless the domain doc provides a better template:

1. Cover metadata: client/project, scope, date range, author, version.
2. Executive summary: decision, status, top findings, recommended next action.
3. Method: data sources, collection commands, assumptions, and limitations.
4. Findings: evidence-backed observations with source IDs and confidence.
5. Recommendations: owner, priority, expected outcome, verification path.
6. Evidence ledger: source IDs, dates, URLs or paths, and supported claims.
7. Appendix: raw tables, screenshots, exports, unresolved questions.
8. Handoff: worker-ready tasks, routine schedule, or custom-agent prompt.

## Component Vocabulary

Use Toolbox-style Markdown containers when they improve scanning or export
quality. Supported renderer blocks include:

| Need | Markdown block |
|------|----------------|
| Cover, chaptering, separators | `::: report-cover`, `::: chapter-hero`, `---` |
| Summary stats rows | `::: stats-strip` with nested `::: stat-card` |
| Evidence and source cards | `::: source-card`, `::: evidence-panel`, evidence badges |
| Priority/severity panels | `::: priority-group priority=high`, `::: info-panel severity=critical` |
| Impact/evidence/action panels | `::: impact-panel`, `::: evidence-panel`, `::: action-panel` |
| Good/bad comparisons | `::: good-bad` with `::: good-row` and `::: bad-row` |
| Accordions and appendices | `::: accordion title="..."`, `::: appendix-links` |
| Sources | `::: sources-layout`, `::: sources-group`, `::: source-title`, `::: source-card` |
| Tables, code, quotes, links | `::: facts-table-wrap`, fenced code, `> quote`, Markdown links |
| Charts/math | `::: bar-chart`, fenced `mermaid`, fenced `latex`, `{{latex:...}}` |

Add appendix links when a report has supplementary data, screenshots, source
exports, or companion reports. Keep private appendices out of public examples.
Appendix links render file-type labels/icons from the link extension. Mermaid and
LaTeX render as portable source/fallback blocks; do not add external runtime
dependencies unless the export bundle vendors them locally.

## Generic vs Client-Custom Reports

Use the same Markdown-first report contract for both reusable guidance reports and
client-specific analysis reports, but change evidence collection depth:

| Report mode | Purpose | Evidence depth | Typical tools |
|-------------|---------|----------------|---------------|
| Generic guidance | Teach a domain, playbook, or operating model in a reusable template style. | Framework docs, curated source material, public references, and explicit assumptions. | Domain agents, local knowledge, `webfetch`, browser extraction for source examples. |
| Client-custom | Produce actionable findings for a specific website, product, app, service, business, campaign, citations, or backlinks. | Live data, crawl outputs, analytics/search exports, page screenshots, third-party profiles, engine runs, and source IDs. | Domain agents plus aidevops service helpers, browser automation, SEO/data providers, citation/backlink tools where configured. |

For client-custom reports, gather data before interpretation. Use deterministic
`run:` or helper commands for collection, then route the evidence bundle to the
domain agent and `agent:Reports` for reasoning, prioritisation, and narrative.
If the report pattern will repeat, finish with `reports/routine-handoff.md` so a
custom agent/routine can collect, monitor, and act on the recommendations.

## Routing Matrix

| Report focus | Load next | Keep here |
|--------------|-----------|-----------|
| SEO, GEO, AI-search visibility | `reports/seo-geo.md` | Structure, citations, export |
| Engineering, code quality, delivery | `reports/development.md` | Structure, citations, export |
| Campaigns, content, CRO, sales | `reports/marketing.md` | Structure, citations, export |
| Finance, operations, company runners | `reports/business.md` | Structure, citations, export |
| AI token, model, session, and MCP usage | `reports/token-use.md` | Local evidence bundle and session metrics |
| Export format or PDF styling | `reports/exporters.md` | Canonical Markdown contract |
| Recurring collection or custom client agent | `reports/routine-handoff.md` | Handoff completeness |

## Quality Gate

- Every material claim has an inline citation or an explicit `unsupported` note.
- Recommendations are decision-ready: owner, priority, rationale, verification.
- Markdown remains canonical; derived exports are not hand-edited.
- Public output replaces private paths, private repo names, and local machine
  details with placeholders.
- Follow-up tasks include file/page paths when known, reference patterns, and
  verification commands.

## Related

- `reports/citations.md` -- inline citations and optional `citations.json`.
- `reports/exporters.md` -- Markdown to HTML/PDF/export bundle contract.
- `reports/routine-handoff.md` -- recurring routines and custom client agents.
- `reports/outputs.md` -- `_reports/` directory and artifact contract.
