comment-writer

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:

1. Direct observation (what you see)
2. Why it matters (technical consequence)
3. 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