writing-outline

Writing Outline

Create a detailed outline for a specific section/part before drafting prose. This is Level 3 of the progressive expansion workflow.

Progressive Expansion Context

.planning/PRECIS.md          # Level 1: Thesis, claims, audience
       ↓
.planning/OUTLINE.md         # Level 2: Master structure (sections, goals)
       ↓
outlines/Part I.md         # Level 3: THIS STEP - Detailed section outline
       ↓
drafts/Part I.md           # Level 4: Prose expansion

Never skip to prose drafting without a detailed outline first.

Shared Enforcement

Auto-load all constraints matching applies-to: writing-outline:

!uv run python3 ${CLAUDE_SKILL_DIR}/../../scripts/load-constraints.py writing-outline

You MUST have these constraints loaded before proceeding. No claiming you "remember" them.

Outline Flowchart (This IS the Spec)

START (PRECIS + master OUTLINE exist)
  │
  ├─ Step 1: Load context (PRECIS, OUTLINE, ACTIVE_WORKFLOW)
  │
  ├─ Step 2: Select section (user choice or next unoutlined)
  │
  ├─ Step 3: Gather structure/depth preferences
  │
  ├─ Step 4: Create detailed outline
  │  └─ For each subsection: POINT + EVIDENCE + LOGIC
  │     Opening → Body (subsections with transitions) → Closing
  │
  ├─ Step 5: Cross-reference with PRECIS claims
  │  └─ Verify: advances claim, within scope, thesis thread
  │
  ├─ Step 6: Update ACTIVE_WORKFLOW.md
  │
  └─ More sections remaining?
     ├─ YES → Loop to Step 2 (NO pause, NO "should I continue?")
     └─ NO → GATE: Every OUTLINE section has outlines/ file?
            ├─ NO → Report missing, loop back
            └─ YES → Outline Review Gate
                     └─ Dispatch writing-outline-reviewer subagent
                        ├─ APPROVED → IMMEDIATELY load writing-draft (no pause)
                        └─ ISSUES_FOUND → fix outlines → re-dispatch (max 5)

If text and flowchart disagree, the flowchart wins.

## The Iron Law of Outline Before Prose

NO PROSE WITHOUT OUTLINE. Never skip to prose drafting without a detailed outline in outlines/ first. This is not negotiable.

If you find yourself writing prose without a matching outline file:

1. STOP immediately
2. DELETE the prose
3. Create the outline first
4. THEN draft

Thin outlines produce thin drafts. Each outline must have POINT, EVIDENCE, and LOGIC for every subsection.

Session Resume Detection

Before starting, check for an existing handoff:

1. Check if .planning/HANDOFF.md exists
2. If found: Read it and present to user:
   • Show the phase, section in progress, and Next Action
   • Ask: "Resume from handoff, or start fresh?"
   • If resume: skip to the recorded section
   • If fresh: proceed normally
3. If not found: Proceed normally

Process

Step 1: Load Context

Read(".planning/ACTIVE_WORKFLOW.md")
Read(".planning/PRECIS.md")
Read(".planning/OUTLINE.md")

If master OUTLINE.md is missing, run writing-brainstorm first.

Step 2: Select Section

If not specified by user, present available sections:

AskUserQuestion(questions=[
  {
    "question": "Which section should I outline in detail?",
    "header": "Section",
    "options": [
      {"label": "Part I / Introduction", "description": "Hook, thesis, roadmap"},
      {"label": "Part II / Background", "description": "Context and precedents"},
      {"label": "Part III / Argument", "description": "Main claims and evidence"},
      {"label": "Part IV / Counterarguments", "description": "Objections and responses"}
    ],
    "multiSelect": false
  }
])

Step 3: Gather Section Details

For the selected section, ask clarifying questions:

