sequential-read

# 📖 Sequential Read

Read prose (novels, non-fiction, articles) by ingesting content in semantic chunks and building structured reflections iteratively. The output captures how your perspective developed over the course of reading — predictions that were wrong, questions that got answered, opinions that shifted — not just a retroactive summary.

## Invocation

| Command | Description |
|---|---|
| `/sequential-read <path-to-file>` | Run a full reading session |
| `/sequential-read <path-to-file> --lens <persona>` | Read with a perspective (e.g., "skeptic", "literary critic", "student") |
| `/sequential-read list` | List all sessions |
| `/sequential-read show <session-id>` | Show the synthesis for a completed session |

## Execution Model

**The pipeline runs in spawned sub-agents.** Novel-length reads are a two-phase process: a main reader that handles the bulk of chunks, then a finisher that completes the remaining chunks and writes synthesis. This is the normal flow, not an error.

When the user invokes `/sequential-read`:

1. Parse the command to extract the file path and optional lens
2. Pre-create the session:
   ```bash
   python3 {baseDir}/scripts/session_manager.py create <source-file>
   ```
3. Spawn the **main reader** sub-agent:
   ```
   sessions_spawn with label: reader-{session-id}
   Tell the agent: "Session already exists at {session-id}. Do NOT create it again."
   ```
4. Tell the user the session has started and they'll be notified when it's done
5. **When the main reader returns** (whether it completed or died mid-read):
   - Check session status: `python3 {baseDir}/scripts/session_manager.py get <session-id>`
   - Check how many reflections exist vs total chunks
   - **If synthesis exists:** Done. Present results.
   - **If chunks remain or synthesis is missing:** Spawn a **finisher** sub-agent (see below). This is the expected path for novels.
6. When the finisher returns, present the synthesis and session path.

### The Two-Phase Pattern

For...

# Sequential Read

Read prose (novels, essays, articles) chunk by chunk with structured reflections that capture how your understanding develops over the course of reading — not just a retroactive summary.

## What It Does

Instead of dumping an entire book into context and asking "what did you think?", this skill:

1. **Prereads** the source text and splits it into semantic chunks (~550 lines each, respecting chapter/section boundaries)
2. **Reads** each chunk sequentially, writing a structured reflection after each one — predictions, reactions, revised understanding, questions
3. **Synthesizes** the full reading experience into a final document that preserves the arc of discovery

The output captures what a retroactive summary cannot: predictions that were wrong, questions that got answered chapters later, opinions that shifted, moments of genuine surprise.

## Why It Matters

An AI reading a book all at once produces a book report. An AI reading sequentially produces something closer to a reading experience — the difference between knowing the destination and having walked the road.

Tested on 41+ novels with consistent results. The reading reflections surface genuine engagement: confusion, delight, boredom, revised opinions. The sequential constraint forces honesty.

## Requirements

- OpenClaw with `sessions_spawn` capability
- Python 3
- A plain text file (.txt) of the work to read

## Quick Start

```
/sequential-read ~/books/my-book.txt
```

The skill handles everything autonomously — preread, chunking, sequential reading, synthesis. You'll be notified when it's done.

## Pipeline

```
Source Text → Preread (chunk) → Read (reflect on each chunk) → Synthesize
```

For novels (20+ chunks), the pipeline automatically uses a two-phase reading pattern: a main reader handles ~80% of chunks, then a finisher completes the rest and writes the synthesis. This is normal operation, not error recovery.

## Output

Each session produces:
- Individual chunk reflections in...