Book Mirror

---
name: book-mirror
version: 0.1.0
description: Take any book (EPUB/PDF), produce a personalized chapter-by-chapter analysis with two-column tables. Left column preserves the chapter content; right column maps every idea to the reader's actual life using brain context. Output is a single brain page at media/books/<slug>-personalized plus an optional PDF via brain-pdf.
triggers:
  - "personalized version of this book"
  - "mirror this book"
  - "two-column book analysis"
  - "apply this book to my life"
  - "how does this book apply to me"
tools:
  - search
  - query
  - page_get
  - page_put
  - link
  - entity_recall
  - chronicle_since
  - get_brain_identity
mutating: true
writes_pages: true
writes_to:
  - media/books/
---

# book-mirror — Personalized Chapter-by-Chapter Book Analysis

> **Convention:** see `_brain-filing-rules.md` (via `get_skill _brain-filing-rules`)
> for the sanctioned `media/<format>/<slug>` exception this skill files under.
>
> **Convention:** see conventions/quality.md (via `get_skill conventions/quality`)
> for citation rules, back-link enforcement, and output quality bars.
>
> **Convention:** see conventions/brain-first.md (via `get_skill conventions/brain-first`)
> for the lookup chain (brain → search → external) the context-gathering
> phase follows.

## What this does

Given a book (EPUB or PDF), produce a brain page where every chapter is
summarized in detail on the left and mirrored back to the reader's actual life
on the right, using their own words, situations, people, and patterns from
the brain. Output is a brain page at `media/books/<slug>-personalized`.

This is NOT a generic book summary. The right column is the value: it makes
the book read like a therapist who knows the reader is leaving notes in the
margins. If the user wants a flat summary instead, route them to a different
skill.

## Trust contract (read this before running)

book-mirror is an orchestration the agent runs itself, with a strict trust
narrowing on the fan-out:

- The orchestrating agent spawns N **read-only** chapter subagents (one per
  chapter) via its own subagent mechanism (e.g. the Task tool). Each chapter
  subagent is allowed `page_get` and `search` ONLY. They CANNOT call
  `page_put` or any mutating tool. They produce markdown analysis via their
  final message.
- The orchestrator reads each subagent's result, assembles the final
  two-column page, and writes it via a single trusted `page_put`.
- This means untrusted EPUB/PDF content cannot prompt-inject any
  `people/*` page. The trust narrowing happens at the tool allowlist,
  not at the slug-prefix layer.

## The pipeline

```
1. ACQUIRE   → User has the EPUB/PDF locally (manual; book acquisition is
               deliberately not part of this skill — see "Acquiring the
               book" below).
2. EXTRACT   → Pull chapter text from EPUB/PDF into one .txt per chapter.
3. CONTEXT   → Gather everything the brain knows about the reader.
4. ANALYZE   → Fan out N read-only chapter subagents.
5. ASSEMBLE  → Orchestrator reads each result and writes one page_put.
6. PDF       → Optional: render via skills/brain-pdf for delivery.
```

## 1. Acquiring the book

Book acquisition (legal-grey-area downloading) is deliberately out of
scope. The user drops the EPUB/PDF manually. Common paths:

```bash
# User-supplied path
ls path/to/book.epub
ls path/to/book.pdf
```

The brain is DB-canonical — the book file stays on the local filesystem
in a working directory; only the finished analysis page goes into the
brain.

## 2. Text extraction

Goal: one `.txt` file per chapter under a temp directory. The agent has
shell + python access; the analysis fan-out is downstream of this and
takes the extracted directory as input.

### EPUB

```bash
SLUG="this-book"                                # kebab-case
WORK="$(mktemp -d)/$SLUG"
mkdir -p "$WORK/chapters"
unzip -o path/to/book.epub -d "$WORK/unpacked"

# Find content files (XHTML/HTML), sorted (chapter order = sort order)
find "$WORK/unpacked" -name "*.xhtml" -o -name "*.html" | sort > "$WORK/files.txt"

# Strip HTML to text per chapter
python3 - <<'PY'
from bs4 import BeautifulSoup
import os, sys
work = os.environ['WORK']
files = open(f'{work}/files.txt').read().splitlines()
for i, path in enumerate(files, 1):
    html = open(path, encoding='utf-8', errors='replace').read()
    text = BeautifulSoup(html, 'html.parser').get_text('\n')
    text = '\n'.join(line.strip() for line in text.splitlines() if line.strip())
    with open(f'{work}/chapters/{i:02d}.txt', 'w') as f:
        f.write(text)
PY
```