AskUserQuestion(questions=[
  {
    "question": "How should this section be structured?",
    "header": "Structure",
    "options": [
      {"label": "Chronological", "description": "Events/developments in time order"},
      {"label": "Thematic", "description": "Grouped by topic or concept"},
      {"label": "Problem-Solution", "description": "Issue then resolution"},
      {"label": "Comparative", "description": "Side-by-side analysis"}
    ],
    "multiSelect": false
  },
  {
    "question": "What level of detail do you want?",
    "header": "Depth",
    "options": [
      {"label": "Paragraph-level", "description": "One bullet per paragraph"},
      {"label": "Sentence-level", "description": "Key sentences mapped out"},
      {"label": "Full skeleton", "description": "Nearly complete argument structure"}
    ],
    "multiSelect": false
  }
])

Step 4: Create Detailed Outline

Create directory if needed and write the detailed outline:

mkdir -p outlines

Write to outlines/[Section Name] (Outline).md:

# [Section Name] - Detailed Outline

## Section Goal
[From master OUTLINE.md - what this section accomplishes]

## Claim Supported
[Which claim from PRECIS.md this section advances]

## Structure: [Chronological/Thematic/Problem-Solution/Comparative]

---

## Opening

**Lead sentence**: [Draft or TBD]
**Context needed**: [What reader must know]
**Transition from previous**: [How we got here]

---

## Body

### Subsection A: [Name]

**Point**: [Main argument of this subsection]
**Evidence**:
  - [Source 1]: "[key quote or fact]"
  - [Source 2]: "[key quote or fact]"
**Logic**: [How evidence supports point]
**Transition**: [Bridge to next subsection]

### Subsection B: [Name]

**Point**: [Main argument]
**Evidence**:
  - [Source]: "[key quote or fact]"
**Logic**: [How evidence supports point]
**Anticipated objection**: [If applicable]
  - Response: [How to address]
**Transition**: [Bridge to next]

### Subsection C: [Name]

[Continue pattern...]

---

## Closing

**Section summary**: [One sentence recap]
**Bridge to next section**: [How this leads to what follows]
**Thesis thread**: [How this connects to main thesis from PRECIS]

---

## Sources Used in This Section
- [Source 1] - used for [what]
- [Source 2] - used for [what]

## Open Questions
- [Anything unresolved before drafting]

## Estimated Length
[Paragraph count or word count target]

Step 5: Cross-Reference with PRECIS

Verify the detailed outline against PRECIS.md:

• Advances at least one claim from PRECIS
• Addresses relevant counterarguments (if applicable)
• Stays within IN scope
• Avoids OUT scope items
• Maintains thesis thread

Report any misalignments.

Step 6: Update Workflow State

Update .planning/ACTIVE_WORKFLOW.md:

phase: outline
current_section: [section name]
outlines_complete:
  - [list of completed outlines]

Step 7: Continue or Proceed

After completing a section outline, IMMEDIATELY start the next section. Do NOT:

• Ask "should I continue?"
• Summarize what you just outlined
• Wait for confirmation

Pausing between section outlines is procrastination disguised as courtesy.

When ALL sections from OUTLINE.md have detailed outlines in outlines/, proceed to the draft phase.

---

Deviation Rules (Outline Phase)

When outlining reveals unplanned issues, follow the deviation rules from constraints/deviation-rules.md:

• R1 (Factual): Source contradicts a PRECIS claim → auto-fix: note the contradiction, adjust the outline point
• R2 (Evidence): No source found for an outline point → auto-fix: flag as evidence gap, search for sources
• R3 (Structural): Section doesn't fit the argument flow → auto-fix: reorder subsections
• R4 (Restructuring): Entire PRECIS claim needs revision based on outlining → STOP, present to user, may require returning to writing-setup

Track deviations per section outline. Each section summary should include: Deviations: N auto-fixed (R1: X, R2: Y, R3: Z). R4 escalations: [list or "none"].

Gate: Exit Outline Phase

Before proceeding to draft phase (see constraints/gate-function-standard.md for the full 6-step gate including SUMMARY):

1. IDENTIFY: What proves outlining is complete?
   • Every section in OUTLINE.md has a corresponding file in outlines/
   • Each outline cross-references PRECIS.md claims
