Generate Report

You are writing a report as a Markdown file with YAML frontmatter. Follow these instructions exactly.

File format

Every report is a .md file. Metadata goes in YAML frontmatter delimited by ---. Any markdown content below the frontmatter becomes the report body.

markdown

---
title: "Report Title"
category: performance
status: warning
summary: "One-line summary of findings"
source: your-agent-name
tags: [extra-tag-1, extra-tag-2]
updatedAt: "2025-06-15T10:00:00Z"
sections:
  - type: metrics
    title: "Section Title"
    items:
      - label: "Metric Name"
        value: 42
        unit: "ms"
        status: passing
---

## Markdown body

Any content below the closing `---` is rendered as a markdown section
after the structured sections declared in frontmatter.

Frontmatter fields

Field	Required	Type	Description
`title`	Yes	`string`	Human-readable report title.
`category`	Yes	`string`	Category for filtering (e.g., `performance`, `security`, `quality`). See category list below.
`status`	Yes	`"passing" \| "warning" \| "failing" \| "info"`	Overall health outcome.
`summary`	Yes	`string`	One-line summary of findings. Keep it concise — this is shown in list views.
`updatedAt`	Yes	`string`	ISO 8601 timestamp of when the report was generated (`YYYY-MM-DDTHH:mm:ssZ`).
`source`	Optional	`string`	Name of the agent or service that generated this report (e.g., `lighthouse`, `security-scanner`).
`tags`	Optional	`string[]`	Free-form tags for filtering (e.g., `[homepage, mobile, ci]`).
`sections`	Optional	`ReportSection[]`	Structured content sections (metrics, tables, markdown). See section types below.

Always provide title, category, status, summary, and updatedAt. Do not leave them empty or omit them.

File placement and tagging

Place report files inside a reports/ directory. Subdirectories automatically become tags on the report.

code

reports/
  daily-check.md                        # no directory tags
  security/
    audit.md                            # tagged: ["security"]
    dependency-scan.md                  # tagged: ["security"]
  performance/
    mobile/
      lighthouse.md                     # tagged: ["performance", "mobile"]

Directory-derived tags are merged with any tags declared in frontmatter, deduplicated.

Choose a filename that is a short, descriptive, kebab-case slug (e.g., dependency-scan.md, homepage-vitals.md).

Section types

Sections appear in the order listed in frontmatter. The markdown body (if present) is appended as a final section after all frontmatter sections. Put the most important information first.

Markdown section

Free-form text rendered as GitHub Flavored Markdown.

yaml

sections:
  - type: markdown
    content: |
      ## Analysis

      The homepage load time has improved by **15%** since last week.

Metrics section

Key performance indicators with optional deltas and per-metric status.

yaml

sections:
  - type: metrics
    title: "Core Web Vitals"
    items:
      - label: LCP
        value: 2.5
        unit: s
        previousValue: 3.1
        status: passing
      - label: FID
        value: 300
        unit: ms
        previousValue: 150
        status: failing

Each metric item:

Field	Required	Type	Description
`label`	Yes	`string`	Metric name (e.g., "LCP", "Coverage").
`value`	Yes	`number \| string`	Current value.
`unit`	Optional	`string`	Unit of measurement (e.g., "s", "ms", "%", "score").
`previousValue`	Optional	`number \| string`	Previous value for delta comparison.
`status`	Optional	`"passing" \| "warning" \| "failing" \| "info"`	Status of this individual metric.

Table section

Tabular data with column headers.

yaml

sections:
  - type: table
    title: "Dependency Vulnerabilities"
    columns: [Package, Severity, Version, Fixed In]
    rows:
      - [lodash, High, 4.17.20, 4.17.21]
      - [express, Medium, 4.17.1, 4.18.0]

Status reference

Status	When to use
`passing`	Everything is within acceptable thresholds.
`warning`	Some metrics are degraded or approaching thresholds.
`failing`	Critical issues that need immediate attention.
`info`	Informational report with no pass/fail judgment.

Category conventions

Category	Use case
`performance`	Web vitals, bundle size, load times.
`security`	Vulnerability scans, dependency audits.
`accessibility`	WCAG compliance, axe-core results.
`seo`	Meta tags, structured data, crawlability.
`quality`	Code quality, test coverage, lint results.
`uptime`	Health checks, availability monitoring.
`compliance`	License audits, policy checks.

Git workflow

Reports are stored on a dedicated git branch (typically reports).

Committing a report

bash

git checkout reports
mkdir -p reports/security
# ... write the file ...
git add reports/
git commit -m "report(security): add dependency vulnerability scan"
git push origin reports

Creating the branch for the first time

bash

git checkout --orphan reports
git rm -rf .
mkdir reports
# ... create your first report file ...
git add reports/
git commit -m "report: initialize reports branch"
git push -u origin reports

Additional resources

•For complete examples of different report types, see examples.md

Your task

Based on the user's request ($ARGUMENTS), generate a complete report file following the format above. Analyze the relevant code, data, or context in the repository before writing the report. Make sure the report contains real, accurate data — not placeholder values.