yacosta738/agent-harness/async-collaboration-comments

Async Collaboration Comments

Overview

Write comments that are warm, direct, and useful fast. The reader should know the point, the reason, and the next action without decoding corporate filler.

Pressure Scenario

Without this skill, an agent writes a long generic reply, piles on minor nits, or sounds like a bot. The comment creates more coordination cost than it removes.

With this skill, the agent writes one focused comment in the thread language, explains the technical why when needed, and gives a concrete next action.

When to Use

Use when drafting:

• GitHub PR or issue comments.
• Review feedback or requested changes.
• Linear updates.
• Slack, Discord, Notion, or async project replies.

Use gh-address-comments when you need to inspect unresolved GitHub review threads before drafting. Use receiving-code-review when processing feedback directed at our code.

Voice Rules

Comment Formula

<Direct observation or request>
 
<Why it matters, only if needed>
 
<Concrete next action>

Examples

Request a change

Good direction. I would separate the validation from the UI wiring here, because the PR currently
mixes two different decisions.
 
That lowers the review load and makes the rollback clearer if the integration fails.

Ask for a split

This PR is already above a reasonable review budget. Let's split it before going further.
 
My suggestion: foundation with tests first, then integration, then docs. That way each review has a
clear start and end.

Approve with note

This is on the right track and the scope is easy to follow.
 
Approved. For the next PR, link the previous and the next one so the chain stays navigable.

Common Mistakes

• Do not recap the whole PR before giving the point.
• Do not write five comments when one higher-level comment solves the issue.
• Do not soften a real blocker until it sounds optional.
• Do not post externally unless the user explicitly asked for that write action.