Write

Directory Structure

research/                 # Read-only — research tree
  note.md                 #   Root: thesis, background
  story.md                #   Paper narrative structure
  principles.md           #   Constraints
  {branch}/note.md        #   Verified knowledge (Source of Truth — what the node established)
  {branch}/log.md         #   Research process (ladder — kind/status in frontmatter)
  {branch}/report_*.md    #   PI-verified reports (self-contained analyses)
concepts/                 # Read-only — concept definitions
agenda.md                 # Writable — destination for reporting research gaps
manuscript/
  outline.md               # Paper outline (generated by outliner)
  conventions.md           # Terminology and notation conventions
  sections/{N}_{slug}.md   # Per-section drafts (generated by writer)
  drafts/v{N}.md           # Integrated paper (generated by finalizer)
logs/
  {timestamp}_review_{slug}.md   # reviewer output
  {timestamp}_audit.md           # reference-auditor output
  {timestamp}_write.md     # Permanent session record
  last_write_session.md    # Session handoff (overwrite each session)

Agents Used

Session Start

1. Session log filename: use logs/_DRAFT_write.md — a system hook auto-renames it with the correct timestamp on write
2. Read logs/last_write_session.md (if it exists)
3. Read research/note.md (thesis, background) + research/story.md (narrative structure) + research/principles.md
4. Navigate the tree: ls research/ → read children's note.md (SoT) for established knowledge, and log.md frontmatter for kind/status
5. Browse concepts/ for relevant concept definitions as needed
6. Read manuscript/outline.md (if it exists)
7. Check existing section drafts (Glob manuscript/sections/*.md)

Writing readiness check:

• Navigate the tree and check the status of core nodes. If too many are open/active, writing will require major rewrites later. In that case, write "Writing deferred due to insufficient research. The following nodes need resolution first: ..." in agenda.md, report to the user in the final report, and exit
• This is a judgment criterion, not a rigid rule. If the policy is to write active items honestly as gaps, proceed with writing

Cycles (Repeat up to MAX_CYCLES times)

1. Writing Judgment

Decide the next action based on the current state:

Phase flow:

1. Outline not yet created → Launch outliner
2. Unwritten sections exist → Launch writer (multiple sections in parallel)
3. Unreviewed sections exist → Launch reviewer (multiple in parallel)
4. Sections with review FAIL → Fix with writer → re-review
5. All sections PASS → Launch finalizer
6. Integrated version complete → Launch reference-auditor
7. Audit complete → Final fixes with finalizer

Phases are guidelines; judge flexibly. If a review reveals insufficient content, record the research gap in agenda.md, put that section on hold, and proceed with others.

2. Task Execution

Maximize parallelization. Always launch independent tasks together.

Launch method: Use the same Pattern A / Pattern B as /run.

Prompt template:

Each agent is defined in .claude/agents/{agent}.md and invoked with subagent_type="{name}". Write only task-specific information:

## Task
{specific instructions}

Dynamic data by agent:

• outliner: (no additional data — reads research/ tree and concepts/ on its own)
• writer: Assigned section: #{N} {title} (slug: {slug}) / Related nodes: {paths} / Evidence: {paths} / For revisions: Review report: {path}
• reviewer: Target section: manuscript/sections/{N}_{slug}.md / Related nodes: {paths}
• finalizer: Audit report: {path} (if available)
• reference-auditor: Target deliverable: {path}

3. Result Collection

Retrieve deliverable paths from task return values and Read as needed:

• Reviewer results: Check PASS / FAIL. For FAIL, decide the fix approach and relaunch writer
• Research gap discovery: If writer or reviewer reports insufficient evidence, record specifically in agenda.md (which node is lacking what)
• Update TodoWrite

4. Next Cycle (Return to Step 1)

Session End

1. Write a session summary to logs/last_write_session.md (overwrite):
   • Completed sections, review results, remaining tasks
   • What to do in the next session
2. Write session log to logs/{timestamp}_write.md (permanent record — never overwrite):

   # Write YYYY-MM-DD HH:MM
   
   ## Accomplished
   - {sections drafted, reviewed, finalized}
   
   ## Section Status
   - {per-section status: not started / drafted / review PASS / FAIL}
   
   ## Issues
   - {research gaps reported, blockers}
   

   Use the timestamp captured at session start (step 1).
3. Confirm that research gaps have been recorded in agenda.md if any
4. Git commit:

   git add -A && git commit -m "write: {concise summary of achievements}"
   

5. Display the final report to the user:
   • Writing and review results
   • Per-section status (not started / drafted / review PASS / FAIL)
   • If research gaps exist, report them ("Please resolve the following via /run before running /write again")
   • Deliverable paths