version: "1.0.1" name: lumi-reading-theme-map description: > Build and maintain thematic cluster pages in wiki/themes/<book-slug>/ by linking themes to the chapters and characters they appear in. Use whenever the user wants to analyze, map, or update themes — including phrasings like "map out the themes", "cluster the themes after chapter 5", "what themes appear across the book", "theme analysis", or "update theme pages". allowed-tools:

• Bash
• Read
• Write
• Edit

/lumi-reading-theme-map

TL;DR

Creates and updates wiki/themes/<book-slug>/<theme-slug>.md pages by clustering theme tags already applied by chapter-ingest into coherent cross-chapter themes, then linking each theme to its chapters and the characters associated with it.

A theme page is only created when a theme tag appears in at least two chapters — a single-chapter tag is not yet a theme; it is a local observation. This threshold keeps theme pages meaningful and prevents noise.

Context

Read README.md at the project root before this SKILL.md. The full schema reference lives there. Theme pages live under wiki/themes/<book-slug>/ — namespaced per book. Themes link to chapters via tagged_with/appears_in edges (written by chapter-ingest) and to characters via associated_with/expresses_theme edges (written by this skill).

Theme stubs are seeded by chapter-ingest; this skill promotes stubs to full pages and updates them as more chapters are ingested.

All graph and frontmatter mutations go through _lumina/scripts/wiki.mjs. Never edit wiki/graph/edges.jsonl directly. add-edge is idempotent and writes reverse edges automatically except terminal/symmetric cases.

Inputs

• <book-slug> — the book to operate on.
• Optional --from-chapter <N> — only process theme tags from chapters numbered >= N.

Useful for incremental updates after reading a batch of new chapters.

• No chapter cursor required: theme-map is not spoiler-sensitive. It operates on all

ingested chapters unless explicitly restricted.

Workflow

Step 1 — Collect all theme stubs for the book

node _lumina/scripts/wiki.mjs list-entities themes/<book-slug> --json

For each theme slug found, read its appears_in edges to discover which chapters link to it:

node _lumina/scripts/wiki.mjs read-edges --from themes/<book-slug>/<theme-slug> --type appears_in --json

Step 2 — Apply the two-chapter threshold

Count the chapters that link to each theme. If the count is:

• < 2: leave the stub as-is. Do not write a full theme page. Note these in the

summary report as "pending themes (not yet a cross-chapter pattern)".

• >= 2: proceed to Step 3 for this theme.

The reasoning: a theme tagged in only one chapter might be a local motif rather than a structural theme. Waiting for a second chapter confirmation prevents over-clustering.

Step 3 — Write or update the theme page

For each theme that meets the threshold:

1. Check if a full theme page exists or only a stub:

``bash node _lumina/scripts/wiki.mjs read-meta themes/<book-slug>/<theme-slug> --json ``

1. Update frontmatter via set-meta:

``bash node _lumina/scripts/wiki.mjs set-meta themes/<book-slug>/<theme-slug> updated YYYY-MM-DD ` Required frontmatter fields (see README.md): id, title, type: theme, created, updated, book`.

1. Write (or rewrite) the theme page body with these sections:

• ## Definition — one paragraph explaining what this theme means in the context of

this book. Stay grounded in the text; do not import external literary theory.

• ## Chapters — wikilinks to every chapter where this theme appears, with a one-line

note per chapter on how the theme manifests.

• ## Characters — list the characters most associated with this theme.
• ## Open Questions — aspects of the theme not yet resolved by the ingested chapters.

Writing the body is moderate-risk (rewrites the theme page). For bulk re-clustering (rewriting 5+ theme pages at once), confirm with the user before proceeding.

Step 4 — Link themes to characters

For each character who appears in 2+ chapters sharing this theme, register an association edge:

node _lumina/scripts/wiki.mjs add-edge themes/<book-slug>/<theme-slug> associated_with characters/<book-slug>/<character-slug>

Use judgment: not every character in a chapter expresses every theme. Link only when the character's role is central to the theme's manifestation in that chapter. The engine writes the expresses_theme reverse edge automatically.

Step 5 — Self-verification

After writing all theme pages, verify the threshold invariant:

node _lumina/scripts/wiki.mjs read-edges --from themes/<book-slug>/<theme-slug> --type appears_in --json

Every promoted theme page must have >= 2 appears_in edges. If any page has only one, it was promoted prematurely — revert to stub status and note in the report.

Then update wiki/index.md if new theme pages were created, append the activity via:

node _lumina/scripts/wiki.mjs log reading-theme-map "<book-slug> -> <K> themes promoted, <M> stubs pending"

Run node _lumina/scripts/lint.mjs --json when available; use --fix only for index/frontmatter fixes within this skill's scope.

Output / Definition of Done

• Every theme that appears in >= 2 chapters has a full page under wiki/themes/<book-slug>/.
• Each theme page has bidirectional links: tagged_with/appears_in to chapters,

associated_with/expresses_theme to characters.

• Theme stubs for single-chapter tags remain as stubs (not promoted).
• wiki/index.md updated when pages were created or promoted.
• wiki/log.md has a new entry:

## [YYYY-MM-DD] reading-theme-map | <book-slug> → <K> themes promoted, <M> stubs pending

• Lint/check run where available; unresolved issues are reported with exact slugs.

Guardrails

• Require user confirmation before bulk re-clustering (rewriting >= 5 theme pages).

Single-page updates are safe; mass updates are risky because they rewrite multiple wiki pages atomically.

• Use Write only to create a new theme stub with complete frontmatter. For

frontmatter mutations on an existing page, use wiki.mjs set-meta.

• Graph/frontmatter mutation must go through _lumina/scripts/wiki.mjs; never edit

wiki/graph/edges.jsonl, generated citation files, or existing frontmatter by raw text edits.

• Do not create theme pages from single-chapter evidence. The two-chapter threshold is

the quality gate.

• Do not pass --book to add-edge; the <book-slug> namespace is part of the slug

path.

• Do not add reverse expresses_theme edges manually; add-edge associated_with

creates the reverse automatically.

Examples

<example> Input: user says "map themes for great-gatsby after all 5 chapters". Action: list-entities themes/great-gatsby. Find stubs: class, the-american-dream, isolation, love, illusion. Read appears_in edges for each. class: 4 chapters -> promote. the-american-dream: 3 chapters -> promote. isolation: 1 chapter -> leave as stub. love: 2 chapters -> promote. illusion: 2 chapters -> promote. Write 4 theme pages. Report 1 stub pending. </example>

<example> Input: user says "what themes link to gatsby the character?". Action: read-edges --from characters/great-gatsby/gatsby --type expresses_theme --json. Report results. Read-only query; no writes. </example>

<example> Input: user says "re-cluster all themes from scratch" (5 theme pages would be rewritten). Action: this is a bulk update. Before proceeding, report: "This will rewrite 5 theme pages. Confirm?" Wait for user confirmation before writing. </example>

<example> Input: chapter 3 has been ingested with a new tag mortality. Only one chapter uses it. Action: leave wiki/themes/great-gatsby/mortality.md as a stub. Note in summary: "mortality: 1 chapter (pending second occurrence to promote)". </example>