generate-status-report

Produce a periodic status report by analyzing project artifacts, calculating progress metrics, and summarizing accomplishments, blockers, and upcoming work with RAG (Red/Amber/Green) health indicators.

When to Use

• End of sprint or reporting period (weekly, biweekly, monthly)
• Stakeholder requests for project health update
• Before steering committee or governance meetings
• When project health indicators change (e.g., new blocker or risk materializes)
• Periodic checkpoint against charter milestones

Inputs

• Required: Reporting period (start date, end date)
• Required: At least one project artifact (BACKLOG.md, SPRINT-PLAN.md, WBS.md, or PROJECT-CHARTER.md)
• Optional: Previous status reports (for trend comparison)
• Optional: Budget or resource tracking data
• Optional: Risk register updates

Procedure

Step 1: Read Existing Artifacts

Scan the project directory for PM artifacts:

• PROJECT-CHARTER.md — milestones, success criteria
• BACKLOG.md — item counts by status, burn-down data
• SPRINT-PLAN.md — sprint goal, committed items, task completion
• WBS.md — work package completion percentages
• Previous STATUS-REPORT-*.md files — trend data

Read available files. Not all will exist — adapt the report to available data.

Expected: At least one artifact read successfully, key metrics extracted.

On failure: If no artifacts exist, report cannot be generated. Create a charter or backlog first using the draft-project-charter or manage-backlog skills.

Step 2: Calculate Progress Metrics

Compute metrics from available data:

Agile metrics (from BACKLOG.md / SPRINT-PLAN.md):

• Velocity: story points completed this sprint
• Sprint completion: items done / items committed
• Backlog burn-down: total remaining points vs previous period
• Cycle time: average days from In Progress to Done

Classic metrics (from WBS.md):

• % complete: work packages done / total work packages
• Schedule variance: planned milestone dates vs actual
• Effort variance: estimated effort vs actual effort consumed

## Metrics
| Metric | Value | Previous | Trend |
|--------|-------|----------|-------|
| Velocity | [N] pts | [N] pts | ↑/↓/→ |
| Sprint Completion | [N]% | [N]% | ↑/↓/→ |
| Backlog Remaining | [N] pts | [N] pts | ↓ (good) |
| Schedule Variance | [+/-N days] | [+/-N days] | |

Expected: 3-5 metrics calculated with previous period comparison.

On failure: If no historical data exists (first report), omit Previous and Trend columns. If data is incomplete, note gaps in report footer with action items to establish tracking.

Step 3: Identify Blockers, Risks, and Issues

List active blockers and risks:

## Blockers & Risks
| ID | Type | Description | Severity | Owner | Status | Action Required |
|----|------|------------|----------|-------|--------|----------------|
| R-001 | Risk | [Description] | High | [Name] | Open | [Action] |
| B-001 | Blocker | [Description] | Critical | [Name] | Active | [Action by date] |
| I-001 | Issue | [Description] | Medium | [Name] | Investigating | [Action] |

Cross-reference against the charter risk register. Flag any new risks not previously identified.

Expected: All active blockers and top risks documented with owners and actions.

On failure: If no blockers exist, explicitly state "No active blockers" — don't leave the section empty. If a blocker lacks an owner, escalate to project manager for assignment.

Step 4: Summarize Accomplishments and Next Period Plan

Write two sections:

## Accomplishments (This Period)
- [Completed item/milestone with evidence]
- [Completed item/milestone with evidence]
- [Completed item/milestone with evidence]

## Planned (Next Period)
- [Planned item/milestone with target]
- [Planned item/milestone with target]
- [Planned item/milestone with target]

Expected: 3-5 accomplishments with concrete evidence, 3-5 planned items for next period.

On failure: If no accomplishments exist, report the reason (blocked, re-planning, team unavailable). If next period plan is unclear, list "Planning session scheduled for [date]" as the primary item.

Step 5: Assign RAG Indicators and Write Report

Assess project health across four dimensions:

| Dimension | Green | Amber | Red | |---|---|---|---| | Schedule | On track or ahead | 1-2 weeks behind | >2 weeks behind or milestone missed | | Scope | No uncontrolled changes | Minor scope adjustments | Scope creep affecting deliverables | | Budget | Within 5% of plan | 5-15% over plan | >15% over plan or untracked | | Quality | Tests pass, criteria met | Minor quality issues | Critical defects or acceptance failures |

Write the complete report:

# Status Report: [Project Name]
## Report Date: [YYYY-MM-DD]
## Reporting Period: [Start] to [End]
## Document ID: SR-[PROJECT]-[YYYY-MM-DD]

### Overall Health
| Dimension | Status | Notes |
|-----------|--------|-------|
| Schedule | 🟢/🟡/🔴 | [One-line explanation] |
| Scope | 🟢/🟡/🔴 | [One-line explanation] |
| Budget | 🟢/🟡/🔴 | [One-line explanation] |
| Quality | 🟢/🟡/🔴 | [One-line explanation] |

### Executive Summary
[2-3 sentences: overall status, key achievement, biggest risk]

### Metrics
[From Step 2]

### Accomplishments
[From Step 4]

### Blockers & Risks
[From Step 3]

### Planned Next Period
[From Step 4]

### Decisions Needed
- [Decision 1 — needed by date, from whom]

---
*Report prepared by: [Name/Agent]*

Save as STATUS-REPORT-[YYYY-MM-DD].md.

Expected: Complete status report saved with RAG indicators, metrics, and narrative.

On failure: If data is insufficient for RAG assessment, use ⚪ (Grey) indicating "insufficient data" and list what data needs to be collected for next report.

Validation

• [ ] Status report file created with correct date-stamped filename
• [ ] RAG indicators assigned for all four dimensions with justification
• [ ] At least 3 metrics calculated from project artifacts
• [ ] Blockers section present (even if "No active blockers")
• [ ] Accomplishments listed with evidence
• [ ] Next period plan included
• [ ] Executive summary is 2-3 sentences, not a paragraph
• [ ] Every blocker and risk has an owner and action with deadline

Common Pitfalls

• Report without data: Status reports must be evidence-based. Every claim should reference an artifact or metric.
• All green, all the time: Persistent green RAG without evidence suggests the report isn't honest. Challenge green assessments.
• Blocker without owner: Every blocker needs an owner and an action. Unowned blockers don't get resolved.
• Metric without context: "Velocity = 18" means nothing without comparison. Always include previous period or target.
• Too long: A status report should be scannable in 2 minutes. Keep it to 1-2 pages.
• Missing decisions section: If the project needs stakeholder decisions, make them explicit with deadlines.
• Stale data: Using outdated artifacts leads to misleading reports. Verify artifact dates match reporting period.
• Missing trend data: First-time reports can't show trends, but subsequent reports must compare to previous periods.

Related Skills

• draft-project-charter — charter provides milestones and success criteria for status tracking
• manage-backlog — backlog metrics feed the status report
• plan-sprint — sprint results provide velocity and completion data
• create-work-breakdown-structure — WBS completion drives classic progress metrics
• conduct-retrospective — status report data feeds the retrospective