| 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"} |
Activation Contract
Load whenever writing a comment another human will read:
- GitHub PR or issue comments
- Review feedback and requested changes
- Slack, Discord, or async project updates
Hard Rules
- Start with the actionable point — never recap the PR before giving feedback
- Explain the technical reason when asking for a change — "because X" is required
- Never use "you should" — use "this would" or "consider"
- Write in the thread/user language. Spanish threads: Rioplatense/voseo (
podés, tenés, fijate, dale)
- No em dashes — use commas, periods, or parentheses
Decision Gates
| Comment intent | Tone / format |
|---|
| Blocking issue (must fix before merge) | Direct, one paragraph, state the risk |
| Non-blocking suggestion (nice to have) | Prefix with "nit:" or "optional:" |
| Question / clarification needed | Single question, no assumption of wrongness |
| Positive reinforcement | One sentence, specific about what worked |
| Pile-on (already covered by others) | Skip — comment on highest-value issue only |
Comment Formula
<Direct observation or request>
<Why it matters — technical reason>
<Concrete next action>
Examples
Buenísimo el enfoque. Acá separaría este cambio en otro commit porque mezcla la validación con el wiring de UI.
Eso le baja carga al reviewer y hace que el rollback sea más claro si falla la integración.
nit: este nombre podría ser más explícito — `handleSubmit` hace demasiado, `validateAndSubmitForm` dice mejor lo que pasa.
Output Contract
Return a comment following the 3-part formula:
- Direct observation (what you see)
- Why it matters (technical consequence)
- Concrete next action (what to do)
Maximum 3 short paragraphs or a tight bullet list. No preamble.
Gotchas
- Starting with "I think..." or "Maybe..." hedges the feedback into ambiguity — be direct
- "just" and "simply" minimize valid effort — remove them ("just add a test" = dismissive)
- Writing multiple change requests in one comment — split into separate comments so each can be resolved independently
- Missing the "why" on a requested change makes it look like a style preference, not a technical decision
Commands
gh pr view <PR_NUMBER> --json title,body,additions,deletions,changedFiles
