Trigger with developer communication needs. Use when communicating with human developers in code reviews, issues, technical discussions, and status updates. Covers effective communication patterns.
This skill teaches effective communication with human developers
| Field | Description | Format |
|---|---|---|
| Communication Type | The type of developer communication (PR comment, issue response, technical explanation, status update, etc.) | String |
| Tone Assessment | Evaluation of message tone (respectful, specific, constructive) | Pass/Fail with notes |
| Blocking Status | Whether feedback is blocking or non-blocking |
| "Blocking" or "Non-blocking" |
| Message Content | The actual communication to send | Formatted text (Markdown) |
| References | Links to relevant code, issues, or documentation | List of URLs |
Identify the communication type - Determine if you are writing a PR comment, issue response, technical explanation, status update, or conflict resolution message.
Understand the human-AI communication differences - Recognize that human communication differs fundamentally from structured AI-to-AI message templates:
| Aspect | AI-to-AI Communication | Human Communication |
|---|---|---|
| Format | Structured JSON/templates | Natural language |
| Tone | Neutral, task-focused | Warm, respectful, contextual |
| Context | Explicit, complete | Often implicit, requires inference |
| Feedback | Direct status codes | Nuanced, face-saving |
| Timing | Immediate processing | Async, variable attention |
Use the decision tree - Navigate the decision tree below to select the appropriate reference document for your specific communication scenario.
Apply the key principles - Before drafting your message, review and apply all six key principles listed in the "Key Principles of Developer Communication" section.
Draft your message - Write your communication following the patterns and templates in the relevant reference document.
Run the pre-send checklist - Before sending, verify your message against the "Checklist: Before Sending Any Communication" to ensure quality and professionalism.
Send and monitor - Deliver the message through the appropriate channel and monitor for responses or follow-up needs.
Every developer you interact with is trying to do good work. Code that seems "wrong" may reflect constraints, legacy decisions, or knowledge you lack.
Instead of: "This approach is wrong" Use: "I noticed this pattern - was there a specific reason for this approach? I was thinking X might work because..."
Vague feedback wastes time and creates frustration. Always provide concrete examples.
Instead of: "This code could be cleaner"
Use: "Consider extracting lines 45-52 into a validateUserInput() function - it would make the login flow easier to test"
Clearly distinguish required changes from suggestions. Use explicit markers.
Blocking: "This will cause a null pointer exception when user is undefined"
Non-blocking: "Nit: Consider using const here instead of let"
Recognition builds trust and encourages best practices. Point out what's done well.
Example: "Nice job handling the edge case for empty arrays here - that would have been easy to miss"
Explain why something matters, not just what to change.
Instead of: "Use dependency injection" Use: "Using dependency injection here would let us mock the database in tests, reducing test runtime from 30s to 2s"
Is this about code you're reviewing?
├── YES → See pr-comment-writing.md
│ ├── Is it a blocking issue? → Request Changes
│ ├── Is it a suggestion? → Comment (non-blocking)
│ └── Is it praise? → Approve with comment
│
└── NO → Is this about an issue/ticket?
├── YES → See issue-communication.md
│ ├── Bug report? → Acknowledge, reproduce, respond
│ ├── Feature request? → Thank, set expectations
│ └── Question? → Answer or redirect
│
└── NO → Is this explaining technical decisions?
├── YES → See technical-explanation.md
│
└── NO → Is this a conflict or disagreement?
├── YES → See conflict-resolution.md
│
└── NO → Is this a progress/status update?
├── YES → See status-updates.md
│
└── NO → See templates-for-humans.md for general formats
Use when: Writing code review comments on Pull Requests
Contents:
Use when: Responding to bug reports, feature requests, or questions in issue trackers
Contents:
Use when: Explaining architecture, design decisions, or non-obvious code to humans
Contents:
Use when: Disagreeing with another developer's approach or resolving technical disputes
Contents:
Use when: Reporting progress, communicating blockers, or providing completion updates
Contents:
Use when: Writing PRs, commits, release notes, or migration guides for human readers
Contents:
| Situation | Wrong Tone | Right Tone |
|---|---|---|
| Code issue | "This is wrong" | "This might cause X - what if we tried Y?" |
| Suggestion | "You should do X" | "One option would be X - thoughts?" |
| Bug found | "You broke the build" | "The build is failing - looks like it's related to X" |
| Disagreement | "That won't work" | "I have concerns about X because of Y - how about Z?" |
| Confusion | "This doesn't make sense" | "Help me understand the reasoning behind X?" |
| Urgency | "Fix this now" | "This is blocking deployment - can we prioritize?" |
Copy this checklist and track your progress:
Wrong:
"This code is inefficient and poorly structured."
Right:
"I noticed this loop processes items sequentially. Consider using
Promise.all()for parallel execution - it could reduce the response time from ~500ms to ~100ms based on similar patterns elsewhere in the codebase."
"Nice catch on the null check at line 42 - that edge case would have caused issues in production. The error message is also very clear."
| Situation | Issue | Resolution |
|---|---|---|
| Misunderstood feedback | Developer responds defensively | Clarify intent, acknowledge their perspective |
| Unclear requirements | Developer delivers wrong implementation | Provide concrete examples and success criteria |
| Communication breakdown | No response for 48+ hours | Follow up with direct message, check availability |