generate-report

name: generate-report description: Generate a structured Markdown report with YAML frontmatter for repository health monitoring. Use when the user asks to create a report, health check, audit, scan result, or status update for a repository. argument-hint: "[topic or category] e.g. 'security audit' or 'performance lighthouse'"

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.

---
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

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.

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.

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.

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:

Table section

Tabular data with column headers.

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

Category conventions

Git workflow

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

Committing a report

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

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.