Three Pass Writing

Step 1 — Declare scope, output type, audience, and budget

Emit a brief card before writing any prose:

Output:      <working title>
Type:        <technical-report | blog-article | architecture-doc | documentation-guide | executive-brief>
Audience:    <who reads this, their expertise level, what they need>
Thesis:      <one-sentence proposition or central recommendation>
Word target: <e.g. "2,000 words" or "1 page">
Budget:      <wall-clock ceiling, e.g. "2 hr">
Reference:   <load the matching reference file from Bundled Resources>

The Thesis constrains every section — every claim must trace back to it. A vague thesis produces a wandering draft.

The Audience drives the Presentation P: vocabulary level, assumed knowledge, required definitions, and appropriate formality.

Step 2 — Gather and assess source material

List all inputs the piece will draw on: data, prior documents, source code, research, interviews, benchmarks.

For each source, note:

• Relevance to the thesis
• Credibility and recency
• Whether it supports or complicates the proposition

If any source exceeds 600 lines, build a chunk map per .claude/rules/iterative-read.md before reading it.

Assess whether .claude/rules/iterative-processing.md applies: source material >600 lines AND intended output >500 lines → plan READ-PROCESS-WRITE triplets for Pass 2.

Step 3 — Pass 1: Scaffold the structure (10–30 min)

Using the reference file for the declared output type, build a complete structural outline. Produce the scaffold:

• One heading per major section
• One-sentence stub per section stating what it will argue or cover
• Evidence markers: [evidence: source / data point] placed at each claim site
• No prose, no full sentences in stubs — structure only

Answer the Five Ps at outline level using the table in the Reference Tables section below.

Emit the scaffold and the Five Ps assessment.

Gate — Pass 1: Can a second writer produce the intended piece from this outline without asking a single clarifying question?

• Stop: The scaffold is the deliverable (e.g., an outline for human approval before full draft).
• Proceed: Every section stub traces to the thesis. Continue to Step 4.
• Revise: Restructure if sections overlap, are missing, or contradict the thesis.

Step 4 — Pass 2: Draft complete prose (30 min–4 hr)

Write complete prose for every section in the scaffold. The pass is complete when zero placeholders, stubs, or [evidence: ...] markers remain.

While drafting:

• Every major claim must have evidence inline (citation, data point, example, or code)
• Every section opens with a topic sentence and closes with a transition or conclusion
• Section order must match the scaffold unless a structural change genuinely improves coherence

For outputs exceeding 500 lines, apply .claude/rules/iterative-write.md:

• Sequential strategy for independent sections (technical reports, documentation guides)
• Scaffold-then-Fill strategy for cross-referenced sections (architecture docs with forward references, research writeups citing earlier sections)

When source material is also large, apply .claude/rules/iterative-processing.md READ-PROCESS-WRITE triplets — do not batch all source reading before writing begins.

Gate — Pass 2: Can a reader unfamiliar with the background understand the full argument using only this draft, without supplementary material?

• Stop: Draft quality is sufficient for the use case. Emit as Pass-2 draft.
• Proceed to Pass 3: Full refinement warranted. Justify in writing.

Step 5 — Pass 3: Refine and strengthen (15 min–1 hr)

Re-read the full draft as a skeptical, hostile reviewer — someone who starts unconvinced and looks for reasons to dismiss the piece. Apply the Pass-3 checklist from the reference file for the declared output type.

While refining:

• Challenge every claim: is the evidence sufficient, or is this an assertion without support?
• Cut bloat: target 10–15% word count reduction without losing substance
• Strengthen transitions: does each section flow logically from the previous?
• Check internal consistency: do later sections contradict earlier ones?
• Verify formatting against output-type conventions from the reference file
• Confirm the piece delivers on the brief card's stated purpose for the stated audience

Step 6 — Emit final deliverable

Assemble the final output in this order:

1. Brief card (Step 1)
2. Final prose (Pass 3 output, or Pass 2 if Pass 3 was deferred with written justification)

If the assembled output exceeds approximately 500 lines, apply .claude/rules/iterative-write.md Sequential strategy to emit each major section independently.

Step 7 — Harvest reusable insights to memory

After Pass 2 or Pass 3, evaluate: is there anything non-obvious here worth preserving for a future writing session?

Qualifying examples:

• A structural pattern that worked well for this audience type
• An argument structure that resolved a difficult tradeoff
• A discovery that a commonly held view was unsupported by the evidence
• A vocabulary or framing choice specific to this domain or audience

Write qualifying insights to .claude/agent-memory/ per .claude/rules/memory-update.md. Record the outcome:

Memory: <written — <topic> to <file> | skipped — nothing qualifies | skipped — already present>

Do not manufacture entries. One genuine insight outweighs five forced ones.

Step 8 — Validate

• Brief card has output type, audience, thesis, word target, and budget filled in
• Source material assessed; chunk map exists for sources >600 lines
• Pass-1 scaffold has one-sentence stub per section with evidence markers
• Pass-1 Five Ps answered at outline level using the correct output-type column
• Pass-1 gate decision recorded (stop / proceed / revise)
• Pass-2 draft has zero placeholders, stubs, or evidence markers remaining
• Every major claim in the draft has evidence inline
• Pass-2 gate decision recorded (stop / proceed)
• If Pass 3 ran: word count reduced by at least 5%; all claims challenged
• Final deliverable within 20% of stated word target
• Wall-clock time ≤ declared budget, or overrun logged with reason
• Memory evaluation recorded (written / skipped)

Reference Tables

Five Ps by Output Type

