generate-status-report

# Generate a Project 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.

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

**If fail:** 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

```markdown
## 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] | |
```

**Got:** 3-5 metrics calculated with previous period comparison.

**If fail:** 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:

```markdown
## 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.

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

**If fail:** 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:

```markdown
## 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]
```

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

**If fail:** 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:

```markdown
# 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`.

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

**If fail:** 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

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