Internal Comms Smart

A practical skill for writing effective internal communications — covering 3P updates (Progress, Plans, Problems), company newsletters, status reports, incident reports, leadership updates, and project announcements with appropriate tone and structure.

When to Use This Skill

Choose Internal Comms Smart when you need to:

• Write 3P updates (Progress, Plans, Problems) for stakeholders
• Draft company-wide announcements or newsletters
• Create incident reports and post-mortems for internal distribution
• Write project status updates for leadership
• Compose team announcements for organizational changes

Consider alternatives when:

• You need customer-facing communications (use an email or PR skill)
• You need marketing newsletters (use an email marketing skill)
• You need formal business proposals (use a business writing skill)

Quick Start

Copy
# Generate a 3P update
claude "Write a 3P update for the engineering team's sprint. Progress: migrated 80% of auth service to new framework. Plans: complete migration next week, start load testing. Problems: CI pipeline is 40% slower after adding security scans."

Copy
# Engineering 3P Update — Week of Dec 16

## ✅ Progress
- **Auth Service Migration**: 80% complete — user
  authentication, session management, and token refresh
  endpoints migrated to the new framework. Integration
  tests passing on all migrated endpoints.
- **Database Optimization**: Query response times improved
  by 35% after index tuning on the orders table.

## 📋 Plans
- **Complete Auth Migration** (Dec 20): Migrate remaining
  OAuth2 flows and admin endpoints. Target: 100% by Friday.
- **Load Testing** (Dec 23-27): Run performance benchmarks
  on migrated auth service. Compare against baseline metrics
  from the legacy service.

## ⚠️ Problems
- **CI Pipeline Slowdown**: Pipeline duration increased from
  12 min to 17 min (+40%) after integrating SAST security
  scans. **Impact**: Developer iteration speed reduced.
  **Proposed Fix**: Parallelize security scans with unit
  tests instead of running sequentially. ETA: Dec 18.

Core Concepts

Communication Types

Type	Audience	Frequency	Tone
3P Update	Direct manager	Weekly	Factual, concise
Sprint Summary	Engineering org	Bi-weekly	Technical
Incident Report	Engineering + Ops	Per incident	Objective, clear
Company Update	All employees	Monthly	Inclusive, clear
Change Announce	Affected teams	As needed	Empathetic, firm
Leadership Brief	Executives	Weekly/Monthly	Data-driven

Status Report Framework

Copy
## Executive Status Report Template

### One-Line Summary
[Project] is [on track / at risk / blocked] for
[milestone] by [date].

### Key Metrics
| Metric          | Target | Actual | Status |
|----------------|--------|--------|--------|
| Sprint velocity | 40 pts | 38 pts | 🟡     |
| Bug count       | < 10   | 7      | 🟢     |
| Test coverage   | > 80%  | 82%    | 🟢     |
| Uptime          | 99.9%  | 99.87% | 🟡     |

### Decisions Needed
1. [Decision] — Options: A or B. Recommend A because [reason].
   Deadline: [date].

### Risks
| Risk              | Probability | Impact | Mitigation      |
|------------------|-------------|--------|-----------------|
| Vendor delay     | Medium      | High   | Fallback vendor  |
| Scope creep      | High        | Medium | Freeze scope Fri |

Incident Report Template

Copy
# Incident Report: [INCIDENT-ID]

**Severity**: P1 / P2 / P3
**Duration**: [start time] to [end time] ([total minutes])
**Impact**: [X users affected, Y% error rate increase]
**Status**: Resolved / Monitoring

## Timeline
- **14:23 UTC** — Alert triggered: API error rate > 5%
- **14:25 UTC** — On-call engineer acknowledged
- **14:32 UTC** — Root cause identified: expired TLS cert
- **14:38 UTC** — Certificate renewed and deployed
- **14:42 UTC** — Error rate returned to baseline

## Root Cause
The TLS certificate for api.example.com expired at 14:20
UTC. Auto-renewal failed because the DNS validation
record was deleted during a DNS migration on Dec 10.

## Action Items
| Action                        | Owner  | Due Date  |
|------------------------------|--------|-----------|
| Add cert expiry monitoring   | DevOps | Dec 20    |
| Restore DNS validation record| Infra  | Done      |
| Document DNS migration SOP   | Infra  | Dec 27    |

Configuration

Parameter	Description	Example
comm_type	Type of communication	"3p_update" / "incident"
audience	Target audience	"engineering" / "all_company"
tone	Communication tone	"technical" / "leadership"
include_metrics	Add quantitative metrics	true
urgency	Urgency level for the communication	"normal" / "urgent"
format	Output format	"markdown" / "slack"

Best Practices

1. Lead with the conclusion, then provide supporting evidence — Executives read the first line and decide whether to read more. "Auth migration is on track for Dec 20 delivery" lets them move on. Burying the status in paragraph three means they'll miss it or ask you to repeat it.

2. Quantify everything that can be quantified — "Performance improved" is subjective. "Query latency dropped from 450ms to 290ms (35% improvement)" is verifiable and impactful. Numbers build credibility and make progress measurable across updates.

3. Keep problems paired with proposed solutions — Reporting a problem without a plan of action creates anxiety. "CI pipeline is 40% slower" alarms readers. "CI pipeline is 40% slower — we're parallelizing scans, ETA fix by Thursday" shows ownership and reduces the urge for leadership to intervene.

4. Use consistent formatting across all updates — If your 3P update changes format every week, readers waste mental energy re-learning the structure. Pick a template and stick with it. Consistency lets readers find what they need instantly through pattern recognition.

5. Send updates at consistent times — If your weekly update goes out at random times on random days, people stop expecting it and stop reading it. Pick a time (e.g., Monday 9am or Friday 4pm) and make it predictable.

Common Issues

Updates are too long and nobody reads them — Managers who want to demonstrate thoroughness write 2-page updates that get skimmed or skipped. Keep weekly updates under 200 words. If more detail is needed, link to a longer document and let readers choose their depth level.

Incident reports assign blame instead of identifying systemic causes — "The intern deleted the production database" is blame. "Production database access controls allowed individual users to execute DROP without approval" is a systemic finding that leads to a real fix. Focus on system design, not human error.

Tone is inconsistent across the organization — One team sends casual Slack updates while another sends formal Word documents. This creates confusion about organizational culture and professionalism standards. Create a brief internal comms style guide with examples for each communication type.