The packt-prose user guide
packt-prose reads a chapter in Word format, tells you where it departs from Packt house style, and writes copyedits into the file as tracked changes. It runs on your own laptop and it always works on a copy: the file you hand it is never modified.
This guide assumes you can copy a command into a terminal window and open a file in Word. Nothing else.
What it does, and what it does not
It does five things:
- reports where a manuscript departs from house style;
- applies the mechanical corrections that need no decision from you;
- puts the manuscript into the house Word styles, so every deliverable looks the same whatever template the draft arrived in;
- checks a set of proposed edits — yours, Claude's, or a supplier's — before any of them reach the document;
- runs a whole copyedit in one command, asking a language model for the edits that need judgement and checking every one of them.
The limits matter as much as the capabilities.
- It never publishes anything. When it changes something it writes a
new
.docxfile next to the one you gave it, and stops. There is no upload, no notification, and nothing further along the production line sees the file until you send it on. - Every change arrives as a tracked change. Nothing is quietly rewritten. You open the output in Word and accept or reject each change one at a time, exactly as you would with a freelancer's file. Where an explanation belongs with a change — or with something deliberately left alone — it arrives as an ordinary Word comment in the margin.
- It will not change code, numbers, or links. Code listings, inline identifiers, file names, URLs, and figure placeholders are marked off limits before any edit is considered. An edit that would alter a figure, drop a URL, or retype an identifier is refused rather than applied.
- It does not restructure a chapter. It will tell you that a figure is not announced in the prose, or that one list punctuates half its items as sentences. It will not convert bullets to prose, add headings, or reorder sections. That is developmental work and it stays with a person.
- It has no opinion it cannot cite. Every finding comes from a named rule that cites the section of the house style behind it. The readable report shows both, so you can look a finding up and disagree with it.
Its own judgements are deterministic. The house-style report, the mechanical fixes, and every safety check are the same on the same file every time, on any machine. Nothing there consults a model.
A model only enters when one drives the tool — Claude working through the packt-prose skill — and then only on one side of the line: it proposes, and the same deterministic checks decide what reaches the document. What cannot vary is what is allowed through.
Before you start
Install the tool once, following Installing packt-prose. Then check it is healthy.
The last line should read No problems found. The tool is ready to use.
If it does not, the install page has a section for every message you are
likely to see.
Work in the folder your chapter is in, so you can refer to the file by name. Every command below assumes that.
Look at a chapter before anything else
review is one read that answers what a copyedit needs to know: what kind
of document this is, how big it is, what the findings look like grouped by
rule, and whether anything blocks writing. Every example in this guide is
the real output of the tool on a real submitted chapter.
chapter.docx
reads as chapter, so the default profile is in use
prose words 5222
suggested 130 edits — professionals land 20-35 per 1,000 words; far below this usually means findings went unfixed
findings 12 error, 51 warning, 211 advice
mechanical 9 fixes needing no judgement
styles 649 unstyled, 665 to re-style, 18 need a person
rule severity n fix first example
packt.mech.smart-quotes advice 95 0 "'" (p2)
packt.advice.passive advice 51 0 "is to split:" (p1)
packt.caps.headings warning 16 0 "The Orchestrator Role" (p15)
packt.doc.bold-emphasis error 12 0 "Chapter 6: Coordinating Multiple Agents" (p0)
packt.advice.referent warning 8 0 "It has" (p10)
packt.voice.first-person warning 5 0 "we've" (p3)
…
It also writes two files as a side effect — the chapter JSON every later command reads, and the mechanical-fix plan — so the rest of the workflow never re-parses the document.
To read the manuscript itself as the tool sees it, ask for the text view: one line per paragraph, with its number and what the paragraph is.
[0|P] Chapter 6: Coordinating Multiple Agents
[1|P] Every system that grows complex enough eventually needs to split its responsibilities. A single agent handling…
[5|P] TIP Before splitting a single agent into multiple agents, write down the exact interaction protocol between…
[6|H1] Assigning Roles Across Agents
And to re-read chosen paragraphs precisely — exact text, tag, and the
findings that sit on them — use show:
1. Get a house-style report on a manuscript
Use this when a draft arrives and you want to know what state it is in before you commit time to it. Nothing is written to the manuscript.
- Run the check.
- Read the findings. Each line gives the file, the paragraph number, the position inside that paragraph, how much the finding matters, and what it is.
chapter.json:0:0 error: Do not use bold for emphasis in prose. Bold is only for a bullet lead-in term followed by a colon.
chapter.json:0:0 warning: Reference a chapter as "Chapter N, Title", with the title in italics. (found "Chapter 6:")
chapter.json:1:426 advice: This reads as passive. Naming who or what acts is usually clearer.
chapter.json:2:135 advice: This sentence leans on its conjunction. Drop the "And", or turn the "But" into "However,".
chapter.json:3:81 warning: Write to the reader in the second person: the reader is "you", and the author has no pronoun. (found "we've")
- Read the last line, which is the total.
Numbers like these are normal for a raw draft, and most of the volume
is advice. To work rule by rule instead of line by line, ask for the
one-line-per-rule summary (--summary), a single rule's findings
(--rule packt.caps.headings), or only the confident tiers
(--severity warning). --suggest stubs.json turns the judged rules'
findings into ready-to-curate edit stubs.
- For anything longer than a few findings, ask for the readable version instead and save it to a file.
That report groups the findings by rule, because the same rule firing twenty times is one decision to make rather than twenty. It opens in any text editor, and it pastes into an email or a review note.
# House style report
Profile **default**. 112 findings: 4 errors, 25 warnings, 83 advice.
## packt.mech.em-dash (4)
Remove the dash. Use a comma, a semicolon, parentheses, or split the sentence. (found " – ")
error · house style: STYLE_ANALYSIS §4 Punctuation
| Paragraph | Text |
| --- | --- |
| 61 | Figure 13.1** – **A sample output from the loade… |
| 106 | Figure 13.2** – **A boxplot output from the load… |
| 115 | Figure 13.3** – **A sample output to inspect the… |
| 135 | Figure 13.4** – **A diagram showing the impact o… |
The paragraph numbers count every paragraph in the file from the top, including empty ones, so they will not match anything Word shows you. Use the quoted text to find the place.
2. Apply the fixes that need no decision
A few corrections have exactly one right answer: 32GB becomes 32 GB,
IO becomes I/O, behaviour becomes behavior, an introductory phrase
gets its comma. Applying those by hand is a waste of an editor's
afternoon, so the tool will do them for you.
- Look at what it would do, without writing anything.
5 mechanical fixes are available in chapter.docx (profile default):
paragraph 0 packt.mech.intro-comma
"By default" → "By default,"
paragraph 0 packt.mech.unit-space
"32GB" → "32 GB"
paragraph 0 packt.mech.io
"IO" → "I/O"
paragraph 2 packt.consist.us-spelling
"behaviour" → "behavior"
paragraph 2 packt.words.to
"in order to" → "to"
Run again without --dry-run to write them as tracked changes.
- Write them into a new file.
5 mechanical fixes written to chapter_fixed.docx as tracked changes.
These are the fixes that need no judgement. Run lint on the result to see what is left for an editor or a model.
- Open
chapter_fixed.docxin Word and review the tracked changes as you would anyone else's, as described under Reviewing the tracked changes below.
If you want the changes attributed to you rather than to the tool, add your name.
Autofix is deliberately narrow: seventeen rules out of ninety. Some of
that is caution about context, and some of it is evidence. Measured across
403 Packt books, editors keep several of the forms the house style prefers
far more often than they change them — e.g. was kept 436 times against
65 replacements, utilization 55 times against one — so those rules
report and suggest, and a person decides. packt-prose rules lists which
is which, with the numbers.
Put the manuscript into house styles
Most drafts arrive with no Word styles at all, or in another template's. The styles pass classifies every paragraph — body, headings, lists, code, captions, callouts — and re-styles the confident calls as tracked paragraph revisions, leaving the unclear ones for you. Start with the report, which writes nothing:
chapter.docx
paragraphs 740
unstyled 649
to re-style 665
needs a person 18
missing styles H1-Section, H2-Heading, L-Bullets, P-Callout, P-Regular, SC-Source
what would change:
555 SC-Source — every run in the paragraph is monospaced
70 P-Regular — the paragraph is a sentence with no style
24 H2-Heading — "heading 2" is the house style "H2 - Heading" under another name
6 P-Callout — the paragraph is shaded and announces itself as a tip or note
left for a person:
paragraph 13 — the paragraph is shaded like a callout but does not announce itself as one; needs a person
"[DIAGRAM] Three boxes in a horizontal row labeled 'Planner A…"
Every decision states its evidence, and "needs a person" is a real answer:
those paragraphs are listed for you rather than guessed at. The style pass
is a production task on its own request: packt-prose styles apply for a
styles-only job, or --styles on an apply when one deliverable needs the
style layer and an edit list in a single write. A copyedit runs neither —
extraction classifies the confidently mis-styled paragraphs for judging,
and the mis-styled list goes in the copyedit's report for production.
The pass does more than swap style names, and each extra is reported:
- The look is uniform across deliverables. Where the manuscript
arrived defining a house style with its own formatting, the definition
is rewritten to the catalog's, and the report names each one under
stylesRedefined. - Hand formatting comes off re-styled furniture. An author's orange 20pt chapter line or hand-shaded tip box loses that formatting as tracked revisions, so the house style actually shows. Formatting on only some of a paragraph's words is treated as deliberate emphasis and kept.
- The chapter opening is reshaped. A first line reading
Chapter 6: Coordinating Multiple Agentsbecomes the number in its ownHS - ChapterNumberparagraph and the bare title inHS - ChapterTitle— the shape copyedited chapters are delivered in — all as tracked changes a reviewer can reject.
683 paragraphs re-styled in the same pass.
The chapter opening was reshaped: "6" now sits in its own HS - ChapterNumber paragraph and "Coordinating Multiple Agents" in HS - ChapterTitle, all tracked.
53 re-styled furniture paragraphs had hand formatting cleared (76 runs, tracked); --json lists each paragraph and what came off.
3. Check a copyedit somebody else produced
When Claude copyedits a chapter it hands you an edit list: a file that says, for each change, which paragraph it belongs to, the exact words it replaces, and what it replaces them with. A supplier's tooling may give you one in the same form. Before any of it goes near the manuscript, check it.
- Run every proposed edit past the safety checks.
If everything is sound you get one line.
If something is not sound you get the reasons, all of them at once, for each edit that failed. These are three real refusals:
edit 2 (paragraph 53) rejected:
quoted: "the pipeline stalls, and the user waits"
replacement: "the pipeline stalls and the user waits for 90 seconds"
✗ find_missing: "the pipeline stalls, and the user waits" does not appear in paragraph 53; quote the paragraph exactly
✗ entity_drift: the replacement introduces a number that is not in the original: "90"
edit 3 (paragraph 3) rejected:
quoted: "no such sentence appears here"
replacement: "anything"
✗ find_missing: "no such sentence appears here" does not appear in paragraph 3; quote the paragraph exactly
✗ collapsed_replace: 5 words would become 1, which is usually a misalignment rather than an edit
0 of 3 edits passed the gates.
1 of 1 comments can be anchored.
- Ask whether the edit has flattened the author's voice. This is measured against what Packt copyeditors actually did to real books, not against a guess.
Author voice, before and after editing:
before after change
words 5082.00 5095.00 0%
mean sentence length 17.52 17.57 0%
contractions per word 0.02 0.02 -0%
"we" per 1,000 words 0.98 0.98 -0%
"you" per 1,000 words 7.48 7.46 -0%
exclamation marks 0.00 0.00 0%
questions 13.00 13.00 0%
hedges per 1,000 words 2.16 2.16 -0%
passive sentences 0.15 0.15 0%
Nothing looks out of place: every measure moved the way a professional copyedit moves it.
edit-list voice accounting (39 edits):
contractions expanded 0 (0 rule-backed)
contractions introduced 0 (0 rule-backed)
pronoun shifts 0 (0 rule-backed)
hedges removed 0 (0 rule-backed)
When a measure has moved much further than a copyedit usually moves it,
you get told which one and by how much. Those are questions to ask, not
faults: a book with its own house voice, or a chapter that genuinely
needed heavy work, shows up here too. Each register shift is counted
twice — in total, and how much of it a named house rule demanded. A
first-person conversion carrying packt.voice.first-person on every
edit is the point-of-view policy being enforced, at any volume; the
shifts that flag are the ones no rule backs.
- Write the edits into the manuscript as tracked changes.
--mechanicalfolds the mechanical fixes into the same write, so the document is written exactly once.
packt-prose apply -i chapter.docx --chapter chapter.json \
--edits edits.json -o chapter_CE.docx --mechanical
41 tracked changes written to chapter_CE.docx, attributed to "Packt CE".
7 mechanical fixes were already covered by one of your edits, so they were not planned twice:
paragraph 8: "Role" (packt.caps.hyphenated-compound)
…
24 formatting requests applied, touching 28 runs, as tracked format revisions.
7 comments written alongside them.
No edits were refused.
- Read back what the output carries in its margins — every comment, who wrote it, and the words it marks:
7 comments in chapter_CE.docx.
paragraph 25, by Packt CE
on: "described in their 2024 technical reports"
Which reports are these? The orchestrator/subagent separation most readers
will be able to find is in Anthropic's engineering blog posts rather than
anything titled a technical report. A title or link here lets the reader
and the technical reviewer check the specific finding…
If the copyedit arrives as a Word file rather than an edit list, there is no edit list to check. Run the house-style report on it as in section 1, and compare the two documents directly for voice.
How to read a report
Every finding carries one of three levels, and they are not equally confident.
| Level | What it means | How much to trust it |
|---|---|---|
| error | A house rule with no exceptions. | Act on it. |
| warning | A rule that holds unless the sentence says otherwise. | Read the sentence, then act. |
| advice | A candidate for you to judge. | Your call entirely. |
Advice is a suggestion, never an instruction. The tool is deliberately cautious about telling an editor what to do with a sentence, so anything that depends on meaning, rhythm, or the author's intent arrives as advice and stops there. A chapter with eighty pieces of advice is not a bad chapter — but a copyedit that answers none of them was not a copyedit. The expectation for every severity is fix-or-decline: a finding becomes a tracked edit unless the editor can name the reason it should not (the fix would change meaning, the rule misread the sentence, the answer needs the author), and the count of findings is never the reason. A rule broken two hundred times is two hundred edits.
Two things follow from how the checks are built, and it is worth knowing both.
- The mechanical rules are reliable and narrow. Units, spellings, product casing, compound words, Latin abbreviations, one term per concept: these are checked against fixed lists, so they are right when they fire and they fire every time. What they do not cover is anything requiring judgment.
- The advisory checks are heuristics. Passive voice, missing referents, comma splices, over-long sentences, missing articles, and capitalization of concepts are recognized by pattern, using curated word lists rather than an understanding of English. They miss things, and they occasionally flag something correct — a proper noun read as a capitalized common noun is the usual case. In one real chapter the capitalization check flagged Consumer Expenditure Survey, which is the actual name of a survey and correctly capitalized. Skim those, do not work through them.
Reviewing the tracked changes in Word
The output file is an ordinary Word document with ordinary tracked changes. Open it, go to the Review tab, and accept or reject each change. Nothing is different from reviewing a freelancer's file, and you keep the final say on every change.
Some changes carry an ordinary Word comment in the margin explaining why the change was made, and some untouched sentences carry one saying why they were deliberately left alone, or asking the author a question only they can answer. Comments never change the text — rejecting every tracked change leaves the author's exact words — and you delete them the way you delete any Word comment once they are dealt with.
Alongside the document you get a short report on what happened.
1 tracked changes written to chapter_CE.docx, attributed to "Packt CE".
1 edits were refused and not written:
paragraph 296 — entity_drift: the replacement drops a number: "60"
quoted: "The 60% cutoff value is used for all datasets."
Open the output in Word to review what was applied.
Two numbers matter: how many changes were applied, and how many were refused. A refused edit was never written to the document, so there is nothing to undo — but it does tell you something about the copyedit it came from. The reasons you will see most often are these.
| Reason | What went wrong |
|---|---|
find_missing |
The quoted words are not in that paragraph. The edit was written against different text, or invented. |
find_ambiguous |
The quoted words appear more than once and the edit did not say which one. |
protected_span |
The change would have altered code, an identifier, a file name, or a link. |
code_paragraph |
The edit targets a code listing, a table, or a figure. |
entity_drift |
The replacement changes or drops a number, a unit, a URL, or an acronym. |
large_insertion |
The replacement adds enough new wording to be a rewrite rather than a copyedit. |
collapsed_replace |
The replacement cuts a phrase down to almost nothing. |
A handful of refusals in a long chapter is normal. A lot of them, and
especially a lot of find_missing, means the copyedit itself needs
looking at rather than the document.
A file that already has tracked changes
If you point apply or autofix at a document that already carries
tracked changes, it stops and tells you your options.
packt-prose: chapter.docx already contains tracked changes. Run `packt-prose accept` to accept them all, pass --accept to do the same in this pass, pass --layer to write on top of them, or resolve them selectively in Word.
The interesting choice is between the last two, and it is about whose work the reviewer should still be able to see.
Layer when the existing changes are someone's work — the author's revisions, or an earlier copyeditor's pass:
Their revisions stay pending under their own names, yours arrive under
yours, and Word shows the two sets in different colors. Deleting text
someone inserted nests your deletion inside their insertion, exactly the
shape Word itself records, so every combination of accepting and rejecting
works. Edits are measured against the text as it reads with the existing
changes accepted — the same text extract shows you — so build the edit
list from the revised file itself, not from an earlier version.
One thing genuinely cannot be layered over: a pending structural
revision, such as an inserted or deleted paragraph. Paragraph numbers
depend on how that resolves, so --layer refuses those files and says so;
resolve the structural change in Word or accept everything first.
Accept when the existing changes are just drafting history — the usual case with a raw submission whose author left revision marks on:
Accepting bakes those revisions into the text under nobody's name, which is fine for the author's own drafting and wrong for another editor's work. If some of those revisions deserve rejecting instead, that is Word's job.
Reporting is unaffected either way. lint and voice read a document
with tracked changes quite happily — they read it as though the changes
were accepted — so you can always get a report on a part-edited chapter.
Per-book style profiles
Most of house style is house-wide. A few decisions belong to the book, and a profile is where a book records them.
The clearest example is contractions. Should don't be written out as
do not? The evidence refuses to pick a side: across the copyedits we
mined, editors expanded contractions 1,124 times and introduced them 909
times, and when we compared the tool's edits with the human copyedits of
the same chapters, none of the expansions were corroborated. So the
default profile says nothing either way, and the decision belongs to the
title. A profile can set one of three positions:
- neutral — say nothing either way. This is the default.
- expand — contractions are flagged and expanded to full forms, the register the Writers' Guide asks authors for.
- house — full forms are flagged as candidates for contraction, for a
deliberately conversational title (the built-in
--profile conversationalsets this).
A profile can also switch individual rules off for a title — an author whose informal register the commissioning editor signed off, a chapter extract where the whole-chapter checks make no sense — and turn on the checks that are off by default.
To use one, name it on the command.
Ask the editorial tooling team to set a profile up for a book. It is a
small file of decisions, it lives with the title, and once it exists every
command takes the same --profile option.
The book decisions file
Some choices are smaller than a profile and bigger than a chapter: does this book caption with an en dash or a colon, is its "data" singular or plural, is "agile" capitalized? Several rules learn the answer from each chapter's own majority — which works until chapter 3's majority disagrees with chapter 7's.
A file named packt-book.yml beside the manuscripts settles it. Every
command finds it automatically, the way the auto profile is found, and a
recorded decision replaces the per-chapter count: every chapter is held to
the book's choice, including a chapter that is internally consistent the
other way.
It is the copyeditor's style sheet, made machine-readable. When a run's findings show the book has made a call, record it here; the next chapter's run starts from the decision instead of rediscovering it.
Where to get help
The tool can tell you what the house style says. This lists every rule it enforces, with its severity, and marks the ones autofix can apply on its own.
To read a single rule in full — what it means, what it applies to, and which section of the house style it comes from — ask for it by the identifier a report shows against it.
If something goes wrong, the install page covers the problems that come
up when the tool is new on a machine. For anything else, ask the
editorial tooling team, and include three things: the exact command you
ran, the exact message you got back, and what packt-prose doctor
printed.
Because the tool is deterministic, that is enough to reproduce whatever you saw. The same file gives the same answer every time, on any machine, which is also why a report is worth attaching to a review: anyone can run the command again and get your numbers.