---
name: status-updates
description: WHEN writing team updates, progress reports, or stakeholder comms; delivers scannable structure, honest framing, and warm recognition.
---

# Status Updates Playbook

Guidelines for writing team updates that are easy to scan, honest about challenges, and generous with recognition.

## Philosophy

- **Outcomes first** - Lead with results and impact, not activity; tie to goals/OKRs
- **Scannable** - Emoji-anchored sections, bullet points, short paragraphs
- **Quantify** - Metrics, deltas, dates, owners—show progress with numbers
- **Honest** - Acknowledge challenges directly, then reframe with context
- **Warm** - Credit individuals by name, use inclusive language
- **Evidence-backed** - Link to production, docs, metrics to show not tell
- **Close the loop** - Note delta from last update and what's next

## Quick Reference

| Task | Guide |
|------|-------|
| Voice and tone patterns | [tone-profile.md](tone-profile.md) |
| PR evidence gathering | [pr-evidence.md](pr-evidence.md) |

## When to Use

- Team or stakeholder progress updates
- Manager/exec communications
- Slack channel announcements
- Sprint summaries or retrospectives
- Launch communications

## Intake Questions

Ask these before drafting to ensure the update hits the right notes:

**Essential:**

- Audience & channel (manager, exec, peers? email, Slack, doc?)
- Time window (which two weeks? tie to OKRs/roadmap item?)
- Desired outcome (inform, influence decision, unblock, build trust?)

**Evidence gathering:**

- GitHub username (to pull authored PRs from past 14 days)
- Impact evidence (metrics, user/business outcomes, shipped artifacts?)

**Framing:**

- Risks/blockers (what needs escalation, by when?)
- Length/tone preference (bullets vs paragraph, RAG color?)

**Recognition:**

- Glue work to highlight (reviews, incidents, mentoring, docs, coordination?)
- Who to thank or spotlight?

If details are missing, ask concise clarifying questions before drafting.

## Core Patterns

### Structure

1. **Friendly hook** (optional): Seasonal reference or greeting
2. **Section headers**: Emoji prefix + bold title
3. **Bullet points**: Outcome-first, with inline evidence links
4. **Named recognition**: Specific individuals at section end
5. **Forward momentum**: End with what's next

### Framing Challenges

Never bury bad news. Acknowledge it, then provide context:

> "Great progress and some less-than-ideal timeline changes. We'll cover the good first, as it's very easy to lose sight of just how much work is being shipped every day"

**Pattern:** [Bad news] + [acknowledge feeling] + "There is [context] though:" + [reframing bullets]

### Evidence and Links

Weave links naturally into claims:

> "shipped to production, to the X page ([our fastest growing page](link))"

Use footnotes for caveats that would clutter the main flow.

## Do's and Don'ts

**Do:**

- Open with a hook before diving in
- Use emoji for visual hierarchy (one per section)
- Credit individuals by name
- Link to evidence
- Use `backticks` for technical terms
- End with momentum

**Don't:**

- Bury or avoid bad news
- Use emoji as decoration
- Give vague thanks ("thanks everyone")
- Write dense paragraphs
- Over-explain technical concepts

For detailed voice characteristics and replication techniques, see [tone-profile.md](tone-profile.md).

---

## Writing Guidance

**Phrasing:**

- Use verbs + outcomes: "Shipped X → improved Y by Z%" not "Worked on X"
- Keep bullets single-line; front-load result, back-load detail
- Include dates/owners for risks and asks

**Progression:**

- Note delta from last update ("Previously blocked, now shipped")
- Mention decisions made and decisions pending (with decision-maker)

**Dependencies:**

- Call out dependencies you're unblocking for others
- Call out dependencies you need unblocked