writing-setup

What this skill does

# Writing Setup

Create the project foundation: PRECIS.md (thesis, audience, claims), OUTLINE.md (document structure), and ACTIVE_WORKFLOW.md (state tracking).

**Prerequisites:** Brainstorm and lit review complete. User has confirmed topic, angle, and audience. Sources materialized in `references/` (PDFs + markdown).

## 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 step
   - If fresh: proceed normally
3. **If not found:** Proceed normally

## Shared Enforcement

Auto-load all constraints matching `applies-to: writing-setup`:

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

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

## Setup Flowchart (This IS the Spec)

```
START (brainstorm confirmed)
  │
  ├─ Step 1: Create project directories
  │  └─ mkdir outlines/ drafts/ references/ scratch/ .planning/
  │
  ├─ Step 2: Interview → Create PRECIS.md
  │  ├─ Ask thesis question
  │  ├─ Ask counterargument question
  │  └─ Write .planning/PRECIS.md (thesis, claims, audience, scope)
  │
  ├─ Step 2b: PRECIS Review Gate
  │  └─ Dispatch writing-precis-reviewer subagent
  │     ├─ APPROVED → proceed to Step 3
  │     └─ ISSUES_FOUND → fix PRECIS.md → re-dispatch (max 5)
  │
  ├─ Step 3: Create OUTLINE.md
  │  └─ Map sections → claims from PRECIS
  │     Each section has: Goal, Claim, Key Points, Transition
  │
  ├─ Step 4: Detect domain (legal/econ/general)
  │
  ├─ Step 5: Create ACTIVE_WORKFLOW.md
  │
  └─ GATE: All 3 files exist with required content?
     ├─ NO → Report missing content, fix before proceeding
     └─ YES → IMMEDIATELY load writing-outline (no pause)
```

If text and flowchart disagree, the flowchart wins.

<EXTREMELY-IMPORTANT>
## The Iron Law of Progressive Expansion

**NO OUTLINE WITHOUT PRECIS. NO DRAFTING WITHOUT OUTLINE. This is not negotiable.**

The levels are:
1. PRECIS.md (thesis, claims, audience)
2. OUTLINE.md (structure mapped to claims)
3. Section outlines in outlines/ (detailed per-section)
4. Prose drafts in drafts/ (expanded from outlines)

Skipping levels produces incoherent documents. Each level expands the previous.
</EXTREMELY-IMPORTANT>

## Step 1: Create Project Structure

```bash
mkdir -p outlines drafts references scratch .planning
echo "scratch/" >> .gitignore
touch references/sources.bib
# Seed the append-only decision log (standard state file — see writing-learnings-log.md)
[ -f .planning/LEARNINGS.md ] || printf '# Learnings — decision log\n\nAppend-only. One terse dated bullet per notable decision (angle, rejected framings, R4 restructurings, accepted gaps). Never rewrite.\n\n' > .planning/LEARNINGS.md
```

After writing PRECIS.md, append the scope decisions (claims cut, In/Out boundary) to `.planning/LEARNINGS.md` — these are the choices a resuming session cannot reconstruct from PRECIS alone.

The `references/sources.bib` file is the single source of truth for every
citation. Drafts use pandoc cite-keys (`[@authorYEAR]`) and pandoc-citeproc
renders them in Bluebook style (via the CSL configured in `ACTIVE_WORKFLOW.md`).
Populate the .bib during brainstorm/research — see
`sources_md_to_bib.py` in this skill's `scripts/` directory if you have an
existing `sources.md` to convert.

## Step 2: Create PRECIS.md

### Interview for PRECIS

Use `AskUserQuestion` to gather remaining details:

```
AskUserQuestion(questions=[
  {
    "question": "What is your thesis in one sentence?",
    "header": "Thesis",
    "options": [
      {"label": "I have a thesis", "description": "I will type it"},
      {"label": "Help me find it", "description": "Synthesize from sources"},
      {"label": "Critique: X is wrong", "description": "Argue against existing view"},
      {"label": "Propose: X should change", "description": "Recommend reform"}
    ],
    "multiSelect": false
  },
  {
    "question": "What is the strongest objection to your thesis?",
    "header": "Counter",
    "options": [
      {"label": "I know it", "description": "I will describe the objection"},
      {"label": "Find from sources", "description": "What do critics say?"},
      {"label": "Steel-man for me", "description": "Generate the best counter"}
    ],
    "multiSelect": false
  }
])
```

