google-doc-change-requests
Skill431 starsChanged 8 months agoMITView on GitHub
Turn a Google Doc of requested changes, downloaded as .docx, into an explicit change list — the visible text edits, the pending suggestions, and the decisions made in comment threads — before implementing any of it. Use this skill whenever the user hands over a .docx (or any Google Docs export) of team feedback, edits, or requested changes to copy, layout, or behavior.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- commitSkill
- course-update-reconSkill
- feature-specSkill
- prepare-prSkill
- review-prSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
Read all three. all.md shows where each suggestion and comment sits in the flow.
- Very specific: line 47
If it reports no comments and no suggestions, the doc is plain and final.md is the whole story.
- Very specific: line 56
Write a ledger (a markdown table in the scratchpad, or a .claude/ plan file if the work will span sessions) with one row per item, from …
- Distinctive: line 89
Behavior changes and open threads: ask, in one message that lists them with a recommendation each.
- Very specific: line 103
Add a SCREENSHOT=-gated screenshot harness first if the feature lacks one (see Strategy A in .claude/skills/prepare-pr/SKILL.md).
- Very specific: line 106
After each change: yarn build (copy edits need the i18n export it runs), then SCREENSHOT=NN_<label> bundle exec rspec <harness spec>.
- Very specific: line 111
Commit with the commit skill, git commit --only <paths>, so nothing else in the tree rides along.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Google Doc change requests
A Google Doc that a team has been editing carries three layers, and only one of them is the visible text:
- The text — what the page says once every pending suggestion is accepted.
- Suggestions — Google Docs "suggesting mode" edits, exported as tracked
changes (
w:ins/w:del), each with an author and a timestamp. Some are finished; some were mid-edit when the file was downloaded. - Comments — the margin discussion, exported to
word/comments.xml, each anchored to a run of text. This is where decisions live: "editor's?", "Agreed, let's point to that", "they should be routed back to pick another claim", "feel free to delete".
pandoc file.docx -t gfm gives you layer 1 only: its default
--track-changes=accept applies every suggestion silently, and it drops every
comment. Working from that output alone misses whatever the team decided in
the margins. (It happened: four comment threads on the Fact Verification
exercise edits were missed on the first pass in September 2026, and one
half-finished suggestion had deleted a word from a sentence.)
Work through the phases in order. Do not start implementing before Phase 3.
Phase 1: Extract all three layers
Work in the session scratchpad. <file> is the .docx the user provided.
mkdir -p "$SCRATCH/docx"
# 1. The final text, with images extracted (what the doc would say if every
# pending suggestion were accepted).
pandoc "<file>" -t gfm --extract-media="$SCRATCH/docx" -o "$SCRATCH/docx/final.md"
# 2. Everything inline: insertions/deletions with author and date, and comment
# anchors as spans. Use -t markdown (not gfm) so the spans keep attributes.
pandoc "<file>" --track-changes=all -t markdown -o "$SCRATCH/docx/all.md"
# 3. The ledger of comment threads (with anchored text) and suggestions.
bin/docx-changes "<file>"Read all three. all.md shows where each suggestion and comment sits in the
flow; bin/docx-changes gives the threads with replies, authors and dates.
If it reports no comments and no suggestions, the doc is plain and final.md
is the whole story.
Images: pandoc extracts them to $SCRATCH/docx/media/. Note each one's
dimensions; team screenshots are usually full browser windows and will need
cropping to the passage that makes their point (Phase 4).
Phase 2: Build the change ledger
Write a ledger (a markdown table in the scratchpad, or a .claude/ plan file
if the work will span sessions) with one row per item, from four sources:
- Text differences — compare
final.mdagainst the current copy in the app (config/locales/en.ymletc.) and list each difference, quoting both sides. Copy from the doc is applied verbatim, typos included; note a suspected typo in the ledger rather than fixing it. - Suggestions — one row each, from
bin/docx-changes. Mark any whose result reads wrong (a lone deleted word, a sentence that no longer parses), and any timestamped within an hour or so of the download: those may have been mid-edit. Do not treat a pending suggestion as final if it garbles the text; put it to the user. - Comment threads — one row each: anchored text, the thread (with replies and reactions), and a classification: decided copy change (someone agreed), decided behavior change, open question (no reply, or a question nobody answered), or note to the operator ("feel free to delete"). A behavior change is never implemented on the strength of a comment alone; see Phase 3.
- Doc markers and omissions — all-caps notes such as "SCREENSHOT OF VERIFIED" are placement notes, not copy; the doc usually walks one path through a flow, so anything in the current UI it doesn't mention (a conditional question, an alternate branch) is keep unless told, flagged.
Also note where the doc contradicts itself or its screenshots (a caption that quotes different wording than the screenshot shows, a link the doc says to replace but a sentence that still describes the old target).
Phase 3: Confirm scope before building
Show the user the ledger — compactly: what will be applied verbatim, what needs a decision, what is being left alone. Then:
- Copy changes from the doc, including agreed comment threads: proceed.
- Behavior changes and open threads: ask, in one message that lists them with a recommendation each. Different readings lead to materially different work, so this is worth the round trip.
- Missing copy (a heading the doc marks but doesn't write, alt text, a
new sentence a behavior change needs): never write it. Leave a
[PLACEHOLDER - <what the copy needs to say>]marker per CLAUDE.md, and list the placeholders for the user to fill. Where an existing operator-approved string already says the right thing (a button label, a link text), reuse it.
Phase 4: Implement in reviewable pieces
The user usually wants to see each change on its own. Work as a series of small commits, one per ledger group, each with before/after screenshots:
- Add a
SCREENSHOT=-gated screenshot harness first if the feature lacks one (see Strategy A in.claude/skills/prepare-pr/SKILL.md). Commit it as the first, visually neutral commit; capture the baseline asSCREENSHOT=00_master. - After each change:
yarn build(copy edits need the i18n export it runs), thenSCREENSHOT=NN_<label> bundle exec rspec <harness spec>; keep everytmp/screenshots/NN_<label>/so each commit's before is the previous commit's after. Delete the stray<spec>__*.pngfiles the global screenshot hook adds alongside. - Commit with the
commitskill,git commit --only <paths>, so nothing else in the tree rides along. - Images from the doc: crop to the passage that makes the point (ImageMagick
-crop; join two strips with a hairline when the point spans a page), encode as WebP at native resolution, show at natural width rather than as two-up thumbnails, and link each to what it shows (a permalink to the article revision pictured; the source). If a screenshot can't be cropped into legibility, say so and offer to retake it (a PDF viewer's find bar can be reproduced headless with pdf.js + Selenium). - Present the iterations together: a before/after gallery per commit (an
Artifact, or
tmp/screenshots/gallery.html) is what the user reviews.
Phase 5: Report
Close with, in this order: what was applied (commit per ledger row), what
was deliberately not built and why, the placeholders awaiting copy (grep -n
"\[PLACEHOLDER" config/locales/en.yml), and the doc oddities preserved
verbatim. Keep the ledger's open rows in the PR's "Open questions" section.
Gotchas
pandocdefaults:--track-changes=accept, comments dropped. Always run the--track-changes=all -t markdownpass andbin/docx-changes.- Google Docs exports a reply as a separate comment whose range opens inside
the parent's;
bin/docx-changesuses that nesting to show threads. - A suggestion's author and timestamp tell you who decided and when; a deletion dated minutes before the download is probably unfinished.
- Doc text and doc screenshots can disagree (the doc quoted "started"; the screenshot said "launched"). Decide with the user which the app follows.
- The live Wikipedia article behind an example may already have changed;
link permalinks (
oldid=) to the revision the screenshot shows, found via the revision history, not the current page. - Sources the team screenshotted may be paywalled (JSTOR). Link them anyway when the team wants students to see where the source lives, and ask the user for the file if a retake is needed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

