Writing Feedback SKILL.md

This is the exact file agents read, including the credit header and licence notice. Save it as writing-feedback/SKILL.md.

---
name: writing-feedback
description: "Give useful feedback on documents: the purpose and reader first, review layers from structure and argument to evidence, clarity and style, a short summary, must-fix, should-fix and optional comments with location, reason and suggestion, tone adapted to the writer and a method for merging several reviewers. Use whenever someone needs to review a document, give feedback on a colleague's writing, check their own draft, review agency work or combine comments from several reviewers."
license: CC-BY-4.0
metadata:
  author: Afeez Adebayo
  author_url: https://afeezadebayo.com
  author_linkedin: https://www.linkedin.com/in/afeez-adebayo/
  author_x: https://x.com/za_icon
  source: https://afeezadebayo.com/skills-md/productivity/workplace-writing/writing-feedback/
  category: productivity
  subcategory: workplace-writing
  version: "1.0.0"
  created: "2026-10-10"
  updated: "2026-10-13"
---

# Writing Feedback

Feedback on documents often makes them worse. Reviewers rewrite sentences in their own style, leave dozens of small comments while missing the big problem, contradict each other, or say "looks good" without reading carefully. Writers then spend days resolving comments without knowing which matter. Useful feedback starts with the document's purpose, separates major issues from minor ones and tells the writer what to change and why.

This skill reviews documents and gives feedback in layers: whether the document achieves its purpose for its reader, structure and argument, evidence and accuracy, clarity and length, then style and typos last. It prioritises comments, explains the reason for each, suggests fixes rather than rewriting everything and adapts tone to the writer and relationship. It also helps writers handle feedback from several reviewers.

## Operating principles
1. **Purpose first.** Judge the document against what it is meant to do for its reader.
2. **Big before small.** Structure and argument before word choice and commas.
3. **Specific and kind.** Point to the exact passage, explain the problem and suggest a fix.
4. **Prioritise.** Mark must-fix, should-fix and optional comments.
5. **The writer owns the voice.** Suggest changes; avoid rewriting into the reviewer's style.

## Review layers
| Layer | Questions |
|---|---|
| 1. Purpose | Is it clear who it is for and what they should do? Does it achieve that? |
| 2. Structure | Is the main point first? Is the order logical? Is anything missing or unnecessary? |
| 3. Argument and evidence | Are claims supported? Are numbers right? Are risks and options fair? |
| 4. Clarity and length | Can a busy reader follow it? What can be cut? |
| 5. Style and accuracy | Tone, consistency, spelling, grammar, formatting, names and dates |

## When to use, and when not to
Use it to review colleagues' documents, give feedback as a manager, check your own draft before sending, review agency or freelancer work, or combine comments from several reviewers.

Don't use it to edit text line by line when the writer asked only for proofreading (`editing-tightening`), or to judge performance, which needs a separate conversation.

## Inputs
- The document.
- Its purpose and audience (ask the writer if not stated).
- What kind of feedback the writer wants: big picture, detailed or proofreading.
- The deadline and stage (early draft or near final).
- The relationship and tone preferred.

## Workflow

### Step 1. Ask what feedback is wanted
Early drafts need structure and argument; near-final drafts need accuracy and polish.

### Step 2. Read once without commenting
Understand the whole before marking anything.

### Step 3. Write the summary feedback
Two or three sentences: what works, the most important change, and whether it achieves its purpose.

### Step 4. Add prioritised comments
Must-fix (blocks the purpose), should-fix (improves it), optional (style). Each with location, problem, reason and suggestion.

### Step 5. Limit the number
For early drafts, five to ten meaningful comments beat fifty small ones.

### Step 6. Check tone
Specific, respectful and focused on the document, not the person.

### Step 7. Offer a next step
A short call for big changes, or a second review after edits.

## Comment format
```
[Must-fix] Section 2, paragraph 1
Problem: the recommendation appears on page 3; leaders may stop reading before it.
Why it matters: the decision is the purpose of this memo.
Suggestion: move the recommendation and cost to the first paragraph.
```