### PRECIS.md Template

Write to `.planning/PRECIS.md`:

```markdown
# Precis: [Working Title]

## Thesis
[One sentence - the core argument]

## Audience
[From earlier interview - who is reading, what they know/believe]

## Purpose
[What reader should think/do/believe after reading]

## Hook
[Concrete problem, controversy, or question that opens the piece - draft or TBD]

## Key Claims
- **CLAIM-01**: [Claim 1] → supports thesis by...
- **CLAIM-02**: [Claim 2] → supports thesis by...
- **CLAIM-03**: [Claim 3] → supports thesis by...

## Counterarguments to Address
1. **[Objection]**: [description]
   - Response: [how we will address it]
   - Section: [where it appears]

## Scope
### In
- [What we cover]

### Out
- [What we explicitly exclude and why]

## Domain
[legal | econ | general] → determines which writing skill to use
```

## Step 2b: PRECIS Review Gate

After writing PRECIS.md, dispatch the precis reviewer BEFORE creating the outline. Do NOT skip this step.

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

Follow the reviewer skill instructions: dispatch the subagent, handle APPROVED/ISSUES_FOUND, fix and re-review up to 5 times. Only proceed to Step 3 when the reviewer returns APPROVED.

## Step 3: Create OUTLINE.md

Structure the argument with sections mapped to claims from PRECIS.md.

### OUTLINE.md Template

```markdown
# Outline: [Title from PRECIS]

## Structure

### I. Introduction
- **Goal**: Hook reader, state thesis, roadmap
- **Hook**: [from PRECIS or TBD]
- **Thesis**: [from PRECIS]
- **Claims preview**: [list from PRECIS]

### II. [Section Name]
- **Goal**: [what this section accomplishes]
- **Implements**: [CLAIM-01, CLAIM-02, etc. from PRECIS]
- **Key points**:
  - Point A (sources: ...)
  - Point B (sources: ...)
- **Transition to next**: [how it leads to Section III]

### III. [Section Name]
- **Goal**: [what this section accomplishes]
- **Implements**: [CLAIM-XX from PRECIS]
- **Key points**:
  - [points with sources]

### IV. Counterarguments
- **Goal**: Address objections from PRECIS
- **Objection 1**: [from PRECIS] → Response
- **Objection 2**: [from PRECIS] → Response

### V. Conclusion
- **Goal**: Restate thesis with earned authority
- **Implications**: What follows from this argument
- **Future questions**: What remains unresolved

## Key Sources
[Deduplicated from search phase]

## Open Questions
[Gaps to address before drafting]
```

## Step 4: Domain Detection

Detect domain from sources and topic:

| Domain Indicators | Style | Skill |
|---|---|---|
| Legal cases, statutes, law reviews, constitutional | legal | writing-legal |
| Economics, markets, policy, data, empirical | econ | writing-econ |
| General/other | general | writing-general |

## Step 5: Create ACTIVE_WORKFLOW.md

Create `.planning/ACTIVE_WORKFLOW.md` to track workflow state:

```yaml
---
workflow: writing
style: [legal|econ|general]
phase: outline
project_root: [current directory]
bibliography: references/sources.bib
precis: .planning/PRECIS.md
outline: .planning/OUTLINE.md
current_part: [if multi-part document]
edits_since_verify: 0
verify_threshold: 10
skill_stack:
  - writing
  - writing-[domain]
# Optional — set if the project has an NLM notebook populated with source PDFs
# titled by their bibkeys. Enables the cite-fidelity pipeline.
nlm_notebook: [UUID or omit if no notebook]
nlm_url: [https://notebooklm.google.com/notebook/UUID or omit]
---
```

## Step 5b: Source Inven