/report-writer — Library Skill: Markdown Report Generator

Reusable report formatting for producer agents. Domain-specific content on top of the generic.

How to Call

Skill tool: report-writer
Input: {
  template: "research" | "analysis" | "decision" | "weekly-summary",
  title: "<report title>",
  agent_slug: "<calling agent>",
  data: {
    executive_summary: "<2-5 sentences>",
    findings: [...],          // structure depends on template
    metrics: {...},           // if any
    sources: [...],           // attribution
    next_actions: [...]       // if any
  },
  output_path: "<save path>"  // optional — default: agents/<slug>/data/<run_slug>/report.md
}

Templates

research (for formatting web-research output)

---
generated_by: <agent>
generated_at: <ISO>
template: research-report-v1
sources_count: <N>
---

# <title>

> <agent_slug> · <ISO>

## Executive Summary
<3-5 bullets>

## Detailed Findings

### <Theme 1>
<synthesis paragraph>

**Sources**: [link1], [link2]

### <Theme 2>
...

## Contradictions / Open Questions
- <contradiction 1>: source A says X, source B says Y
- ...

## Conclusions
<2-3 paragraphs>

## References
<full URL list with metadata>

analysis (analyzer agent output)

---
generated_by: <agent>
generated_at: <ISO>
template: analysis-report-v1
---

# <title>

## Context
<1-2 paragraphs — what we analyzed>

## Methodology
<analysis approach>

## Findings
<bullet list or table>

## Interpretation
<analysis takeaway>

## Limitations
- <limit 1>
- <limit 2>

## Next Steps
- [ ] <action 1>

decision (decision-record, ADR-style)

---
generated_by: <agent>
generated_at: <ISO>
template: decision-record-v1
status: proposed | accepted | rejected
---

# <decision title>

## Status
<status + date>

## Context
<problem statement>

## Decision
<chosen path>

## Alternatives (rejected)
1. <option A> — why not: ...
2. <option B> — why not: ...

## Consequences (expected)
- ✅ <positive>
- ⚠ <risk>

## Decided by
<agent + workers (if council)>

analysis-tiered (hub / consensus output — 3-tier human-first)

For hubs (and council orchestrators), analysis-tiered-v1. Council outputs tend to be multi-section and jargon-heavy; this template splits the reader experience into 3 tiers:

• Tier 1 — Decision Layer: 300-500 words for a smart operator. A one-sentence verdict, 4-6 bullet summary, A/B/C option headings if any, 1 critical flag. Jargon-free. Recommended to produce with the plain-language-rewriter skill in mode: "tier-1-extract".
• Tier 2 — Rationale Layer: Hub-specific detail, evidence, nuance, contradictions, tables. Every abbreviation explained in parentheses on first occurrence (plain-language-rewriter mode: "inline-glossary"). Worker references by role label ("framework analyst," "virality researcher") — "Worker N" forbidden.
• Tier 3 — Audit Appendix: Sources, fenced JSON block (for executor.ts recovery), raw worker output summaries. Inside an appendix wrapper — appendix view for the user.

Hub-specific freedom: the contents of the tiers are defined in each hub's own FAZ 4. The template only guarantees the skeleton + reader contract.

---
generated_by: <agent>
generated_at: <ISO>
template: analysis-tiered-v1
council: <council-slug>
cycle_id: <id>
consensus_strength: <0-1>
hitl_fired: <bool>
---

# <title>

<!-- =================== TIER 1 — DECISION LAYER =================== -->

> **To understand in 30 seconds what to do:** read the 300-500 words below. Detail follows.

## Conclusion

<one-sentence verdict>

## Decision Summary

- <bullet 1>
- <bullet 2>
- ... (4-6 bullets)

## Options (if any)

**A) <heading>** — <one-sentence summary>. Risk: <one sentence>.
**B) <heading>** — <one-sentence summary>. Risk: <one sentence>.
**C) <heading>** — <one-sentence summary>. Risk: <one sentence>.

## ⚠ Critical Danger

<the one thing the reader must not overlook, 1-2 sentences>

---

<!-- =================== TIER 2 — RATIONALE LAYER =================== -->

> **If you want more depth:** the sections below open up the "why" side of the decision. Hub-specific detail, evidence, nuance. Every abbreviation is explained in parentheses on first occurrence.

<hub-specific sections — headings and content vary according to the hub's own FAZ 4 definition>

---

<!-- =================== TIER 3 — AUDIT APPENDIX (APPENDIX) =================== -->

<details>
<summary>📎 Audit Appendix — Sources, raw data, machine-readable JSON</summary>

### Sources

<source list>

### Worker Raw Output Summaries

<role-labeled summaries>

### Cycle Output (machine-readable)

` ``json
{ ... fenced JSON block ... }
` ``

</details>

Important technical notes:

• Frontmatter at the very top (for the cycle ledger and dashboard reports.ts).
• The fenced JSON is the last element of the Tier 3 appendix — executor.ts recovers the last ```json block in stdout; position is critical.
• The <details> markdown collapsible starts the appendix collapsed in GitHub render and in the dashboard view; the user opens it if they want.
• HTML mirror generation (if any, <title>.html) may make Tier 1 sticky/highlighted at the top of the page — that is a dashboard render decision, not at this template level.

weekly-summary (automator agent recap)

---
generated_by: <agent>
generated_at: <ISO>
template: weekly-summary-v1
period: <YYYY-Www>
---

# Weekly Summary — <agent>

## Metric Movements
| Metric | Before | Now | Δ | Trend |
|---|---|---|---|---|
| ... | ... | ... | ↗ +0.2 | improving |

## Action Summary
- <action 1>: <outcome>
- ...

## What Didn't Work This Week
- <fail 1>: <reason>

## Next Week's Plan
- [ ] <plan 1>

Flow

1. Select template — via input.template
2. Fill frontmatter — generated_by, generated_at, template version + outview_origin provenance stamp (see below)
3. Render body — place input.data fields into the template slots
4. Source attribution — references section if any
5. Write — output_path or default agents/<slug>/data/<timestamp>/report.md
6. Reports index — append a line to agents/<slug>/data/reports-index.jsonl

Provenance Stamp (Outview observability) — MANDATOR