## Feedback summary example
```
This is a strong case with good data. The main change: put the
recommendation and cost first, because the directors will read the
first page closely and skim the rest. Three must-fix comments below;
the others are optional. Happy to talk it through.
```

## Handling feedback from several reviewers
1. Collect all comments in one place.
2. Group by issue; note conflicts.
3. Decide with the document owner: accept, adapt or decline, with a reason.
4. Resolve conflicts with the decider or by returning to the document's purpose.
5. Reply briefly to reviewers on major points.

## Vague versus useful comments
| Vague | Useful |
|---|---|
| This doesn't flow. | The jump from costs to hiring in paragraph 4 needs a sentence linking them. |
| Too long. | Sections 3 and 4 repeat the same data; keep the table in section 3 and cut section 4. |
| Not convincing. | The 30% saving has no source; add where it comes from or show the calculation. |
| Tone is off. | The second paragraph reads as blaming the finance team; describe the delay neutrally. |

## Checklist for reviewers
- [ ] I know the purpose and reader.
- [ ] The main point is clear in the first paragraph.
- [ ] The structure follows what the reader needs.
- [ ] Claims are supported; numbers match tables and sources.
- [ ] Options, risks and costs are fair.
- [ ] Nothing important is missing; nothing unnecessary remains.
- [ ] Tone suits the audience.
- [ ] Names, dates and figures are correct.

## Receiving feedback
Writers can make feedback easier to give: state the purpose and reader at the top, say what kind of feedback is wanted and by when, and ask one or two specific questions ("Is the recommendation convincing?"). Thank reviewers, explain any comments not taken, and keep a note of recurring feedback to improve future drafts.

## Feedback on AI-written drafts
AI-written drafts often look polished but may contain unsupported claims, generic phrases, repetition and invented details. Reviewers should check every figure and fact, cut filler and ask whether the document says anything the reader could not have guessed.

## Turnaround
Agree when feedback is due and keep to it; late feedback forces rushed edits. For short documents, a same-day review is ideal; for long ones, give the writer the top issues first and detailed comments later, so they can start on the changes that matter most while the rest is finished.

## Edge cases and judgement calls
| Situation | What to do |
|---|---|
| Document has no clear purpose | Make that the first and main comment |
| Writer is junior | More explanation, examples and encouragement |
| Senior author | Concise, direct comments focused on impact |
| Very late stage, big problems | Flag the top issue; agree what can change before the deadline |
| Agency or external work | Refer to the brief and acceptance criteria |
| Self-review | Wait a few hours, read aloud, run the layers in order |

## Handoffs to related skills
- Editing and cutting: `editing-tightening`
- Plain language: `plain-english`
- Staged writing: `writing-process`
- Team standards: `team-style-guide`
- Giving feedback in conversations: the Communication and Presentations skills

## Worked example
A manager was asked to review a six-page proposal the day before it went to leadership. Instead of 40 track changes, the review gave a three-sentence summary, three must-fix comments (move the ask and cost to page one, add a do-nothing option, correct a budget figure that did not match the table), four should-fix comments on clarity and a note that style was fine. The writer fixed the must-fix items in an hour, and the proposal was approved the next day.

## Common mistakes
- Rewriting the document in the reviewer's voice.
- Fifty minor comments and no summary.
- Vague feedback ("this doesn't flow").
- Commenting on typos in an early draft.
- Conflicting reviewers left unresolved.

## Using an AI agent
The agent can run the review layers, draft the summary and prioritised comments, check numbers against tables, merge feedback from several reviewers and flag conflicts. The reviewer adjusts tone and decides which comments to send.

## Self-check before you answer
- Is the document judged against its purpose and reader?
- Are comments prioritised with reasons and suggestions?
- Is there a short summary?
- Is the tone specific and respectful?

---
Created by Afeez Adebayo, Marketing, SEO & Growth Expert
Website: https://afeezadebayo.com
LinkedIn: https://www.linkedin.com/in/afeez-adebayo/
X: https://x.com/za_icon
Source: https://afeezadebayo.com/skills-md/productivity/workplace-writing/writing-feedback/

Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). You may copy, share and adapt this skill, including for commercial use, as long as you credit Afeez Adebayo and link to the source URL above. Keep this notice in any copy or adapted version.