If `bs4` is missing: `pip3 install beautifulsoup4 lxml`.

Inspect the chapter files to identify which are real chapters vs front
matter (TOC, copyright, acknowledgments). Often the EPUB ships one file
per chapter; sometimes multiple chapters per file. Use
`head -5 "$WORK/chapters/"*.txt` to spot-check.

### PDF

```bash
pdftotext -layout path/to/book.pdf "$WORK/full.txt"
```

Then split by chapter heading (look for "Chapter N", "CHAPTER N", or
all-caps title lines) using `awk` or `python`. If the PDF is a scan with
no embedded text, fall back to OCR via `skills/brain-pdf` or another
vision tool.

### Quality check

For each chapter file:

- Word count > 1500 (typical chapter range 2k–8k words).
- No HTML tags.
- Paragraphs preserved with `\n\n`.

Save a `chapters/INDEX.md` mapping chapter number → title → file → word
count for reference.

## 3. Context gathering

This is the most critical step. The right column is only as good as the
context fed to each chapter subagent.

### What to pull

1. **Identity** — `get_brain_identity` plus any identity/self pages the
   user maintains (e.g. `personal/user-profile`, `personal/soul`). Read full.
2. **Recent daily memory** — last 14 days via `chronicle_since`, plus
   recent pages under `personal/reflections/` or wherever the user files
   daily notes (`page_list` / `search`).
3. **Topic-relevant brain searches** tuned to the book's themes:
   - `query "marriage"`, `query "couples therapy"` for a marriage book.
   - `query "founders"`, `query "fundraising"` for a business book.
   - `query "shame"`, `query "anger"` for a psychology book.
4. **Brain pages for relevant entities** — `entity_recall "<name>"` for
   people who will likely come up.
5. **Standing patterns** — anything in the user's reflections or
   originals that's been recurring.

### Assemble a context pack

Write everything to a single file every chapter subagent reads:

```bash
CONTEXT="$WORK/context.md"
{
  echo "## Identity (get_brain_identity + identity pages, if any)"
  # memrain call get_brain_identity '{}'; page_get personal/user-profile, etc.
  echo
  echo "## Recent reflections (last 14 days)"
  # chronicle_since + recent daily reflections — adapt to the user's filing scheme
  # ...
  echo
  echo "## Topic-relevant brain pages"
  # query the book's key themes, embed top results
  # ...
  echo
  echo "## Themes & cruxes"
  # A 1-page summary, written by the agent, calling out:
  # - What's currently active in the user's life that this book intersects
  # - Specific quotes from the user that map to book themes
  # - People and dates that should appear in the right column
} > "$CONTEXT"
```

Make this dense. It's read by every chapter subagent.

## 4. Analysis: fan out the chapter subagents

For each chapter file, spawn a read-only subagent with:

- The chapter text (`$WORK/chapters/NN.txt`)
- The full context pack (`$WORK/context.md`)
- `allowed tools: page_get, search` only (trust contract above)
- Instructions to produce the two-column markdown for that chapter

Then the orchestrator:

- Validates inputs and loads chapter files.
- Estimates cost/effort up front and confirms with the user before a large
  fan-out (per skills/ask-user — a 30-chapter book is a real spend).
- Runs the N chapter subagents (parallel where the harness allows).
- Waits for every one to complete; collects each final markdown analysis.
- Assembles all chapters into one page with frontmatter + intro +
  per-chapter sections + closing.
- Writes ONE `page_put` to `media/books/<slug>-personalized`.
- Reports a summary envelope:
  `{"slug": "...", "chapters_total": N, "chapters_completed": N, "chapters_failed": 0}`.

If any chapter failed, keep the completed analyses on disk under
`$WORK/results/` and re-run only the failed chapters — retry is cheap
when per-chapter results are cached.

### Model: synthesis tier by default

Chapter analysis wants synthesis-tier reasoning (Sonnet). The utility
tier (Haiku) works for drafts but the right-column quality drops
noticeably — the texture that makes the analysis read like a therapist
who knows the reader needs synthesis-grade reasoning.

