Writing Workflow

The expansion of CLAUDE.md → The Core Loop. Read this before drafting a section, outlining a paper, or planning a revision. It turns the five-word loop Question → Evidence → Draft → Verify → Cite into a procedure with templates.

The governing constraint never changes: you cannot write to a thesis you have not read, and you cannot cite a source you do not have. Planning exists to surface the missing evidence before you draft around it.

The Core Loop, expanded

If drafting goes sideways: STOP, re-read the Question, re-plan. A drifted argument is the long-session failure mode (CLAUDE.md → After Compaction).

When to write a section plan

Write a plan to tasks/todo.md (or a spec folder, below) when:

• The section makes a load-bearing argument (intro, discussion, abstract).
• You do not yet have all the evidence in the library.
• The section is protected under CLAUDE.md → Protected Claims (thesis, a reported quantity, methods, an argument-carrying citation, scope).
• You are unsure the claim is defensible.

For a one-sentence fix, a citation-format tidy, or a typo: just do it. Do not ceremony-plan trivial edits.

Section-plan template (copy-pasteable)

Paste into tasks/todo.md. One block per section under work.

## Section: [Introduction / Methods / Discussion / …]  →  file: sections/<name>.tex

**Question (disputable claim this section must establish):**
> [One sentence. Not "write the intro" — "Establish that hallucinated tool calls in
>  multi-turn agents are understudied and that pre-execution gating closes that gap."]

**Word budget:** [from MANUSCRIPT_MAP.md → Structure table]   **Tense:** [intro present / methods past / results past]

### Evidence inventory (library only — references.bib + sources/)
| Claim in the section | Supporting source (`.bib` key) | What it licenses | Gap? |
|---|---|---|---|
| [sub-claim 1] | `tooluse2023` | 70% accuracy *in single-turn QA* | setting ≠ multi-turn agentic — do NOT overclaim |
| [sub-claim 2] | — | — | **[CITE] needed** — not in library |
| [sub-claim 3] | author's own data (`tab:toolacc`) | >40% fewer hallucinated calls, tested harness | reproducible? see methods |

### Draft plan (topic sentence per paragraph)
1. [P1 topic sentence — given→new]
2. [P2 topic sentence]
3. [P3 topic sentence]

### Verification checklist (CLAUDE.md mandatory order)
- [ ] Every `\cite{}` resolves in references.bib (citation-gate)
- [ ] Every quote verbatim + locator
- [ ] Each claim's verb/quantifier matches its source (no overclaim)
- [ ] Numbers match tables/abstract; units stated; N reported
- [ ] Cross-refs resolve (`\ref` ↔ `\label`); every display item cited in text
- [ ] Compiles clean (latexmk + biber, no undefined refs in .log)
- [ ] Gap count reported: (sourced / placeholder / unverified)

### Not Now (off-thesis, parked)
- [ ]

The Question line becomes the section's acceptance criterion: the section is done when a skeptical Reviewer 2 would agree that one sentence is established and nothing beyond it is claimed.

Manuscript lifecycle

A paper moves through stages; the Stage field in MANUSCRIPT_MAP.md → Status records where it is. Match your behavior to the stage.

idea → outline → first draft → internal review → revision → submission → reviewer response → camera-ready

Stage transitions that change the thesis, a reported quantity, the methods, an argument-carrying citation, or the scope are Protected Claims — request the author's approval and record it in tasks/decisions.md.

The MANUSCRIPT_MAP.md Structure-table workflow

MANUSCRIPT_MAP.md is the single most important file; the Structure table is its operational core. Treat it as the plan-of-record for the whole paper.

1. Before drafting a section, read its row. The Purpose (claim it establishes) cell is the section's Question. If that cell still says <...>, stop and write the claim first — drafting to an unstated claim guarantees drift.
2. One section per work unit. Pick one row, run the Core Loop, finish it, update its Status cell (not started → drafting → drafted → verified). Do not draft three sections in one pass — context bleeds and the argument blurs.
3. Honor the budget. The Budget cell is a word cap. Use texcount to measure (CLAUDE.md → Model vs Code — never estimate). Over budget ⇒ cut, do not negotiate the budget silently.
4. Cross-check Key sources. The Key sources table lists the references the paper stands on and, crucially, what each must not be overclaimed as. Before citing one of these in a new context, confirm the matrix/population/scope matches.
5. Update display items. When you add a \label, add the figure/table to the Figures & tables row so the "referenced in" column stays true. Every display item must be cited in the text and vice versa (verification step 5).
6. Park off-thesis material in MANUSCRIPT_MAP.md → Not Now (or `tasks/todo.md →

   Not Now`), never in the draft.

A change to a Structure-table row that alters what a section claims is a scope change — protected.

Spec folders for multi-session sections

For a section that spans sessions (a contested discussion, a methods rewrite, a response to a major revision), create a timestamped spec folder so the plan survives /clear and compaction:

tasks/specs/
  2026-06-03-discussion-rewrite/
    plan.md          # the section plan (template above)
    evidence.md      # the evidence inventory + gaps, kept current
    decisions.md     # framing/scope calls made along the way (mirror to tasks/decisions.md)

A fresh session reads the spec folder to recover what was planned and why without re-deriving it. Use spec folders only when the work genuinely outlives one session; otherwise a tasks/todo.md block is enough.

Handoffs between sessions

Before /clear or at session end, write what the next session needs: tasks/handoff-*.md (current section, open placeholders, gap count, the next Question). The session-start hook points the next session at it. The clear is destructive for in-memory state, not for files — so the files must carry the plan.

Anti-patterns