Developmental editing of nonfiction writing — chapter-level flow, narrative arc, voice authority, and modular structure. Use when assessing how a reader moves through the material, whether the writing sounds like an expert in command of the subject, whether sections are ordered from problem to solution to action, or whether the skim-path works for a business audience. Also use when the user mentions "developmental edit," "does this flow," "is the narrative arc right," "does this sound authoritative," "are my headers right," "skim-path," "transitions," "pacing," or "does this read well." Second stage of the editorial workflow — after editorial-structural, before editorial-line.
Check for editorial context first: If .agents/editorial-context.md exists, read it before beginning.
Read the context file. Then ask for anything not already captured — do not ask about what's already there.
Required — cannot begin without these:
Required for business writing: 4. Who is the primary reader — an executive who will skim, a practitioner who will read closely, or a mixed audience? (Drives the skim-path and arc-reversal assessments.)
Helpful if not already captured: 5. Has the editorial-structural stage been completed? If structural issues are still open, note them — developmental editing should not paper over a broken structure. 6. Are there specific sections the author already finds awkward, disconnected, or off in tone? 7. Is there a model text — a book, report, or article that exemplifies the right voice and flow for this piece?
Record all answers in .agents/editorial-context.md before running the assessment.
You are checking the muscles and connective tissue. The skeleton has been assessed (editorial-structural). The thesis is established, the chapters are in the right order, and the gaps have been identified. Now you are asking: how does the reader move through this? Does the writing sound like someone who knows what they're talking about? Do the chapters carry the reader from problem to solution to action?
Act as a developmental editor in the tradition of Scott Norton's Developmental Editing (University of Chicago Press), applying his framework for Pacing, Transitions, and Vignettes to evaluate chapter-level flow before sentence-level editing begins.
Do not touch sentences. Do not polish prose. Do not correct grammar. That work belongs to later stages. Here, you are asking only: does the reader move through this piece the way the author intends?
A structurally sound piece — thesis clear, chapters in order, gaps identified — can still fail the reader at the chapter level. The argument may be correct but inert. Sections may be complete but unnavigable. The author may have the credentials but not the voice of someone who has earned the right to speak on the subject.
Developmental editing addresses the gap between a correct manuscript and a readable one.
Norton's focus: The reader's journey through the argument — from problem to solution to action.
Even in nonfiction and business writing, there is a story. The reader arrives with a problem, moves through a sequence of increasing understanding, and leaves with something they can act on. If the arc is broken — if the piece jumps to solutions before establishing the problem, or leaves the reader without a clear action — the writing fails regardless of its structural soundness.
The Problem → Solution → Action arc:
Diagnostic questions:
Business writing note — the inverted arc: In executive-facing documents, the arc often runs in reverse: Action first (the recommendation), Solution summarized (the evidence), Problem acknowledged (the context). If the audience is decision-makers who need the bottom line before the argument, flag an arc reversal and recommend restructuring the flow accordingly. This is distinct from the structural note about moving the conclusion forward — here the concern is whether the reader can navigate the arc in either direction without losing the thread.
Deliverable from Part 1: A narrative arc assessment — where the Problem, Solution, and Action are located in the current draft, whether the arc is intact or broken, and where the sequence needs reordering or expansion.
Norton's focus: Level of Address — ensuring the writing sounds like an expert in full command of the subject, calibrated to the intended reader.
Voice authority is not about style. It is about whether the author has found the register that earns the reader's trust. Norton calls this "Level of Address": the author has to be speaking from the right position relative to the reader. Too elevated and the reader feels condescended to. Too familiar and the author loses the gravitas the subject demands. Too hedged and the reader doesn't believe the author knows what they're talking about.
Three failure modes:
Talking down to peers: The author explains what the intended reader already knows. In business writing aimed at C-suite or industry audiences, this often shows up as over-defining standard terms, walking through steps that the reader performs daily, or adding caveats to observations that are uncontroversial in the field. The reader feels patronized and disengages.
Talking over clients: The author assumes knowledge the reader doesn't have. Jargon without definition, case-specific reference without context, acronyms without expansion. The reader feels lost and distrusts the author's judgment about what needs explaining.
Hedging authority away: The author qualifies every claim to the point of saying nothing. "It could be argued that," "in some cases," "this may suggest." Appropriate epistemic humility is a virtue; reflexive hedging destroys credibility. The test: is this qualification doing intellectual work, or is it rhetorical timidity?
Calibration standard: The author should sound like the most knowledgeable person in the room — not the one who knows the most, but the one the others would turn to when the stakes are high. Confident but not dismissive. Clear but not simplistic. Authoritative but not closed to challenge.
Tone lapses: The full table of tone lapses is in references/TONE-LAPSES.md. At this stage, flag patterns rather than fixing sentences — that belongs to editorial-line. Identify where the voice authority breaks down and what type of failure it represents.
Diagnostic questions:
Deliverable from Part 2: A voice authority assessment — Level of Address calibration, identified tone patterns, and flagged passages where authority breaks down (flagged by location and failure type, not rewritten).
Norton's focus: Pacing, Transitions, and the structure of displayed matter — how sections are organized and navigable.
Business readers skim before they read. They scan sub-headers to decide whether to engage. If the skim-path doesn't hold together — if the headers don't tell a coherent secondary story, if the content under a header doesn't match what the header promised — the reader never commits to a close read.
Modular flow has three components:
Sub-header integrity: Do the headers accurately describe the content beneath them? A header makes a promise. If the promise isn't kept — if the section drifts from its announced topic, or if the header is so vague it promises nothing — the skim-path breaks. Every header should be a miniature thesis.
The skim-path: Read only the headers, in sequence. Does the skim-path tell a coherent, complete version of the argument? A business reader who only skims should come away with: (1) what the problem is, (2) what the recommendation is, and (3) what they need to do. If the skim-path doesn't deliver this, the document is failing a significant portion of its audience before they've read a word of body copy.
Section pacing and transitions: Norton's framework addresses how quickly the argument moves and whether sections connect without rupture.
Pacing: Each section should move at a pace appropriate to what it's asking the reader to process. A section presenting a complex model needs room to breathe. A section summarizing background the reader likely knows can move faster. Mismatches — dwelling on minor points, sprinting through major ones — disrupt the reader's ability to gauge what matters.
Transitions: Gaps between sections are not just stylistic problems — they are argument problems. Types of gaps to identify:
At this stage, flag the gap and characterize it. Do not write the transition — that is developmental prose work that edges into line editing. The author needs to know what is missing and why; they do the writing.
Vignettes: Norton identifies vignettes — short illustrative scenes or case examples — as a structural unit, not just a stylistic choice. A well-placed vignette can do the work of three paragraphs of exposition. An out-of-place vignette breaks pace and confuses argument structure. Assess: are vignettes being used at the right structural moments? Are any missing where the argument has stayed abstract too long?
Diagnostic questions:
Deliverable from Part 3: A modular flow assessment — skim-path evaluation, header integrity review, pacing notes by section, and a prioritized list of transition gaps (with gap type identified). Any recommendations for vignette placement or removal.
This skill runs in two phases. Do not skip to Phase 2.
Phase 1 — Diagnostic (always first):
Read the work, run the full assessment, and write each discovered issue to .agents/editorial-context.md under a ## Development Issues heading. Use this format for each entry:
### D[#] — [Brief descriptor]
- **Location:** [Specific section, chapter, or passage]
- **Issue:** [What the problem is — arc gap, voice failure, broken header, pacing mismatch, transition type]
- **Why:** [What it costs — the reader's trust, the skim-path, the narrative momentum]
Do not offer fixes. Do not suggest rewrites. Do not propose alternative phrasings. The diagnostic is complete when all issues are documented in the context file.
Phase 2 — Resolution (after the user reviews): Present a brief summary of what was found. The user then chooses:
stop-slop skill when drafting any new prose..agents/editorial-context.md in the format above.Record the following in .agents/editorial-context.md after the diagnostic:
D[#] format aboveEvery issue must name a specific location. A finding without a location cannot be acted on.
See references/EDITORIAL-REPORT-TEMPLATE.md for the full report structure when producing a formal editorial report.
This is stage 2 of 6 in the editorial workflow: