7 added, 7 removed. Audit A to A.
---
name: comment-writer
description: "Write warm, direct collaboration comments. Trigger: PR feedback, issue replies, reviews, Slack messages, or GitHub comments."
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
## When to Use
Load this skill whenever you write a comment that another human will read.
Use it for:
- GitHub PR or issue comments.
- Review feedback and requested changes.
- Maintainer replies.
- Slack, Discord, or async project updates.
## Voice Rules
| Rule | Requirement |
|------|-------------|
| Be useful fast | Start with the actionable point. Do not recap the whole PR before feedback. |
| Be warm and direct | Sound like a thoughtful teammate, not a corporate bot. |
| Keep it short | Prefer 1 to 3 short paragraphs or a tight bullet list. |
| Explain why | Give the technical reason when asking for a change. |
| Avoid pile-ons | Comment on the highest-value issue, not every tiny preference. |
- | Match thread language | Write in the thread/user language and follow the active persona/tone. Do not force regional Spanish; use voseo only when the active persona or existing thread does. |
+ | Match target context language | Write in the target context language by default: Spanish issue/thread -> Spanish comment, English issue/thread -> English comment, mixed context -> target message language. If the user explicitly requests a language or tone, follow that request. Do not use the active persona as the source of truth for public comments. For Spanish comments, use neutral/professional Spanish by default unless the user or target context clearly calls for regional tone. |
| No em dashes | Use commas, periods, or parentheses instead. |
## Comment Formula
```text
<Direct observation or request>
<Why it matters, only if needed>
<Concrete next action>
```
## Examples
### Request change
```markdown
- Buenísimo el enfoque. Acá separaría este cambio en otro commit porque mezcla la validación con el wiring de UI.
+ Good approach overall. I'd split this into a separate commit because it mixes validation logic with UI wiring.
- Eso le baja carga al reviewer y hace que el rollback sea más claro si falla la integración.
+ That keeps the reviewer's focus narrower and makes rollback cleaner if the integration fails.
```
### Approve with a note
```markdown
- Está bien encaminado y el scope se entiende rápido.
+ Approved. The scope is clear and the change is well-contained.
- Dejo aprobado. Para el próximo PR, agregá el link al anterior y al siguiente así la cadena queda navegable.
+ For the next PR, add links to the previous and following PRs so the chain stays navigable.
```
### Ask for split
```markdown
- Este PR supera el presupuesto de 400 líneas cambiadas, así que necesitamos dividirlo o justificar `size:exception`.
+ This PR exceeds the 400-line budget, so we need to split it or justify `size:exception`.
- Mi sugerencia: primero foundation + tests, después integración, después docs. Así cada review tiene inicio y fin claros.
+ Suggested order: foundation + tests first, then integration, then docs. That gives each review a clear start and end.
```
## Commands
```bash
# Inspect a PR before writing review feedback
gh pr view <PR_NUMBER> --json title,body,additions,deletions,changedFiles
```