git:20260318.9c4aafd to git:20260318.4ba4f0c

- ## Overview

-

- This skill provides frameworks and guidance for effective professional communication in software development contexts. Whether you're writing an email to stakeholders, crafting a team chat message, or preparing meeting agendas, these principles help you communicate clearly and build professional credibility.

-

- **Core principle:** Effective communication isn't about proving how much you know - it's about ensuring your message is received and understood.

-

- ## When to Use This Skill

-

- Use this skill when:

-

- - Writing emails to teammates, managers, or stakeholders

- - Crafting team chat messages or async communications

- - Preparing meeting agendas or summaries

- - Translating technical concepts for non-technical audiences

- - Structuring status updates or reports

- - Improving clarity of written communication

-

- **Keywords**: email, chat, teams, slack, discord, message, writing, communication, meeting, agenda, status update, report

-

- ## Core Frameworks

- ### The What-Why-How Structure

- Use this universal framework to organize any professional message:

- **Apply to**: Emails, status updates, meeting talking points, technical explanations

-

- ### Three Golden Rules for Written Communication

-

- 1. **Start with a clear subject/purpose** - Recipients should immediately grasp what your message is about

- 2. **Use bullets, headlines, and scannable formatting** - Nobody wants a wall of text

- 3. **Key messages first** - Busy people appreciate efficiency; state your main point upfront

-

- ### Audience Calibration

-

- Before communicating, ask yourself:

-

- 1. **Who** are you writing to? (Technical peers, managers, stakeholders, customers)

- 2. **What level of detail** do they need? (High-level overview vs implementation details)

- 3. **What's the value** for them? (How does this affect their work/decisions?)

-

- ## Email Best Practices

-

- ### Subject Line Formula

-

- | Instead of | Try |

- | --- | --- |

- | "Project updates" | "Project X: Status Update and Next Steps" |

- | "Question" | "Quick question: API rate limiting approach" |

- | "FYI" | "FYI: Deployment scheduled for Tuesday 3pm" |

-

- ### Email Structure Template

-

- ```markdown

- **Subject:** [Project/Topic]: [Specific Purpose]

-

- Hi [Name],

-

- [1-2 sentences stating the key point or request upfront]

-

- **Context/Background:**

- - [Bullet point 1]

- - [Bullet point 2]

-

- **What I need from you:**

- - [Specific action or decision needed]

- - [Timeline if applicable]

-

- [Optional: Brief next steps or follow-up plan]

-

- Best,

- [Your name]

- ```

-

- ### Common Email Types

-

- | Type | Key Elements |

- | --- | --- |

- | **Status Update** | Progress summary, blockers, next steps, timeline |

- | **Request** | Clear ask, context, deadline, why it matters |

- | **Escalation** | Issue summary, impact, attempted solutions, needed decision |

- | **FYI/Announcement** | What changed, who's affected, any required action |

-

- **For templates**: See `references/email-templates.md`

-

- ## Team Messaging Etiquette

- > **Note:** Examples use Slack terminology, but these principles apply equally to Microsoft Teams, Discord, or any team messaging platform.

- ### When to Use Chat vs Email

- | Use Chat | Use Email |

- | Quick questions with short answers | Detailed documentation needing records |

- | Real-time coordination | Formal communications to stakeholders |

- | Informal team discussions | Messages requiring careful review |

- | Time-sensitive updates | Complex explanations with multiple parts |

- ### Team Messaging Best Practices

- 1. **Use threads** - Keep main channels scannable; follow-ups go in threads

- 2. **@mention thoughtfully** - Don't notify people unnecessarily

- 3. **Channel organization** - Right channel for right topic

- 4. **Be direct** - "Can you review my PR?" beats "Hey, are you busy?"

- 5. **Async-friendly** - Write messages that don't require immediate response

- ### The "No Hello" Principle

-

- ```text

- Try:

-

- ```text

- You: Hi Sarah - quick question about the deployment script.

- ## Technical vs Non-Technical Communication

-

- ### When to Be Technical vs Accessible

-

- | Audience | Approach |

- | --- | --- |

- | **Engineering peers** | Technical details, code examples, architecture specifics |

