Coherent Writing

Coherent Writing

Usage

Use this skill whenever a user wants writing to read as one connected argument rather than disconnected points.

Target common requests such as:

• "Make this paragraph coherent."
• "Smooth the transitions."
• "This draft feels jumpy and repetitive."
• "Keep my voice, but make the logic flow."

Requirements

Require from the user when missing:

• Draft text to revise.
• Intended audience.
• Desired tone (formal, conversational, technical, persuasive).
• Non-negotiable constraints (length, keywords, claims that must remain).

What It Does

Perform coherence-first editing in four passes with sub-agents:

1. Global argument pass — read the full draft and resolve conflicting arguments. 2. Section transition pass — smooth every consecutive section boundary. 3. Paragraph transition pass — smooth every consecutive paragraph boundary. 4. Final coherence audit — recheck the whole piece and remediate remaining issues.

All passes preserve draft length, author voice, facts, and claims. They may not introduce new points, examples, citations, or arguments.

How It Works

Run the passes in order. Do not skip passes. Do not merge passes.

Preparation (orchestrator only)

Before Pass 1:

1. Read the full draft once without editing. 2. Record baseline word count (target: stay within ±5%). 3. Parse structure:

• Sections: blocks separated by Markdown headings (#, ##, ###, etc.). If no headings exist, treat the whole draft as one section.
• Paragraphs: blocks separated by blank lines within each section.

4. Build work queues:

• Section pairs: (S1,S2), (S2,S3), ...
• Paragraph pairs: (P1,P2), (P2,P3), ... across the full draft in reading order.

5. Copy constraints into every sub-agent prompt (see Global constraints).

For transition templates and anti-patterns, read references/coherence-patterns.md. For sub-agent prompt templates, read references/subagent-prompts.md.

Pass 1 — Global argument coherence (1 sub-agent)

Goal: Ensure the entire piece has no conflicting arguments.

Dispatch: Exactly one sub-agent via the Task tool.

Scope: Full draft.

Allowed edits:

• Resolve contradictions by aligning claims, reordering, or trimming conflicting statements.
• Clarify ambiguous claims so they no longer conflict.
• Remove duplicate arguments that fight each other.

Forbidden edits:

• Adding new arguments, examples, data, or citations.
• Expanding scope or changing the thesis unless required to resolve a direct contradiction.

Output: Revised full draft + short list of conflicts found and how each was resolved.

The orchestrator replaces the working draft with this output before Pass 2.

Pass 2 — Section transitions (1 sub-agent per consecutive section pair)

Goal: Every consecutive section pair flows smoothly; no abrupt section shifts.

Dispatch: Launch one sub-agent per consecutive section pair in parallel (Task tool, single message with multiple calls).

Example: sections Intro, Methods, Results → agents for (Intro, Methods) and (Methods, Results).

Scope per agent: Only the boundary between its assigned section pair:

• The last paragraph(s) of the earlier section.
• Any heading or bridge between them.
• The first paragraph(s) of the later section.

Allowed edits:

• Add or rewrite bridge sentences at the section boundary.
• Tweak opening/closing sentences of adjacent sections for continuity.
• Adjust signposting so the reader knows why the next section follows.

Forbidden edits:

• Rewriting unrelated paragraphs inside either section.
• Adding new points, examples, or claims.
• Changing section order or merging/splitting sections.

Output per agent: Revised boundary text + one-line note on what changed.

The orchestrator merges boundary edits back into the working draft in document order, then proceeds to Pass 3.

Pass 3 — Paragraph transitions (1 sub-agent per consecutive paragraph pair)

Goal: Every consecutive paragraph pair flows smoothly; no abrupt paragraph shifts.

Dispatch: Launch one sub-agent per consecutive paragraph pair in parallel.

Example: paragraphs P1–P4 → agents for (P1,P2), (P2,P3), (P3,P4).

Scope per agent: Only the transition between its assigned paragraph pair:

• The last 1–2 sentences of the earlier paragraph.
• The first 1–2 sentences of the later paragraph.
• At most one short bridge sentence between them if needed.

Allowed edits:

• Rewrite transition phrases.
• Replace vague referents (this, it) with concrete nouns already present in the draft.
• Reorder or tighten existing sentences at the boundary.

Forbidden edits:

• Rewriting full paragraphs unrelated to the boundary.
• Adding new points, examples, or claims.
• Changing paragraph order or splitting/merging paragraphs.

Output per agent: Revised boundary text + one-line note on what changed.

The orchestrator merges boundary edits back into the working draft in document order, then proceeds to Pass 4.

Pass 4 — Final coherence audit (1 sub-agent)

Goal: Recheck the full revised draft for any remaining coherence issues and remediate them.

Dispatch: Exactly one sub-agent via the Task tool.

Scope: Full draft from Pass 3.

Check:

• No conflicting arguments remain.
• Section boundaries still flow.
• Paragraph boundaries still flow.
• Word count still within ±5% of baseline.
• No new points were introduced.

If issues remain: Apply minimal remedial edits (same constraints as earlier passes).

Output: Final draft + short audit report listing any issues found and fixes applied.

Global constraints

Include these in every sub-agent prompt:

CONSTRAINTS (non-negotiable):
- Preserve author voice, facts, and intent.
- Preserve overall length (stay within ±5% of baseline word count).
- Do NOT introduce new points, examples, citations, arguments, or claims.
- Edit ONLY for coherence and transition smoothness.
- Do NOT change scope beyond what is needed to fix coherence.

Orchestrator merge rules

When integrating sub-agent outputs:

1. Apply edits in document order (top to bottom). 2. Prefer the smallest edit that fixes the transition. 3. If two agents touched adjacent boundaries, keep the later merge and re-read the seam for smoothness. 4. After each pass, recompute word count before continuing. 5. If word count drifts beyond ±5%, trim redundant phrasing before the next pass — never by deleting substantive claims.

Return to user

Deliver:

1. Final revised text (full draft). 2. Pass summary (brief):

• Pass 1: conflicts resolved.
• Pass 2: section boundaries edited (count).
• Pass 3: paragraph boundaries edited (count).
• Pass 4: audit outcome.

3. Length check: baseline vs final word count.

Use this checkpoint rubric during every pass:

• Continuity: Does each sentence naturally follow from the prior one?
• Progression: Does each paragraph add something new?
• Signposting: Are transitions explicit where needed?
• Alignment: Does every section support the core claim?
• Constraint compliance: No new points; length preserved.

Coherence Patterns

Use this file during rewriting when you need concrete transition language or fast diagnostics.

Fast Diagnostics

Look for these common coherence failures:

1. Topic jump: New sentence introduces a different subject without a bridge. 2. Orphan claim: Assertion appears without evidence or context. 3. Looping: Paragraph repeats the same claim with different wording. 4. Pronoun fog: "this", "it", "they" without a clear referent. 5. Unsignaled pivot: Shift from explanation to recommendation without warning.

Transition Templates

Use transitions sparingly and only when a link is unclear.

Additive

• "Building on that,"
• "In the same vein,"
• "A related implication is"

Contrastive

• "However, this breaks down when"
• "That said, the stronger interpretation is"
• "By contrast,"

Causal

• "Because of this,"
• "As a result,"
• "This matters because"

Sequence

• "First... Next... Finally..."
• "At this point,"
• "The next step is"

Evidence-to-claim

• "Taken together, these details suggest"
• "This supports the broader claim that"
• "The practical takeaway is"

Paragraph Frame

Use this frame when paragraphs feel loose:

1. Topic sentence with one claim. 2. Support sentence(s): evidence, example, or reasoning. 3. Link sentence: why this point matters for the thesis.

Section Boundary Patterns

Use at section transitions when the shift feels abrupt:

Preview the next section

• "With that foundation in place, the next question is..."
• "That sets up the part of the argument that follows:"
• "To see why this matters, consider..."

Close the prior section

• "So far, this establishes..."
• "Taken together, these points show..."
• "That conclusion leads directly to..."

Heading + bridge

When a heading alone is too abrupt, add one bridge sentence before or after it:

## Methods

Building on the problem outlined above, the analysis proceeds as follows.

Keep Voice While Improving Flow

Prefer these moves before rewriting tone:

• Reorder existing sentences.
• Add one bridge sentence.
• Delete duplicate sentences.
• Replace vague referents with concrete nouns.

Only change diction significantly when explicitly requested.

Length Preservation

When smoothing transitions:

• Trim redundant qualifiers elsewhere if a bridge sentence adds words.
• Prefer tightening existing sentences over adding new ones.
• If a bridge is needed, keep it to one sentence.
• Target ±5% of baseline word count across all passes.

Sub-Agent Prompt Templates

Copy the relevant template into each Task tool call. Replace placeholders in ALL CAPS.

Pass 1 — Global argument coherence

You are a coherence editor for Pass 1 (global argument check).

DRAFT:
"""
FULL_DRAFT
"""

BASELINE WORD COUNT: BASELINE_COUNT

CONSTRAINTS (non-negotiable):
- Preserve author voice, facts, and intent.
- Preserve overall length (stay within ±5% of baseline word count).
- Do NOT introduce new points, examples, citations, arguments, or claims.
- Edit ONLY for coherence — resolve conflicting arguments.
- Do NOT change scope beyond what is needed to fix contradictions.

TASK:
1. Read the entire draft.
2. Identify every conflicting argument, contradiction, or claim that fights another claim.
3. Resolve each conflict by aligning, clarifying, reordering, or trimming — without adding new material.
4. Return the full revised draft.

OUTPUT FORMAT:
1. Revised full draft (complete text).
2. Conflicts resolved (bulleted list: conflict → resolution).
3. Final word count.

Pass 2 — Section transition (one pair)

You are a coherence editor for Pass 2 (section transition).

SECTION A (earlier):
"""
SECTION_A_TEXT
"""

SECTION B (later):
"""
SECTION_B_TEXT
"""

BASELINE WORD COUNT (full draft): BASELINE_COUNT

CONSTRAINTS (non-negotiable):
- Preserve author voice, facts, and intent.
- Preserve overall length (stay within ±5% of baseline word count).
- Do NOT introduce new points, examples, citations, arguments, or claims.
- Edit ONLY the boundary between Section A and Section B.
- Do NOT rewrite unrelated paragraphs inside either section.

TASK:
1. Read Section A ending and Section B opening.
2. Ensure the transition is not abrupt — the reader should know why Section B follows Section A.
3. Edit only:
   - Last paragraph(s) of Section A
   - Section B heading or bridge (if present)
   - First paragraph(s) of Section B
4. Prefer bridge sentences and signposting over full rewrites.

OUTPUT FORMAT:
1. Revised boundary text (show the edited ending of A + start of B, with enough context to merge).
2. One-line note: what changed and why.

Pass 3 — Paragraph transition (one pair)

You are a coherence editor for Pass 3 (paragraph transition).

PARAGRAPH N (earlier):
"""
PARAGRAPH_N_TEXT
"""

PARAGRAPH N+1 (later):
"""
PARAGRAPH_N_PLUS_1_TEXT
"""

BASELINE WORD COUNT (full draft): BASELINE_COUNT

CONSTRAINTS (non-negotiable):
- Preserve author voice, facts, and intent.
- Preserve overall length (stay within ±5% of baseline word count).
- Do NOT introduce new points, examples, citations, arguments, or claims.
- Edit ONLY the transition between Paragraph N and Paragraph N+1.
- Do NOT rewrite unrelated sentences inside either paragraph.

TASK:
1. Read the end of Paragraph N and the start of Paragraph N+1.
2. Ensure the transition flows smoothly — no abrupt topic jump or missing bridge.
3. Edit only:
   - Last 1–2 sentences of Paragraph N
   - First 1–2 sentences of Paragraph N+1
   - At most one short bridge sentence between them if needed
4. Replace vague referents with concrete nouns already in the draft.

OUTPUT FORMAT:
1. Revised boundary text (edited end of N + start of N+1).
2. One-line note: what changed and why.

Pass 4 — Final coherence audit

You are a coherence editor for Pass 4 (final audit).

DRAFT (after Passes 1–3):
"""
FULL_DRAFT
"""

BASELINE WORD COUNT: BASELINE_COUNT

CONSTRAINTS (non-negotiable):
- Preserve author voice, facts, and intent.
- Preserve overall length (stay within ±5% of baseline word count).
- Do NOT introduce new points, examples, citations, arguments, or claims.
- Edit ONLY to fix remaining coherence issues.

TASK:
1. Recheck the full draft for:
   - Conflicting arguments
   - Abrupt section transitions
   - Abrupt paragraph transitions
   - Length drift beyond ±5%
   - Any new points introduced during earlier passes
2. If issues remain, apply minimal remedial edits (same constraints).
3. Return the final draft.

OUTPUT FORMAT:
1. Final revised draft (complete text).
2. Audit report (bulleted: issue → fix, or "No issues found").
3. Final word count vs baseline.