### Cost gate

Never launch the full fan-out silently. Present the chapter count and a
rough cost estimate, and get an explicit go-ahead (skills/ask-user
choice gate) before submission. Scripted/unattended runs must have been
explicitly pre-authorized by the user.

## 5. PDF (optional)

After the brain page is written, render to PDF using `skills/brain-pdf`:

```bash
# The page is already in the brain via page_put; nothing to add here.
# Then invoke brain-pdf:
# (see skills/brain-pdf/SKILL.md for the PDF invocation)
```

## 6. Fact-check and cross-link

After the page lands, run a fact-check pass on factual claims about the
reader (parents, siblings, marriage history, jobs, heritage). Common error
patterns to look for:

- Conflating the reader's parents' relationship with patterns in extended
  family.
- Inventing therapy backstory ("after his parents' divorce…") when the
  reader's parents are still together.
- Wrong number/age of children, wrong spouse / kid / sibling names.

If you can't verify a claim (check `entity_facts` / identity pages),
remove it. Better to lose texture than to introduce a falsehood.

Cross-link entities mentioned in the analysis:

- For every person the right column references with a brain page, add a
  back-link from `people/<slug>` to the new `media/books/<slug>-personalized`
  page via the `link` tool (per `conventions/quality.md` Iron Law).

## Quality bar (the bar)

The **left column** should:

- Preserve the author's actual stories, statistics, frameworks, examples.
- Quote memorable phrases verbatim.
- Be detailed enough that the reader could skip the book and not lose much.

The **right column** should:

- Use the reader's *actual quoted words* from the context pack.
- Reference *specific* dates, situations, people by name.
- Read like a therapist who knows the reader is leaving notes in the margins.
- Be plain about direct hits ("This is exactly the [name a real situation]").
- Be honest about misses ("This chapter is less directly relevant
  because…"). Don't force connections.

The **whole document** should feel like one coherent voice, calibrated to
the reader's actual life rather than a generic profile, and honest about
where the book's framing breaks down for this specific reader.

## Anti-patterns (do not do these)

- ❌ **Skimming chapters.** Standing instruction: preserve detail.
- ❌ **Generic right column.** "This might apply if you've ever felt…" →
  kill on sight.
- ❌ **Factual errors about the reader's life.** Always fact-check after
  assembly.
- ❌ **Giving a chapter subagent page_put access.** Trust contract is
  read-only; the orchestrator does the writing.
- ❌ **Forcing connections.** If a chapter doesn't apply, say so plainly.
- ❌ **Sycophancy or moralizing in the right column.** No "you should…",
  no "consider…", no "perhaps it's time to…".
- ❌ **Truncating the LEFT column.** The book's actual content needs to
  survive.

## Output checklist

- [ ] Book file exists locally (path known).
- [ ] Chapter texts under `$WORK/chapters/*.txt` with sane word counts.
- [ ] Context pack at `$WORK/context.md` is dense.
- [ ] All chapter subagents completed; failed chapters re-run.
- [ ] `media/books/<slug>-personalized` exists in the brain (page_get confirms).
- [ ] Fact-check pass complete (no errors against identity pages or other source-of-truth pages).
- [ ] Cross-links added from referenced people/companies.
- [ ] Optional: PDF rendered via brain-pdf and delivered.

## Related skills

- `skills/brain-pdf/SKILL.md` — render the personalized page to PDF.
- `skills/strategic-reading/SKILL.md` — read a book through a specific
  problem-lens instead of personalizing to the whole reader.
- `skills/article-enrichment/SKILL.md` — same shape applied to articles
  rather than books.


## Contract

This skill guarantees:

- Routing matches the canonical triggers in the frontmatter.
- Output written under the directories listed in `writes_to:` (when applicable).
- Conventions referenced (`quality.md`, `brain-first.md`, `_brain-filing-rules.md`) are followed.
- Privacy contract preserved: no real names, no host-specific filesystem path literals.

The full behavior contract is documented in the body sections above; this section exists for the conformance test.

## Output Format

The skill's output shape is documented inline in the body sections above (see "Output", "Brain page format", or equivalent). The literal section header here exists for the conformance test.

## Anti-Patterns

The full anti-pattern list is in the body sections above; this header exists for the conformance test if the body uses a different casing.