- | **Technical managers** | Balance of detail and high-level impact |

- | **Non-technical stakeholders** | Business impact, analogies, outcomes over implementation |

- | **Customers** | Plain language, what it means for them, avoid jargon |

- ### Three Strategies for Simplification

- 1. **Start with the big picture before details** - People process "why" before "how"

- 2. **Simplify without losing accuracy** - Use analogies; replace jargon with plain language

- 3. **Know when to switch** - Read the room; adjust based on questions and engagement

- ### Jargon Translation Examples

- | Technical | Plain Language |

- | --- | --- |

- | "Microservices architecture" | "Our system is split into smaller, independent pieces that can scale separately" |

- | "Asynchronous message processing" | "Tasks are queued and processed in the background" |

- | "CI/CD pipeline" | "Automated process that tests and deploys our code" |

- | "Database migration" | "Updating how our data is organized and stored" |

- **For more examples**: See `references/jargon-simplification.md`

- ## Writing Clarity Principles

- ### Active Voice Over Passive Voice

- Active voice is clearer, more direct, and conveys authority:

- | Passive (avoid) | Active (prefer) |

- | --- | --- |

- | "A bug was identified by the team" | "The team identified a bug" |

- | "The feature will be implemented" | "We will implement the feature" |

- | "Errors were found during testing" | "Testing revealed errors" |

- ### Eliminate Filler Words

- | Instead of | Use |

- | "At this point in time" | "Now" |

- | "In the event that" | "If" |

- | "Due to the fact that" | "Because" |

- | "In order to" | "To" |

- | "I just wanted to check if" | "Can you" |

-

- ### The "So What?" Test

-

- After writing, ask: "So what? Why does this matter to the reader?"

-

- If you can't answer clearly, restructure your message to lead with the value/impact.

-

- ## Meeting Communication

-

- ### Before: Agenda Best Practices

-

- Every meeting invite should include:

-

- 1. **Clear objective** - What will be accomplished?

- 2. **Agenda items** - Topics to cover with time estimates

- 3. **Preparation required** - What should attendees bring/review?

- 4. **Expected outcome** - Decision needed? Information sharing? Brainstorm?

-

- ### During: Facilitation Tips

-

- - **Time-box discussions** - "Let's spend 5 minutes on this, then move on"

- - **Capture action items live** - Who does what by when

- - **Parking lot** - Note off-topic items for later

-

- ### After: Summary Format

-

- ```markdown

- **Meeting: [Topic] - [Date]**

-

- **Attendees:** [Names]

-

- **Key Decisions:**

- - [Decision 1]

- - [Decision 2]

-

- **Action Items:**

- - [ ] [Person]: [Task] - Due [Date]

- - [ ] [Person]: [Task] - Due [Date]

-

- **Next Steps:**

- - [Follow-up meeting if needed]

- - [Documents to share]

- ```

-

- **For structures by meeting type**: See `references/meeting-structures.md`

-

- ## Quick Reference: Communication Checklist

-

- Before sending any professional communication:

- - [ ] **Clear purpose** - Can the recipient understand intent in 5 seconds?

- - [ ] **Right audience** - Is this the appropriate person/channel?

- - [ ] **Key message first** - Is the main point upfront?

- - [ ] **Scannable** - Are there bullets, headers, short paragraphs?

- - [ ] **Action clear** - Does the recipient know what (if anything) they need to do?

- - [ ] **Jargon check** - Will the audience understand all terminology?

- - [ ] **Tone appropriate** - Is it professional but not cold?

- - [ ] **Proofread** - Any typos or unclear phrasing?

- ## Additional Tools

- - `references/email-templates.md` - Ready-to-use email templates by type

- - `references/meeting-structures.md` - Structures for standups, retros, reviews

- - `references/jargon-simplification.md` - Technical-to-plain-language translations

- - `feedback-mastery` - For difficult conversations and feedback delivery

- - `/draft-email` - Generate emails using these frameworks

-

- ---

-

- **Last Updated:** 2025-12-22

-

- ## Version History

-

- - **v1.0.0** (2025-12-26): Initial release

-

- ---