incremental-writer

name

incremental-writer

description

Orchestrates writing comprehensive long documents section by section, breaking through Claude's single-response output limits. Each section gets full output capacity, then sections are assembled into a final .docx. PROACTIVE TRIGGER — Claude MUST invoke this skill automatically whenever a writing task would produce a document exceeding ~8,000 words. Estimate the total word count before starting. If it exceeds ~8,000 words, the outline has 6+ major sections, or a template is longer than 10 pages, load this skill and ask the user whether to break the work into sections. Do not attempt a single-pass write for documents of this size. Also trigger on: "write section by section", "incremental writer", "comprehensive report", "detailed document", "lengthy report", "full report", or when a template/outline implies a document that would be compressed in one pass. Works alongside domain-specific report skills (RCS, LOPA, construction audit) for writing orchestration.

Incremental Writer

Write comprehensive long documents section by section, then assemble into a polished .docx. This skill exists because Claude's single-response output caps at roughly 8–10k words — fine for short documents, but it forces content compression when writing 30–100+ page reports. The incremental approach gives each section Claude's full output capacity, producing documents 5–15x longer than a single pass would allow.

Step 0 — Proactive Detection & User Decision

Before beginning any document writing task, perform a quick estimate:

1. Scan the inputs — read the template, outline, or user instructions
2. Estimate total scope:
   • Count major sections/chapters
   • Estimate words per section (from template length, topic complexity, or user expectations)
   • Calculate total estimated word count
3. Apply the threshold test:

Indicator	Threshold	Action
Estimated word count	> 8,000 words	Recommend incremental
Major sections	≥ 6 sections	Recommend incremental
Template page count	> 10 pages	Recommend incremental
User says "comprehensive" / "detailed" / "thorough"	Any	Recommend incremental
Simple structure, < 5,000 words	Below all thresholds	Single pass is fine

4. Ask the user using AskUserQuestion:
   • Present the estimate: "This document looks like it will be approximately [X] words across [N] sections."
   • Offer the choice: write section by section (recommended for this size) vs attempt a single pass
   • If the user chooses single pass, proceed normally without this skill
   • If the user chooses incremental, continue to Phase 1

This step is lightweight — it should take one tool call to estimate and one AskUserQuestion call. Do not create manifests or placeholder files until the user confirms.

---

How It Works — Four Phases

Phase 1: Plan & Structure    → Analyse template/outline, create manifest, set up section files
Phase 2: Write (per section) → Write each section comprehensively, reading only prerequisites
Phase 3: Review & Refine     → User reviews, Claude makes targeted edits
Phase 4: Assemble & Export   → Combine sections into final .docx

The key insight is selective context reading: before writing each section, read only the 2–4 prerequisite sections it depends on — not the entire document. This prevents context bloat and keeps each write pass focused.

---

Phase 1 — Plan & Structure

Step 1.1 — Analyse the Source Material

Read the user's template, outline, uploaded document, or verbal instructions. Identify:

• All sections and subsections with their hierarchy
• Boilerplate language that must be preserved verbatim (if template-based)
• Placeholder fields requiring project-specific data
• Estimated word count per section (based on template length or user expectations)
• Cross-references between sections (which sections cite or depend on others)
• The tone, register, and level of technical detail

Summarise your analysis to the user before proceeding. Include the proposed section structure with estimated word targets.

Step 1.2 — Create the Manifest

Create a manifest.json file in the session working directory (e.g., /sessions/<session-id>/incremental-writer/). This tracks document state and enables recovery if the session is interrupted.

{
  "title": "Document Title",
  "status": "planning",
  "templateSource": "path/to/template or 'verbal instructions'",
  "createdAt": "2026-03-08T10:00:00Z",
  "totalWordTarget": 25000,
  "sections": [
    {
      "id": "01",
      "heading": "Executive Summary",
      "filename": "01-executive-summary.md",
      "status": "pending",
      "wordTarget": 1500,
      "wordCount": 0,
      "dependsOn": ["02", "03", "04"],
      "notes": "Write LAST — after all body sections are complete"
    },
    {
      "id": "02",
      "heading": "Introduction",
      "filename": "02-introduction.md",
      "status": "pending",
      "wordTarget": 2000,
      "wordCount": 0,
      "dependsOn": [],
      "notes": ""
    }
  ],
  "writeOrder": ["02", "03", "04", "05", "06", "07", "08", "01"],
  "crossReferences": {
    "02": ["03"],
    "05": ["03", "04"]
  }
}

Key fields:

• dependsOn — which sections to read before writing this one (selective context)
• writeOrder — the actual order sections will be written (may differ from document order; front matter like executive summaries should be written last)
• status — one of: pending, in_progress, draft, revised, final
• wordTarget — estimated words; not a hard limit, but a guide for appropriate depth
• totalWordTarget — sum of all section targets; helps track overall progress

