writing

What this skill does

# Writing

**Entry point for all writing tasks.** Routes to quick mode or project workflow.

## Shared Enforcement

Load the constraint index for the writing workflow:

!`cat ${CLAUDE_SKILL_DIR}/../../references/constraints/writing-common-constraints.md`

**Router loads index only.** Phase skills load specific atomic files relevant to their phase.

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

## Decision Flowchart (This IS the Spec)

```
START
  │
  ├─ Quick edit? ("check this paragraph", inline short text)
  │  YES → Load writing-general/SKILL.md → Apply rules → Return → EXIT
  │
  ├─ Active workflow? (.planning/ACTIVE_WORKFLOW.md exists)
  │  YES → Read ACTIVE_WORKFLOW.md → Resume at current phase → EXIT
  │
  └─ New project
     → Phase 2: Detect Domain, Gather Sources
     → Launch writing-setup
```

If text and flowchart disagree, the flowchart wins.

## Step 1: Detect Mode

**Quick Mode Indicators** (edit text directly, no workflow):
- “Check this paragraph”
- “Edit this text”
- “Review my writing”
- Short text provided inline
- No mention of “project”, “paper”, “article”

→ If quick mode: discover the writing-general skill path via `${CLAUDE_SKILL_DIR}/../../skills/writing-general/SKILL.md`, then `Read()` the output path and apply rules to text.

**Project Mode Indicators** (full workflow):
- “Write a paper on...”
- “Start a law review article”
- “Draft an economics paper”
- Mentions thesis, argument, research

→ If project mode: Continue to Phase 2 below.

## Step 2: Check for Active Workflow

```
if .planning/ACTIVE_WORKFLOW.md exists:
    Read(“.planning/ACTIVE_WORKFLOW.md”)
    Read(“.planning/PRECIS.md”)
    Read(“.planning/OUTLINE.md”)
    → Resume at current phase with appropriate domain skill
else:
    → Continue to Phase 3 (new project setup)
```

---

## Project Mode Workflow

Creates PRECIS.md (thesis, audience, claims) and OUTLINE.md (structure), then hands off to domain-specific writing skill.

## Project Structure

Writing projects should follow this standardized structure:

```
project-name/
├── .planning/
│   ├── ACTIVE_WORKFLOW.md      # Workflow state (auto-created)
│   ├── PRECIS.md               # Thesis, audience, claims, counterarguments
│   ├── OUTLINE.md              # Master document structure
│   └── LEARNINGS.md            # Append-only decision log (angle, rejected framings, R4s) — see writing-learnings-log.md
├── outlines/                    # Detailed section/part outlines
│   ├── Part I (Outline).md
│   ├── Part II (Outline).md
│   └── ...
├── drafts/                      # Prose drafts (expanded from outlines)
│   ├── Part I (Draft).md
│   ├── Part II (Draft).md
│   └── ...
├── references/                  # Source materials, notes
│   ├── sources.bib              # BibTeX bibliography (pandoc --citeproc reads this)
│   └── [topic-notes].md         # Research notes by topic
└── scratch/                     # Working files (gitignored)
    └── brainstorm-notes.md
```

### Directory Purposes

| Directory | Purpose | Tracked in Git |
|-----------|---------|----------------|
| `.planning/` | Workflow state + high-level docs (PRECIS, OUTLINE) | Yes |
| `outlines/` | Detailed outlines per section/part | Yes |
| `drafts/` | Prose versions of outlines | Yes |
| `references/` | Sources, research notes | Yes |
| `scratch/` | Temporary working files | No |

### Progressive Expansion Workflow

Writing proceeds through levels of detail:

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

**Each level expands the previous.** Don’t skip levels:
- PRECIS before OUTLINE
- Master OUTLINE before section outlines
- Section outline before drafting prose

### File Naming Convention

For multi-part documents:
- Section outlines: `outlines/Part I (Outline).md`
- Prose drafts: `drafts/Part I (Draft).md`

For single documents:
- Master outline in `.planning/OUTLINE.md` is sufficient
- Draft: `drafts/draft.md` or `drafts/[title].md`

### Creating Project Structure

When starting a new writing project, create the directories:

```bash
mkdir -p outlines drafts references scratch .planning
echo “scratch/” >> .gitignore
```

## Writing Workflow Overview

```
/writing (entry point)
    │
    └── skills/writing/ (this skill)
            │ Mode detect, source gathering, topic exploration
            │ GATE: Sources gathered, domain detected
            │
            └── skills/writing-setup/ (project foundation)
                    │ PRECIS.md, OUTLINE.md, ACTIVE_WORKFLOW.md
                    │ GATE: All three files exist with required content
                    │
                    └── skills/writing-outline/ (per section)
                            │ outlines/[Section] (Outline).md
                            │ GATE: Outline cross-references PRECIS claims
                            │
                            └── skills/writing-draft/ (per section)
                                    │ Domain skill loaded (legal/econ/general)
                                    │ drafts/[Section] (Draft).md
                                    │ GATE: All sections drafted with depth
                                    │
                                    └── /writing-review (diagnose → REVIEW.md)
                                            │ Hierarchical review: section → transition → document
                                            │ .planning/REVIEW.md
                                            │ GATE: All sections reviewed, all levels complete
                                            │
                                            └── /writing-revise (fix from REVIEW.md + complete)
```

## When to Use

Invoke this skill for:
- Discovering what to write about from reading patterns
- Gathering sources and references for a known topic
- Finding thematic connections across highlights
- Building an outline with supporting quotes

## Prerequisites

Source searching is handled by the **librarian agent** (`workflows:librarian`), which routes through NLM first, then Readwise via the official CLI. You do NOT need direct Readwise MCP access.

## Critical: ALL Source Searches Go Through Librarian

<EXTREMELY-IMPORTANT>
**NEVER call Readwise MCP tools directly. NEVER spawn general-purpose agents for searches.**

ALL source gathering MUST go through the librarian agent, which enforces:
1. Check NLM first (curated knowledge)
2. Readwise via official CLI (context-safe)
3. Structured output (sources, quotes, synthesis)

**If you're about to call `mcp__readwise__*` or spawn a `general-purpose` agent for search, STOP.**
</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT>
## The Iron Law of Clarifying Intent

**NO SEARCH WITHOUT CLARIFYING INTENT FIRST. This is not negotiable.**

In Gathering Mode, you MUST use `AskUserQuestion` to understand angle and audience BEFORE launching any librarian searches. Searching without intent produces scattered results that don't serve an argument.

If you find yourself about to search before the user has confirmed their angle:
1. STOP immediately
2. Ask the clarifying questions (Phase 1)
3. THEN decompose into search themes
4. THEN launch parallel librarian agents

**Searching before clarifying is like outlining before having a thesis.** You'll gather sources for a topic, not an argument. The sources won't support any specific claim because you don't have one yet.
</EXTREMELY-IMPORTANT>

### Librarian Search Pattern

For a topic