Quick-Reference Pass Table

Time Budget Reference

Bundled Resources

• Technical Report Writing Guide — load when output type is technical-report
• Blog and Article Writing Guide — load when output type is blog-article
• Architecture Document Writing Guide — load when output type is architecture-doc
• Documentation Guide Writing Guide — load when output type is documentation-guide
• Executive Brief Writing Guide — load when output type is executive-brief

Example

User: Write an ADR for migrating our API gateway from Express to Fastify.

Actions:
1. Step 1 — Brief card: type=architecture-doc, audience=backend engineering team (senior engineers
   familiar with Node.js, unfamiliar with Fastify internals), thesis="Fastify is the right migration
   target for 3x throughput at lower memory cost", word target=1,500 words, budget=2h.
   Load references/architecture-doc.md.
2. Step 2 — Sources: internal Express benchmark (220 lines), Fastify docs (Pass-1 reading complete),
   migration risk register (80 lines). Total ~300 lines; iterative-processing.md not needed.
3. Step 3 — Pass 1 (18 min): Scaffold with Status/Context/Decision/Alternatives/Consequences.
   Evidence markers: [evidence: express-fastify-benchmark.csv] in Decision, [evidence: risk-register]
   in Consequences. Alternatives listed: Express (status quo), Fastify, Hono, custom thin wrapper.
   Five Ps: Purpose=guide migration decision, Persona=backend team assuming Node expertise,
   Proposition="Fastify best balance of speed + ecosystem", Proof=benchmarks+plugin audit,
   Presentation=ADR format with tradeoff table. Gate: proceed — all alternatives covered.
4. Step 4 — Pass 2 (55 min): Full prose per section. Tradeoff table: Express/Fastify/Hono/custom
   on axes of throughput, ecosystem, migration cost, team familiarity. Consequences includes
   plugin-ecosystem gap as a listed risk. Sequential strategy (ADR sections are independent).
   Gate: proceed to Pass 3 — need to stress-test alternatives before publishing.
5. Step 5 — Pass 3 (25 min): Challenged "3x throughput" — added caveat for middleware-heavy routes
   where gap narrows to 1.8x. Argued Hono's case — found 6 internal plugins would need rewriting;
   rejection confirmed with evidence. Cut 180 words of hedging. Final: 1,380 words.
6. Step 6 — Brief card + ADR emitted. Under 500 lines; iterative-write.md not needed.
7. Step 7 — Memory: "Fastify migration: plugin ecosystem gap is real risk; benchmark caveat needed
   for middleware-heavy routes" written to .claude/agent-memory/main_agent/patterns.md.
8. Step 8 — Validate: all checklist items pass. 1h38m of 2h budget.

Result: Brief card, ADR with Status/Context/Decision/Alternatives/Consequences, tradeoff table
(4 alternatives × 4 criteria), migration phases with rollback, risk register. One memory entry saved.

Troubleshooting

Error: Draft wanders across tangential topics and the argument is unclear. Cause: Writer skipped Pass 1 scaffolding and began drafting without an outline. Solution: Return to Step 3. Build the scaffold first. Every section stub must trace back to the thesis in the brief card. Sections that don't map to the thesis are cut at scaffold stage, not during drafting.

Error: Final output reads as a rough draft — weak transitions, unsupported claims, inconsistent terminology. Cause: Writer skipped Pass 3 or treated it as light copy-editing rather than adversarial reading. Solution: Pass 3 is adversarial reading, not formatting. Re-enter at Step 5. Challenge every claim against its evidence; actively cut 10–15% of words; rewrite transitions for logical flow.

Error: Output is 3× the stated word target; scope creep during drafting. Cause: No word target in the brief card, or scaffold included sections beyond the thesis scope. Solution: Return to the brief card and set a concrete word target. In the scaffold, tag each section "must include" vs. "nice to have". Cut all "nice to have" sections before drafting begins.

Error: Technical piece uses jargon the audience doesn't understand; readers disengage. Cause: Persona in the brief card was left vague ("the team" or "developers") instead of naming a specific reader with a known knowledge level. Solution: Name a specific reader in the brief card. Persona must be concrete enough to predict what they already know and what requires definition. Pass 3's audience register check then has a clear target.

Error: Blog post has well-researched content but low engagement; readers stop before the end. Cause: Pass 1 did not plan a hook, and Pass 3 did not run the read-aloud test. Solution: The blog-article reference file requires a hook in the first 50 words and a read-aloud test in Pass 3. Re-enter at Step 5 using references/blog-article.md.

Rules

• MUST match the folder name three-pass-writing to the name frontmatter field exactly.
• MUST keep this file under 5,000 words; move extended per-output-type detail to references/.
• MUST emit a brief card (Step 1) before writing any prose content.
• MUST record an explicit go/no-go gate decision in writing after Pass 1 and after Pass 2.
• MUST load the matching reference file before starting Pass 1.
• MUST defer byte-level writing mechanics for outputs over 500 lines to .claude/rules/iterative-write.md.
• MUST apply .claude/rules/iterative-processing.md when source material exceeds 600 lines AND output exceeds 500 lines.
• MUST evaluate the memory-update criterion at Step 7 per .claude/rules/memory-update.md and record the decision.
• MUST ensure zero placeholders, stubs, or [evidence: ...] markers remain after Pass 2 is declared complete.
• MUST NOT include XML angle brackets anywhere in frontmatter or body.
• MUST NOT include a README.md in the skill folder.
• MUST NOT skip Pass 3 without explicit written justification recorded in the Pass-2 gate decision.