Step 1.3 — Create Placeholder Files

Create numbered .md files for each section in the working directory:

/sessions/<session-id>/incremental-writer/
├── manifest.json
├── 01-executive-summary.md
├── 02-introduction.md
├── 03-methodology.md
├── ...
└── drafts/                    ← backup folder for revised sections

Each placeholder file starts with a YAML header:

---
section: "01"
heading: "Executive Summary"
status: "pending"
wordCount: 0
---

<!-- Content will be written in Phase 2 -->

Step 1.4 — User Confirmation

Present the section structure to the user:

• List all sections with heading, estimated word target, and write order
• Highlight any sections that will be written out of document order (e.g., executive summary last)
• Note any sections where information is missing or unclear
• Show the total estimated word count and approximate page count (~250 words per page)
• Ask the user to confirm, revise, or add sections

After confirmation, update manifest.json with any changes.

Step 1.5 — Initialise TodoWrite

Create a todo item for each section in write order, plus review and assembly:

- [ ] Write Section 02: Introduction (~2,000 words)
- [ ] Write Section 03: Methodology (~3,000 words)
- [ ] ...
- [ ] Write Section 01: Executive Summary (~1,500 words)  ← last body section
- [ ] Review all sections with user
- [ ] Assemble into final .docx

---

Phase 2 — Write (Section by Section)

This is the core phase. For each section in writeOrder:

Step 2.1 — Read Prerequisites

1. Read manifest.json to get the current section's dependsOn array
2. Read ONLY the sections listed in dependsOn — not the entire document
3. If a dependency section is still pending, either:
   • Write it first (adjust write order), or
   • Skip the dependency and flag it for later review

Context management is critical. A 100k-word document cannot be re-read before every section. Typically 2–4 prerequisite sections (10–20k words) are read per write pass. This is what makes the incremental approach work without hitting context limits.

Step 2.2 — Write the Section

Write the section comprehensively. Key rules:

