report-generation

# Report Generation

This skill enables an AI agent to produce polished, data-driven reports from structured input. The agent accepts data in JSON, CSV, or API response format, applies a report template, generates narrative insights alongside tables and chart specifications, and outputs the final report in Markdown, HTML, or PDF. It supports common report types including sprint retrospectives, financial summaries, analytics dashboards, and incident postmortems.

## Workflow

1. **Ingest and validate the source data.** Accept the input data file or payload in JSON, CSV, YAML, or raw API response format. Validate the schema — check for required fields, correct data types, missing values, and outliers. If the data is incomplete (e.g., a sprint retro JSON missing the velocity field), flag the gap and either infer a default, request the missing value, or note the omission in the report. Normalize date formats, currency symbols, and units for consistency.

2. **Select or customize the report template.** Match the data to a report template based on the report type specified by the user. Built-in templates include: `sprint_retrospective`, `financial_summary`, `analytics_dashboard`, `incident_postmortem`, and `weekly_status`. Each template defines the section order, required data mappings, chart types, and tone (analytical for financial reports, constructive for retros, urgent for postmortems). Users can customize templates by overriding sections, adding fields, or changing the visual theme.

3. **Compute metrics and generate insights.** Derive computed metrics from the raw data — percentage changes, averages, rankings, trend directions, and anomaly flags. For a sprint retro, calculate velocity variance and commitment accuracy. For an analytics report, compute conversion rates and segment-level breakdowns. Then generate narrative insights: not just "conversion rate was 3.2%" but "conversion rate dropped 0.8pp from last period, driven primarily by a 15% decline in mobile traffic."

4. **Populate the report structure.** Fill the template sections with the computed metrics, narrative insights, and formatted data tables. Generate chart specifications (bar, line, pie, or table) for each visualization slot in the template. Use Markdown table syntax for inline tables and a chart spec format (e.g., Mermaid, Vega-Lite, or Chart.js JSON) for visual charts. Add section headers, executive summary, and any appendices.

5. **Format and render the output.** Produce the final report in the requested format. For Markdown, output a clean `.md` file with tables and chart code blocks. For HTML, wrap the Markdown output in a styled template with CSS for print-friendly rendering. For PDF, convert the HTML version using a headless browser or a tool like Puppeteer or WeasyPrint. Ensure charts render correctly in all formats and that tables don't break across pages in PDF.

6. **Review and finalize.** Run a quality check: verify all data points in the report trace back to the source data, ensure no template variables remain unresolved (e.g., `{{quarter}}`), confirm that insights are supported by the numbers, and check that the report length matches the expected range for its type. Deliver the report with a brief summary of what was generated.

## Usage

Provide the agent with the report type, source data, any customization preferences, and the desired output format. The agent returns a complete, formatted report.

**Prompt format:**

~~~
Generate a [report type] report.
Data source: [path to JSON/CSV file, or inline data]
Time period: [date range or sprint number]
Template: [built-in template name or "custom"]
Output format: [markdown / html / pdf]
~~~

## Examples

### Example 1: Sprint Retrospective Report from Structured Data

**Input data (JSON):**

~~~json
{
  "sprint": {
    "number": 14,
    "start_date": "2026-01-27",
    "end_date": "2026-02-07",
    "goal": "Ship checkout flow redesign and analytics instrumentation"
  },
  "velocity": {
    "committed": 34,
    "completed": 29,
    "previous_sprints": [31, 28, 33, 30]
  },
  "stories": {
    "total": 12,
    "completed": 10,
    "carried_over": 2,
    "carried_over_items": [
      "CHECKOUT-142: Edge case handling for international addresses",
      "ANALYTICS-89: Cross-domain tracking for subdomain events"
    ]
  },
  "what_went_well": [
    "Checkout redesign shipped 2 days early",
    "Zero P1 bugs in production release",
    "Effective pairing sessions between frontend and backend teams"
  ],
  "what_could_improve": [
    "Sprint scope increased mid-sprint with 3 unplanned tickets",
    "QA bottleneck on Thursday caused idle time for 2 developers",
    "Standup meetings ran over 15 minutes on 3 of 10 days"
  ],
  "action_items": [
    { "owner": "Priya", "action": "Add a mid-sprint scope freeze policy" },
    { "owner": "James", "action": "Schedule a dedicated QA window on Wednesdays" },
    { "owner": "Dana", "action": "Timekeeper rotation for standups" }
  ]
}
~~~

**Output (Markdown report):**

~~~markdown
# Sprint 14 Retrospective

**Sprint dates:** January 27 – February 7, 2026
**Sprint goal:** Ship checkout flow redesign and analytics instrumentation

---

## Executive Summary

Sprint 14 delivered 85% of committed story points (29 of 34), slightly below
the team's rolling average velocity of 30.5. The primary sprint goal was
partially met: the checkout redesign shipped ahead of schedule, but two
analytics stories carried over due to mid-sprint scope changes and a QA
bottleneck. Zero P1 bugs were introduced, reflecting strong code quality.

## Velocity

| Metric               | Sprint 14 | 4-Sprint Average |
|----------------------|-----------|------------------|
| Committed            | 34 pts    | 31.0 pts         |
| Completed            | 29 pts    | 30.5 pts         |
| Commitment accuracy  | 85%       | 98%              |

The team over-committed by 3 points relative to the historical average.
The shortfall is attributable to 3 unplanned ticket