status-report

name	status-report
version	0.1.0
description	Write periodic status reports summarizing overall system health, uptime, incidents, and maintenance. Use when the user mentions "status report," "health report," "uptime report," "weekly status," "monthly report," "system health summary," "reliability report," or wants to publish a regular update on how their services are performing.

Status Report

Write periodic status reports that give stakeholders a clear picture of system health, reliability trends, and what's being done to improve.

When to Use

• "write a weekly status report"
• "draft our monthly uptime report"
• "summarize system health for this quarter"
• "write a reliability report for stakeholders"

Workflow

1. Check for Context

Read .agents/status-page-context.md if it exists. Use it for:

• Component names — report on the right services
• SLA targets — compare actual uptime against commitments
• Severity levels — classify incidents consistently
• Tone — match the team's communication style

If the file doesn't exist, suggest running the status-page-context skill first. Proceed without it if the user wants to skip.

2. Determine Report Type

Ask the user if not obvious:

Type	Cadence	Audience	Focus
Weekly	Every week	Internal team, stakeholders	Recent incidents, upcoming maintenance, quick health snapshot
Monthly	Every month	Customers, leadership	Uptime metrics, incident summary, trends, improvements
Quarterly	Every quarter	Leadership, board, customers	Reliability trends, SLA performance, strategic improvements
Ad-hoc	As needed	Varies	Specific topic (e.g., post-migration health, new region launch)

3. Gather Data

Ask the user for or help them collect:

Required:

• Reporting period (exact date range)
• Uptime numbers per component (or overall)
• Number and severity of incidents during the period
• Any scheduled maintenance that occurred

Important (include if available):

• SLA target vs actual comparison
• Error budget status (consumed/remaining)
• Mean time to detect (MTTD), mean time to resolve (MTTR)
• Incident trends (improving, stable, worsening)
• Notable incidents with brief descriptions

Optional:

• Performance metrics (latency, throughput)
• Upcoming planned maintenance
• Reliability improvements shipped
• Customer-reported issues

4. Write the Report

Follow these principles:

Principle 1: Lead with the headline number

The first thing readers want to know: how did we do?

Do: "Overall uptime for March 2026: 99.97% (target: 99.9%). Zero critical incidents." Don't: Start with a paragraph about the team's efforts.

Principle 2: Compare against targets

Raw numbers without context are meaningless. Always compare to SLA targets or previous periods.

Do: "API uptime: 99.95% (target: 99.9%) — 0.05% above target. Error budget: 62% remaining." Don't: "API uptime: 99.95%." (Is that good? Bad? On track?)

Principle 3: Be honest about bad periods

A status report that only highlights good metrics loses credibility. Address misses directly.

Do: "Webhook delivery uptime dropped to 99.2% this month, below our 99.5% target. This was driven by the March 14 incident (see below). We've shipped [fix] to prevent recurrence." Don't: Omit components that missed their targets.

Principle 4: Show trends, not just snapshots

One month's number doesn't tell a story. Compare to previous periods.

Do: "MTTR improved from 45 min (Feb) to 28 min (Mar), driven by the new automated rollback system." Don't: "MTTR: 28 minutes." (Better or worse than before?)

Principle 5: Connect incidents to improvements

Every incident mentioned should link to what was done about it. This builds trust.

Do: "March 14 — Webhook delivery failure (47 min). Root cause: connection pool exhaustion. Fix shipped: automated pool scaling + alert at 80% capacity." Don't: "March 14 — Webhook delivery failure (47 min)." (And then?)

Principle 6: End with what's next

Forward-looking items show the team is proactive, not just reactive.

Do: "Upcoming: Database migration (April 3, 02:00-04:00 UTC), new monitoring for edge regions, SLA review for Q2." Don't: End abruptly after the metrics.

Report Templates

Weekly Status Report

# Weekly Status Report: [Date Range]

## Summary
[1-2 sentences: overall health this week. Lead with the headline.]

## Uptime

| Component | Uptime | Target | Status |
|-----------|--------|--------|--------|
| [Component] | [%] | [%] | [On target / Below target] |

## Incidents This Week

| Date | Severity | Component | Duration | Summary |
|------|----------|-----------|----------|---------|
| [Date] | [Sev] | [Component] | [Duration] | [One-line summary + fix status] |

[If no incidents: "No incidents this week."]

## Maintenance

