bookstrap-write-path

name	bookstrap-write-path
description	Execute writing workflow orchestration - writes sections sequentially from outline
invoke	skill
category	orchestration

Write Path Orchestrator

Execute the writing workflow end-to-end, writing sections sequentially from the outline.

What It Does

This orchestrator command:

1. Queries pending write tasks from the database (ordered by sequence)
2. Invokes the writer agent for each section sequentially
3. Verifies completion after each section
4. Handles knowledge gaps by triggering research
5. Tracks progress through the outline
6. Reports completion statistics

Usage

/bookstrap-write-path

Optional Parameters

/bookstrap-write-path --chapter 3
/bookstrap-write-path --max-sections 5
/bookstrap-write-path --start-sequence 12

Workflow

1. Query Pending Write Tasks

SELECT * FROM task
WHERE type = 'write'
AND status = 'pending'
ORDER BY sequence ASC
LIMIT $max_sections;

2. For Each Section Task

a. Mark Task In Progress

TaskUpdate: {taskId: "[task-id]", status: "in_progress"}

b. Invoke Writer Agent

Skill: {skill: "writer", args: "--task-id [task-id]"}

The writer agent will:

• Run pre-write queries
• Check consistency constraints
• Detect knowledge gaps (if any)
• Write the section (if no gaps)
• Extract entities
• Generate embeddings
• Create citations
• Save to manuscript

c. Check for Knowledge Gaps

If writer flagged a knowledge gap:

SELECT * FROM knowledge_gap
WHERE section_ref = $section_id
AND resolved = false
ORDER BY created_at DESC
LIMIT 1;

If gap found:

1. Mark section task as blocked
2. Trigger research path for the gap
3. Pause write path until gap resolved
4. Report to user what research is needed

d. Verify Section Completion

Check that section was properly stored:

from scripts.writer_methods import WriterMethods

# Verify section exists in database
section = db.query(f"SELECT * FROM section WHERE id = $section_id")

# Verify embedding generated
has_embedding = section[0].get('embedding') is not None

# Verify entities extracted
entity_count = db.query(f"SELECT count() FROM [character, location] WHERE ->appears_in<-section.id = $section_id")

# Verify citations created
citation_count = db.query(f"SELECT count() FROM section->cites->source WHERE section.id = $section_id")

e. Update Task Status

If verification passes:

TaskUpdate: {taskId: "[task-id]", status: "completed"}

If blocked on knowledge gap:

TaskUpdate: {
    taskId: "[task-id]",
    status: "blocked",
    metadata: {gap_id: "[gap-id]", gap_question: "[question]"}
}

3. Handle Gaps

When a knowledge gap blocks writing:

KNOWLEDGE GAP DETECTED
======================

Gap: "Need details about wireless operator training protocols in 1943"
Context: Required for Chapter 3, Section 2

Triggering research path...
Run /bookstrap-research-path to resolve this gap
Or continue with /bookstrap-write-path --skip-blocked

4. Report Progress

After processing all tasks (or hitting a gap), report:

WRITE PATH PROGRESS
===================

Sections processed: [count]
Sections completed: [count]
Sections blocked: [count]
Total words written: [count]
Citations created: [count]
Entities extracted: [count]

MANUSCRIPT STATUS
-----------------
Chapter 1: [completed/in-progress/pending]
Chapter 2: [completed/in-progress/pending]
Chapter 3: [in-progress] (blocked on section 3.2)

NEXT STEPS
----------
- Resolve knowledge gap to continue Chapter 3
- Run /bookstrap-research-path
- Or run /bookstrap-edit to review completed sections

Error Handling

Knowledge Gap Detected

When writer discovers missing knowledge:

• Pause write path
• Create knowledge gap record
• Generate research task
• Report to user
• User must run /bookstrap-research-path to proceed

Consistency Check Failed

If pre-write consistency check fails:

• Mark task as blocked
• Report which constraint failed
• Suggest fix (update entity, write missing intro)
• User must resolve manually

Embedding Generation Failed

If embedding cannot be generated:

• Retry once
• If still fails, report configuration issue
• Do not proceed (section needs embedding for queries)

Configuration

Respects settings from bookstrap.config.json:

{
  "orchestration": {
    "write_path": {
      "max_sections_per_run": 10,
      "pause_on_gap": true,
      "auto_trigger_research": false,
      "require_verification": true,
      "commit_after_each": true
    }
  }
}

Example Output

Starting write path orchestration...

Processing section 1 of 5: Chapter 3, Section 1 - "Arrival"
├─ Running pre-write queries...
├─ Consistency checks... PASSED
├─ Knowledge coverage... SUFFICIENT
├─ Writing section... 1,247 words
├─ Generating embedding... Done
├─ Extracting entities... 3 characters, 2 locations
├─ Creating citations... 4 sources cited
├─ Saving to manuscript/chapter-03-rising-action/section-01-arrival.md
└─ Section completed ✓

Processing section 2 of 5: Chapter 3, Section 2 - "Confrontation"
├─ Running pre-write queries...
├─ Consistency checks... PASSED
├─ Knowledge coverage... INSUFFICIENT
├─ Gap detected: "Wireless operator training protocols 1943"
└─ Section BLOCKED (gap flagged)

WRITE PATH PAUSED
=================

Reason: Knowledge gap detected
Gap: "Need details about wireless operator training protocols in 1943"
Context: Required for Chapter 3, Section 2 confrontation scene

Created research task: task_789
Created knowledge gap: gap_456

NEXT STEPS
----------
1. Run /bookstrap-research-path to resolve the gap
2. Once resolved, resume with /bookstrap-write-path --start-sequence 13

PROGRESS SO FAR
---------------
Sections completed: 1
Total words: 1,247
Next section: 3.2 (blocked)

Integration with Other Commands

Before

• /bookstrap-plan-write - Generate write tasks from outline
• /bookstrap-research-path - Ensure knowledge coverage

During

• May trigger /bookstrap-research-path if gaps discovered

After

• /bookstrap-status - Check manuscript progress
• /bookstrap-edit - Review completed sections
• /bookstrap-export-chapter - Export completed chapters

Best Practices

1. Run plan-write first to generate section tasks
2. Complete research path before writing to minimize gaps
3. Write in sequence to maintain narrative flow
4. Commit after each section (automatic if configured)
5. Review regularly with /bookstrap-edit
6. Resolve gaps promptly to maintain momentum

Recovery from Interruption

If orchestrator is interrupted:

# Resume from last completed section
/bookstrap-write-path --start-sequence [next-sequence]

# Or skip blocked sections temporarily
/bookstrap-write-path --skip-blocked

The orchestrator remembers progress via task status in database.

Implementation Notes

This orchestrator is implemented as a skill that:

• Uses TaskList to find pending write tasks
• Invokes writer agent skill for each section
• Uses writer_methods.py for verification
• Detects gaps and triggers research coordination
• Updates tasks using TaskUpdate
• Commits after each section if configured
• Reports progress and blocks to user

The orchestrator does NOT write content itself - it coordinates the writer agent.