• No artificial length limits. Write as much as the section needs. If the template has 3 pages of content for this section, write 3 pages. Do not compress.
• Preserve template language. If the user provided a template, reproduce boilerplate text verbatim. Only modify placeholder fields.
• Use Australian English spelling throughout (analyse, minimise, behaviour, labour).
• Mark missing information with [INSERT: description of what's needed] rather than inventing content.
• Include cross-references to other sections where appropriate (e.g., "refer to Section 3 for methodology details").
• Format for print/PDF export — consistent heading hierarchy, sensible paragraph breaks, tables that won't split awkwardly.

Step 2.3 — Save and Update Manifest

1. Save the section content to its .md file (overwrite the placeholder)
2. Update the file's YAML header with actual word count and status
3. Update manifest.json:
   • Set section status to draft
   • Record wordCount
   • Add timestamp

Step 2.4 — Checkpoint and Progress

1. Mark the TodoWrite item as completed
2. Report progress to the user:

[incremental-writer] Section 02 (Introduction) complete — 2,340 words.
Progress: 2 of 8 sections written (12,450 / ~35,000 words estimated).
Next: Section 03 (Methodology)

3. Proceed to the next section automatically unless the user intervenes. If the user wants to review a just-completed section before moving on, pause and handle their feedback (see Phase 3), then resume.

---

Phase 3 — Review & Refine

After all sections are drafted (or at user-requested checkpoints):

Step 3.1 — User Review

The user can review sections in any order. For each section they want to revise:

1. Read the section
2. Collect user feedback (specific changes, tone adjustments, missing content, factual corrections)
3. Make targeted edits using the Edit tool — do not rewrite entire sections unless the user asks for a full rewrite

Step 3.2 — Backup Before Revision

Before overwriting a section with revisions:

1. Copy the current version to drafts/ with a version suffix: drafts/03-methodology-v1.md
2. Apply edits to the main file
3. Update manifest status to revised
4. Update word count if it changed meaningfully

Step 3.3 — Dependency Cascade Check

If a revised section is listed in another section's dependsOn array:

1. Flag the dependent sections for consistency review
2. Read the dependent section and check whether the revision changes any cross-references, data, or conclusions
3. If inconsistencies are found, propose targeted edits to the dependent section
4. Confirm with the user before making cascading changes

Step 3.4 — Cross-Reference Verification

After all revisions are complete, scan all sections for internal cross-references:

• "Refer to Section X" — does Section X actually cover what's claimed?
• Table/figure numbering — is it sequential and consistent?
• Defined terms — are they used consistently across sections?

Flag any issues for the user's attention.

---

Phase 4 — Assemble & Export

Step 4.1 — Pre-Assembly Check

Before assembling, verify:

• All sections in manifest.json have status draft, revised, or final
• No sections are still pending or in_progress
• All [INSERT: ...] placeholders have been either filled or acknowledged by the user
• Cross-references are consistent

Step 4.2 — Read the docx Skill

Read the docx skill for the .docx assembly methodology. The docx skill uses the npm docx library (JavaScript) to create Word documents programmatically.

Step 4.3 — Assemble the Document

1. Read all section .md files in document order (not write order)
2. Parse each section's Markdown into structured content
3. Use the docx skill's approach to create a .docx file with:
   • Title page (if appropriate)
   • Table of contents
   • All sections with correct heading hierarchy
   • Page numbers, headers/footers
   • Tables, lists, and formatting preserved from Markdown
   • Page breaks between major sections
4. Save the .docx to the user's working folder

Step 4.4 — Final Report

[incremental-writer] Document assembled:
  - Title: [document title]
  - Sections: [N] sections, [total word count] words
  - Output: [filename.docx] in your working folder

Step 4.5 — Cleanup Decision

Ask the user whether to:

• Keep the temp folder (section .md files and manifest) for reference
• Clean up the temp folder (delete section files, keep only the final .docx)

Never auto-delete without asking.

---

Edge Cases

Context Compaction Mid-Write

If context compaction occurs during Phase 2:

1. The manifest file persists on disk with the state of every section
2. On recovery: read manifest.json, identify the last completed section (status = draft), resume from the next section in writeOrder
3. The TodoWrite state also persists, so progress is visible immediately

Section Exceeds Output Capacity

If a single section is so large it would exceed Claude's output capacity:

1. Split it into subsections in the manifest: 04a-findings-part1.md, 04b-findings-part2.md
2. Each subsection gets its own write pass
3. Update writeOrder and dependsOn arrays accordingly
4. During assembly, subsections are merged back into a single document section

User Adds or Removes Sections

If the user wants to modify the structure after Phase 1:

1. Update manifest.json — add/remove section entries
2. Create/delete corresponding .md files
3. Renumber if needed (or use descriptive IDs that don't require renumbering)
4. Adjust writeOrder and dependsOn arrays
5. Update TodoWrite list

Template-Based vs Freeform Writing

• Template-based: Phase 1 analyses the template structure. Phase 2 preserves boilerplate language and fills placeholders. Higher fidelity to source material.
• Freeform (from outline or verbal instructions): Phase 1 proposes a structure based on the topic. Phase 2 writes original content. More creative freedom, but still structured.

The skill handles both — the difference is in how strictly template language is preserved.

---

Integration with Other Skills

Domain-Specific Report Skills (RCS, LOPA, Construction Audit, etc.)

When a domain-specific report skill detects that the document will be large (6+ sections or 8,000+ words), it should hand off writing orchestration to the incremental writer. The workflow is:

1. Domain skill defines the template sections, regulatory requirements, and content guidance
2. Incremental writer takes over the section-by-section writing process
3. Each section uses domain skill guidance for content accuracy and regulatory citations
4. Incremental writer assembles the final .docx

The domain skill provides the what (content requirements, regulatory references, template structure). The incremental writer provides the how (section-by-section writing, context management, assembly).

docx Skill

Called in Phase 4 for final .docx assembly. Read the docx skill before assembly to follow its exact methodology.

Session Memory

Checkpoints fire automatically via TodoWrite completion after each section. The manifest file on disk also provides a recovery path if the session ends mid-write.

---

Manifest Status Values

Status	Meaning
pending	Not yet written
in_progress	Currently being written
draft	First pass complete
revised	User-requested changes applied
final	Approved by user, ready for assembly

---

Progress Reporting Format

After each section:

[incremental-writer] Section [ID] ([heading]) complete — [wordCount] words.
Progress: [N] of [total] sections written ([cumulative words] / ~[estimated total] words).
Next: Section [nextID] ([nextHeading])

After all sections are complete:

[incremental-writer] All [N] sections drafted — [total words] words total.
Ready for review (Phase 3) or assembly (Phase 4).

After assembly:

[incremental-writer] Document assembled — [filename.docx]
  Sections: [N] | Words: [total] | Pages: ~[estimate]
  Location: [path in user's working folder]

---

Quick Start Checklist

When this skill fires, follow this sequence:

1. Estimate — scan inputs, estimate word count and section count (Step 0)
2. Ask — if over threshold, ask user whether to use incremental approach
3. Analyse — read and analyse the template, outline, or instructions
4. Propose — present section structure with word targets and write order
5. Confirm — get user confirmation
6. Set up — create manifest and placeholder files, initialise TodoWrite
7. Write — sections one by one with selective context reading
8. Report — progress after each section
9. Review — when all sections are drafted, offer review or assembly
10. Assemble — into .docx using the docx skill
11. Deliver — final document to the user's working folder