- 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 |
| 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
- Friendly hook (optional): Seasonal reference or greeting
- Section headers: Emoji prefix + bold title
- Bullet points: Outcome-first, with inline evidence links
- Named recognition: Specific individuals at section end
- 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
backticksfor 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