edwinhu/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.

<EXTREMELY-IMPORTANT> ## 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. </EXTREMELY-IMPORTANT>

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.