2. RUN: List files in outlines/, compare against sections in OUTLINE.md
3. READ: Check each outline has POINT, EVIDENCE, LOGIC for subsections
4. VERIFY: All sections have outlines, all outlines reference PRECIS claims
5. REVIEW: Dispatch outline reviewer subagent: Discover path: ${CLAUDE_SKILL_DIR}/../../skills/writing-outline-reviewer/SKILL.md, then Read() the output. Follow the reviewer skill instructions: dispatch the subagent, handle APPROVED/ISSUES_FOUND, fix and re-review up to 5 times. Only proceed when APPROVED.
6. CLAIM: Only if steps 1-5 pass (including reviewer APPROVED), proceed to draft phase. Gate type: human-verify — auto-advance to writing-draft.
7. SUMMARY: Append phase summary to .planning/PHASE_SUMMARY.md (see constraints/phase-summary-frontmatter.md):
   • phase: outline
   • artifacts_produced: [list all outlines/*.md files created]
   • provides: [outlines/*.md, .planning/OUTLINE_REVIEWED.md]
   • deviations: {r1: X, r2: Y, r3: Z, r4: W}
   • Include substantive one-liner (NOT "Outlining complete")

Skipping the outline verification is NOT HELPFUL — the user drafts from a thin outline and rewrites every section. You must verify every outline exists and has real structure.

Proceeding to draft with a thin outline is NOT HELPFUL — every section will wander and require complete redrafting. The reviewer must confirm depth before drafting begins.

---

Outline Quality Checklist

Before finalizing each outline, verify:

• Every subsection has a clear POINT
• Evidence is specific (quotes, data), not vague ("sources say")
• Logic connecting evidence to point is explicit
• Transitions between subsections are planned
• Section contributes to thesis (not tangential)
• Anticipated objections are noted where relevant
• Length estimate is realistic

Red Flags

• About to create an outline without reading PRECIS.md first → STOP. The outline won't align with the thesis; read PRECIS before every outline.
• About to write a topic list instead of a structured outline → STOP. Topics are not arguments; add POINT, EVIDENCE, LOGIC for each subsection.
• About to skip the cross-reference with PRECIS → STOP. The section may advance no claim; check which claim it serves.
• About to pause after one outline to ask permission → STOP. That breaks momentum; continue to the next section immediately.
• About to outline without sources → STOP. Evidence-free outlines produce evidence-free prose; go back to brainstorm for sources.

Progress Gating

If 5+ iterations on the same section without meaningful progress, STOP and escalate to the user for scope adjustment.

Signs you are stuck:

• Rewriting the same subsection structure repeatedly
• Cycling between two structural approaches
• Unable to find evidence for a claimed point after multiple searches
• PRECIS claim doesn't decompose cleanly into this section

When escalating, present:

• What you've tried (briefly)
• Where the section is stuck
• Options: narrow scope, merge with adjacent section, drop the claim, or reframe the argument

Spinning without progress is anti-helpful. Recognizing when to ask for guidance is competence, not weakness.

Common Problems

Problem	Fix
Outline is just topic list	Add POINT, EVIDENCE, LOGIC for each
No sources mapped	Go back to research or brainstorm
Section doesn't advance a claim	Rethink why it exists
Too long for one section	Split into multiple sections
Transitions missing	Add explicit bridges

Next Phase

After all section outlines are complete:

Outline Review Gate (MANDATORY)

Read ${CLAUDE_SKILL_DIR}/../../skills/writing-outline-reviewer/SKILL.md and follow its instructions.

Follow the outline reviewer's instructions:

• If 10+ sections → review in groups of 3-4
• Dispatch reviewer subagent
• If ISSUES_FOUND → fix outlines → re-dispatch (max 5 iterations)
• If APPROVED → proceed to draft phase

After outline review APPROVED:

Read ${CLAUDE_SKILL_DIR}/../../skills/writing-draft/SKILL.md and follow its instructions.

Then follow its instructions immediately to expand outlines into prose.