status-updates

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
PR evidence gathering	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)"

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.

---

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