| Date | Component | Duration | Status |
|------|-----------|----------|--------|
| [Date] | [Component] | [Duration] | [Completed / Scheduled] |

## Looking Ahead
- [Upcoming maintenance]
- [Reliability improvements in progress]
- [Anything the team should be aware of]

Monthly Status Report

# Monthly Status Report: [Month Year]

## Executive Summary
[2-3 sentences: how the month went, headline metrics, key events.]

## Uptime & SLA Performance

| Component | Uptime | SLA Target | vs Target | vs Last Month |
|-----------|--------|------------|-----------|---------------|
| [Component] | [%] | [%] | [+/- %] | [+/- %] |

**Overall uptime:** [%]
**Error budget consumed:** [%] ([remaining]% remaining for [period])

## Reliability Metrics

| Metric | This Month | Last Month | Trend |
|--------|-----------|------------|-------|
| Incidents (total) | [N] | [N] | [direction] |
| Critical incidents | [N] | [N] | [direction] |
| MTTD (mean time to detect) | [min] | [min] | [direction] |
| MTTR (mean time to resolve) | [min] | [min] | [direction] |

## Incident Summary

### [Incident title] — [Date]
- **Severity:** [Level]
- **Duration:** [X min/hours]
- **Impact:** [What users experienced]
- **Root cause:** [1 sentence]
- **Fix:** [What was done]
- **Postmortem:** [Link or "published" or "in progress"]

[Repeat for each notable incident. Minor incidents can be summarized in a table.]

## Maintenance Summary

[Table of maintenance windows with component, date, duration, outcome.]

## Improvements Shipped

- [Reliability improvement with brief description of what it prevents]
- [Monitoring improvement]
- [Process improvement]

## Looking Ahead

- **Upcoming maintenance:** [Dates and components]
- **In progress:** [Reliability work underway]
- **SLA review:** [Any target changes under consideration]

---

*Next report: [Date]*

Quarterly Status Report

# Quarterly Reliability Report: [Q# Year]

## Executive Summary
[3-5 sentences: quarter performance, key wins, key challenges, strategic outlook.]

## Quarterly Metrics

| Metric | Q[N] | Q[N-1] | Q[N-2] | Trend |
|--------|------|--------|--------|-------|
| Overall uptime | [%] | [%] | [%] | [direction] |
| Critical incidents | [N] | [N] | [N] | [direction] |
| Total incident minutes | [N] | [N] | [N] | [direction] |
| MTTD | [min] | [min] | [min] | [direction] |
| MTTR | [min] | [min] | [min] | [direction] |
| Error budget remaining | [%] | [%] | [%] | [direction] |

## SLA Performance by Component

| Component | Q[N] Uptime | SLA Target | Met? |
|-----------|-------------|------------|------|
| [Component] | [%] | [%] | [Yes/No] |

## Notable Incidents

[Top 3-5 incidents by severity/impact with brief summaries and links to postmortems.]

## Reliability Investments

### Shipped This Quarter
- [Initiative]: [Impact/result]

### In Progress
- [Initiative]: [Expected completion, expected impact]

### Planned for Next Quarter
- [Initiative]: [Why, expected impact]

## Lessons Learned
- [Key takeaway from the quarter's incidents]
- [Pattern or trend identified]
- [Process or cultural insight]

## Outlook
[2-3 sentences on focus areas for next quarter.]

---

*Next quarterly report: [Date]*

Anti-patterns to Avoid

Anti-pattern	Why it's bad	Instead
"All systems operational" with no data	Provides no transparency or accountability	Show uptime numbers against targets
Only reporting good metrics	Erodes trust when stakeholders discover omissions	Address misses directly with root cause and fix
Raw numbers without context	"99.95%" means nothing without the target	Always compare: vs target, vs last period
Listing incidents without fixes	Feels like a problem list, not a report	Connect every incident to what was done about it
Skipping months with no incidents	Inconsistency in reporting cadence	Still publish — "No incidents this month" is a positive signal
Overly long reports	Nobody reads them	Keep weekly to 1 page, monthly to 2 pages, quarterly to 3-4 pages

Related Skills

• status-page-context — Set up the context document this skill reads (components, SLA targets, tone)
• incident-communication — Write updates during active incidents (referenced in incident summaries)
• postmortem — Write detailed postmortems (linked from incident summaries)
• maintenance — Write maintenance announcements (referenced in maintenance summaries)