Review Comments Resolver Skill
A document with forty comments induces either capitulation (accept-all, the doc becomes committee mush) or avoidance (the comments age until the doc ships around them). Resolution is triage: most comments are mechanical (accept in batch, thank in aggregate), some are substantive-and-right (accept with the change named), some deserve push-back (drafted politely, decided by the doc's owner), and a few contradict each other — those aren't the author's to split; they get reconciled by naming the conflict to its parties. Every comment ends closed, and the doc stays the author's.
What This Skill Produces
- The triage table — every comment sorted: accept-mechanical / accept-substantive / push-back / conflict / out-of-scope
- The batch plan — mechanical fixes applied in one pass, resolved with one courtesy note
- The push-back replies — drafted: the reviewer's point honored, the decision explained, the owner's call made
- The conflict reconciliations — contradicting reviewers named to each other with the author's recommendation
- The closure sweep — nothing left dangling; the resolved-vs-declined summary if the doc's approver wants it
Required Inputs
Ask for these if not provided:
- The comments and the doc — the actual comment set; triage reads them, not a summary of them
- The authority map — whose comments are directives (the approver), whose are advice (peers), whose are taste — the same words resolve differently by author; "consider rewording" from the VP and from a peer are different speech acts
- The doc's non-negotiables — what the author is defending (the recommendation, the scope, the tone) — push-back needs a spine to push from
- The deadline — a closing date makes "let's discuss" comments convert to decisions instead of orbit
Framework: The Resolution Rules
- Triage before touching: read all comments first, sort into the five bins — resolving in document-order mixes typo fixes with strategy debates and exhausts the author by page three. The bins get processed cheapest-first: mechanical batch, then substantive accepts, then push-backs, then conflicts.
- Mechanical means batch: typos, clarity nits, formatting — apply all, resolve all, one aggregate thank-you. Individually replying "good catch!" forty times is a day lost to etiquette.
- Push-back is a reply, not a silence: declining a comment requires saying so — "Kept as-is: the recommendation stays unhedged because [reason]; happy to discuss" — because silently-unaddressed comments return in the next review round with reinforcements. The author owns the call on advice-comments; directive-comments that the author disagrees with get escalated as a conversation, not quietly overridden.
- Conflicts get named, not averaged: when reviewer A wants detail added and reviewer B wants the section cut, the author doesn't split the difference into mush — the conflict is surfaced ("A and B, you're asking for opposites here — my recommendation is B's cut because [header test]; A, does the appendix satisfy the need?") and decided once, on the record.
- The sweep closes everything: every comment ends in resolved / replied / escalated — a doc with lingering open comments reads as contested, and approvers notice. The closing summary ("38 taken, 4 declined with reasons, 2 conflicts resolved with A/B") converts the review round into a credibility artifact.
Output Format
Comment Resolution: [doc] — [N] comments
The Triage
| # |
Comment (gist) |
From |
Bin |
Action |
Batch Pass
[The mechanical list → applied · the aggregate note]
Push-Backs (drafted)
[Per comment: the honor-then-decide reply, verbatim]
Conflicts (reconciled)
[Per pair: the naming message + the author's recommendation]
The Sweep
[All closed · the summary line for the approver]
Quality Checks
Anti-Patterns
1---2name: review-comments-resolver3description: Resolve a document's forty review comments systematically — triage by type (accept, push back, conflict, out-of-scope), batch the mechanical fixes, draft the disagreement replies, and reconcile reviewers who contradict each other. Use when asked work through these review comments, two reviewers want opposite things, close out the feedback on this doc, or which comments do I actually have to take. Produces the comment triage, the batched fixes, the push-back replies, the conflict reconciliations, and the closure sweep.4---5
6# Review Comments Resolver Skill
7
8A document with forty comments induces either capitulation (accept-all, the doc becomes committee mush) or avoidance (the comments age until the doc ships around them). Resolution is triage: most comments are mechanical (accept in batch, thank in aggregate), some are substantive-and-right (accept with the change named), some deserve push-back (drafted politely, decided by the doc's owner), and a few *contradict each other* — those aren't the author's to split; they get reconciled by naming the conflict to its parties. Every comment ends closed, and the doc stays the author's.
9
10## What This Skill Produces
11
12- **The triage table** — every comment sorted: accept-mechanical / accept-substantive / push-back / conflict / out-of-scope
13- **The batch plan** — mechanical fixes applied in one pass, resolved with one courtesy note
14- **The push-back replies** — drafted: the reviewer's point honored, the decision explained, the owner's call made
15- **The conflict reconciliations** — contradicting reviewers named to each other with the author's recommendation
16- **The closure sweep** — nothing left dangling; the resolved-vs-declined summary if the doc's approver wants it
17
18## Required Inputs
19
20Ask for these if not provided:
21- **The comments and the doc** — the actual comment set; triage reads them, not a summary of them
22- **The authority map** — whose comments are directives (the approver), whose are advice (peers), whose are taste — the same words resolve differently by author; "consider rewording" from the VP and from a peer are different speech acts
23- **The doc's non-negotiables** — what the author is defending (the recommendation, the scope, the tone) — push-back needs a spine to push from
24- **The deadline** — a closing date makes "let's discuss" comments convert to decisions instead of orbit
25
26## Framework: The Resolution Rules
27
281. **Triage before touching:** read all comments first, sort into the five bins — resolving in document-order mixes typo fixes with strategy debates and exhausts the author by page three. The bins get processed cheapest-first: mechanical batch, then substantive accepts, then push-backs, then conflicts.
292. **Mechanical means batch:** typos, clarity nits, formatting — apply all, resolve all, one aggregate thank-you. Individually replying "good catch!" forty times is a day lost to etiquette.
303. **Push-back is a reply, not a silence:** declining a comment requires saying so — "Kept as-is: the recommendation stays unhedged because [reason]; happy to discuss" — because silently-unaddressed comments return in the next review round with reinforcements. The author owns the call on advice-comments; directive-comments that the author disagrees with get escalated as a conversation, not quietly overridden.
314. **Conflicts get named, not averaged:** when reviewer A wants detail added and reviewer B wants the section cut, the author doesn't split the difference into mush — the conflict is surfaced ("A and B, you're asking for opposites here — my recommendation is B's cut because [header test]; A, does the appendix satisfy the need?") and decided once, on the record.
325. **The sweep closes everything:** every comment ends in resolved / replied / escalated — a doc with lingering open comments reads as contested, and approvers notice. The closing summary ("38 taken, 4 declined with reasons, 2 conflicts resolved with A/B") converts the review round into a credibility artifact.
33
34## Output Format
35
36# Comment Resolution: [doc] — [N] comments
37
38## The Triage
39| # | Comment (gist) | From | Bin | Action |
40|---|---|---|---|---|
41
42## Batch Pass
43[The mechanical list → applied · the aggregate note]
44
45## Push-Backs (drafted)
46[Per comment: the honor-then-decide reply, verbatim]
47
48## Conflicts (reconciled)
49[Per pair: the naming message + the author's recommendation]
50
51## The Sweep
52[All closed · the summary line for the approver]
53
54## Quality Checks
55
56- [ ] Every comment landed in exactly one bin before any fix was made
57- [ ] The authority map informed the bins — directives and advice resolved differently
58- [ ] Every decline has a stated reason in a reply
59- [ ] No conflict was averaged into mush — each was named and decided
60- [ ] Zero comments remain open at the end
61
62## Anti-Patterns
63
64- [ ] Do not accept-all — forty reviewers produce committee prose; the author is the editor
65- [ ] Do not resolve in page order — bins first, or the strategy debates drown in typo fixes
66- [ ] Do not decline silently — unaddressed comments respawn with allies
67- [ ] Do not split contradictory feedback down the middle — mush satisfies neither reviewer and weakens the doc
68- [ ] Do not leave "let's discuss" comments orbiting — the deadline converts them to decisions
gabrielmoreira