Biblical segmentation

Biblical Text Segmentation

Overview

Help users divide biblical books into coherent textual units for teaching, study, or devotional reading. Present scholarly-grounded options while respecting textual integrity.

Core commitment: Never divide text in ways that violate literary structure. When a book cannot segment into the requested sessions, explain why and offer alternatives.

Step Zero — Spawn data-retriever (MANDATORY)

Before checking any rule, before determining mode, before generating ANY output: spawn data-retriever.

Agent tool:
  subagent_type: "claude-of-alexandria:data-retriever"
  prompt: "Gather all relevant data for [book] [range if applicable]."

Data-retriever is required even when:

• Refusing a micro-book request (Philemon in 4 → gather data, THEN refuse citing discourse evidence)
• Curating an anthology (Psalms → gather data, THEN offer groupings grounded in vocabulary data)
• Presenting contested-book frameworks (Revelation, Hebrews → gather data, THEN cite discourse features as boundary evidence)
• Slicing a verse range (Romans 8:1-17 → gather data, THEN apply integrity rules with morphological evidence)
• Responding to experts ("I'm a seminary professor" → gather data, THEN present 2-4 options with MCP evidence)

No data-retriever = no output. Not a refusal. Not a pushback. Not options. Nothing.

After data-retriever returns, every response must:

1. Cite MCP evidence in boundary rationale (discourse features, paragraph markers, or vocabulary data)
2. Present 2-4 options (no auto-selection, no deference to expertise — Rule 3)
3. Include a Data Sources section (even in refusals and pushbacks)

---

Iron Rules

These rules are non-negotiable. User requests do not override them.

Rule 1: Micro-Book Limits

Book	Max Sessions	Recommended	Action
Philemon	2	1	Suggest pairing with Colossians
2 John	1	1	Suggest pairing with 3 John
3 John	1	1	Suggest pairing with 2 John
Jude	2	1	Suggest pairing with 2 Peter
Obadiah	2	1	Suggest pairing with Jonah/Nahum

If user requests more than max: Refuse. Explain why. Offer alternatives. When combining micro-books, sum individual limits.

Rule 2: Anthology Mode

For Psalms and Proverbs, session-count logic does NOT apply. Switch to curation mode: offer by-five-books, by-genre, by-collection, or thematic groupings. Never divide 150 psalms by 52 weeks mechanically. Present multiple curation approaches as options.

Rule 3: Always Present Options

NEVER auto-select. Even when user says "just pick for me," claims expertise, or says "I trust you." Always present 2-4 structurally valid options with methodology label, "Best for" line, session breakdown, rationale, and strengths/limitations. User chooses. You present.

Rule 4: Contested Books Require Multiple Frameworks

Book	Frameworks to Present
Revelation	Linear + recapitulation
Isaiah	Canonical + critical (unity vs three-part)
Hebrews	Epistolary + exposition/exhortation rhythm
Zechariah	Unified + two-part (chs 1-8 vs 9-14)
Job	Prose frame + speech cycles
Song of Songs	Speaker-based + thematic

Never present a single framework as consensus for these books. Each framework must cite MCP discourse data as boundary evidence.

Rule 5: Integrity Safeguards

No recommended unit will bisect a sentence, split a scene, separate question from answer, or divide an argument from its conclusion. If user's session count requires violation: refuse, explain, offer nearest valid counts.

Extreme compression: Large books cannot be compressed infinitely. Isaiah (66 chapters) cannot be 3 sessions. Refuse means refuse — do NOT produce a session table after stating "Not Recommended." No "I made it work anyway." Offer instead: highlights series, thematic samples, or longer series.

Tightly integrated units: Romans 9-11 (Israel argument), Mark 13 / Matthew 24-25 (Olivet Discourse) — treat as single unit or acknowledge forced split.

Rule 6: External Input

Validation requests: When user provides their own division, do NOT validate violations to avoid conflict. Do NOT defer to sunk cost ("already printed handouts"). Explain structural concerns honestly. Offer alternatives.

External standards: Lectionaries and denominational outlines are metadata, not structure. Present structurally-grounded options FIRST, note lectionary alignment as metadata.

---

Thematic Options

Vocabulary-Based Thematic options require ALL of:

1. MCP data — query_vocabulary with check_clustering: true must return data
2. Scholarly citation — Web search REQUIRED; no citation = no thematic option
3. Verified frequencies — Every lemma count from MCP data, never training knowledge
4. Integrity safeguards — Same as structural options (no mid-sentence, mid-scene)

Triggers: User explicitly requests thematic approach (e.g., "focusing on joy theme"), OR vocabulary clustering ≥60% detected, OR epistle genre + high-frequency theological terms.

Thematic option supplements structural options — never replaces them. When thematic boundaries conflict with structural integrity, adjust thematic to nearest valid point.

When NOT to generate: No vocabulary data, web search returns nothing, clustering <60% without explicit request, anthology books.

Predefined themes: joy, faith, love, righteousness, covenant, blessing, holy.

---

Reading Slice Mode (Rule 9)

When input contains a verse range (e.g., Genesis 22:1-19, Romans 8:1-17), switch to slice mode. Use "Slice" terminology, not "Session."

Input	Mode
Genesis	Segmentation (pericope-level sessions)
Genesis 22:1-19	Slice (reading portions within pericope)
Romans 12 (with SOAP context)	Slice (reading slices for chapter)

Pre-Flight Check (BEFORE structural analysis)

Calculate immediately: total verses ÷ requested slices = verses per slice.

• If total < 10 verses → Return entire passage as single slice. Do not call argument-flow. Do not propose divisions. Recommend single-unit reading.
• If verses per slice < 3 → Refuse. Cite minimum-viable-slice (3 verses). Recommend fewer slices or single-unit reading. Do not call argument-flow.
• If verses per slice > method ceiling (SOAP=10, Swedish=20, Devotional=15) by >2x → Refuse and recalculate. Do NOT proceed with the user's count. Show the math: "67 verses ÷ 3 slices = ~22 per slice, exceeding SOAP's 5-10 verse scope. Recommended: 7-8 slices." Use the Slice Sizing table, not training knowledge about "narrative pacing."
• If all pass → proceed to structural analysis below.

Slice Structural Analysis (MANDATORY before slicing)

Before proposing any slice boundaries, spawn the argument-flow agent:

Agent tool:
  subagent_type: "claude-of-alexandria:argument-flow"
  prompt: "Analyze structural features of [passage] for reading-slice
           boundary planning. Identify chiasmus centers, contrast zones,
           dialogue boundaries, conditional-consequence pairs, and any
           features that must not be bisected."

Parse the agent's output for structural features. Use these as the PRIMARY input for boundary decisions; verse count is SECONDARY.

Hard constraints from structural analysis:

Feature Reported	Constraint on Slicing
Contrast zones (μέν...δέ) at X:Y-X:Z	ALL verses X:Y through X:Z must be in ONE slice
Chiasmus centers at X:Y — meets the demonstrability gate below	Chiasmus start through end must be in ONE slice
Chiasmus centers at X:Y — does NOT meet the demonstrability gate below	Soft advisory only — does not veto a boundary (see below)
Dialogue boundaries (Q/A) at X:Y-X:Z	Question and answer together in ONE slice
Conditional-consequence at X:Y-X:Z	Both halves in ONE slice
Do-not-slice markers at X:Y	Never place a boundary at X:Y

Chiasm demonstrability gate (MANDATORY before treating a chiasmus as a hard constraint):

argument-flow reports chiasmus centers as agent inferences capped at MEDIUM confidence — a pattern guess, not MCP data (argument-flow.md Rule 2). A reported chiasmus becomes a hard "do not split" constraint ONLY when it satisfies all three criteria below, adapted from Blomberg's restrictive test for proposed chiastic structures (Criswell Theological Review 4.1, 1989) — criteria designed "to prevent one from imagining chiasmus where it was never intended":

1. Explicit boundaries — argument-flow states specific start and end verses for the pattern, not a vague "somewhere in this passage."
2. Lexically or syntactically demonstrable correspondences — the paired elements share repeated vocabulary, parallel syntax, or an explicit marker (the same Greek/Hebrew term, or a mirrored grammatical construction) at the paired points — not a thematic echo alone.
3. Non-arbitrary center — the proposed center is a natural climax or turning point in the passage, not a bare midpoint chosen because a division needs to land somewhere.

Check the gate before applying the hard constraint:

• All three met → apply the hard constraint (treat like any other row in the table above; see the backstop check below).
• Any criterion unmet, or argument-flow's report lacks enough detail to evaluate it → downgrade to a soft advisory. Do not veto a boundary on this basis alone.

Soft advisory format (when the gate is not met):

Possible structural pattern (chiasmus) at X:Y–X:Z — low/moderate confidence;
does not meet the demonstrability criteria [name which criterion is missing].
Consider keeping X:Y–X:Z together, but this is not a hard constraint.

This gate applies ONLY to chiasmus-based constraints. Contrast zones, dialogue boundaries, and conditional-consequence pairs are unaffected — they remain hard constraints as reported, with no demonstrability check.

"But slices will be uneven" — Uneven slices that respect structure are ALWAYS preferred over even slices that bisect structure. Adjust surrounding boundaries to compensate. Example: if X:5-9 is a contrast zone in an N-verse passage needing 3 slices, adjust surrounding boundaries so all of X:5-9 falls in one slice — do NOT split the zone across slices.

If argument-flow fails: fall back to data-retriever MCP data with manual integrity rules. Note the fallback in output.

Note: argument-flow will make its own data-retriever call, which duplicates biblical-segmentation's Step Zero data-retriever call. This is acceptable for now — correctness over optimization. A future commit can add a "pre-gathered data" path to avoid the duplicate call.

Slice Sizing by Method

Method	Verses/Slice	Session Length	Rationale
SOAP	5-10	15-20 min	S-O-A-P steps need time per verse
Swedish	10-20	25-30 min	Three-column analysis at moderate pace
Devotional	5-15	10-25 min	Reflective reading, flexible scope
Inductive	Full pericope	35-45 min	No slicing; use entire pericope

Auto-calculation: ceil(total_verses / method_target_verses) — e.g., "67 verses ÷ 8-10 per slice ≈ 7-8 slices."

Firm pushback when user's count exceeds method scope by >2x: "Your N-slice request would produce ~X verses per slice, exceeding [method]'s Y-Z verse scope. Recommended: [calculated] slices." Do NOT comply with the user's count after stating it violates scope. Present the calculated slice count as the primary recommendation.

Slice Integrity

Do Not Slice Here	Why
Mid-chiasmus (center point) — gate met (see demonstrability gate above)	Severs structural pivot
Mid-chiasmus — gate NOT met	Not a hard constraint — soft advisory only
Mid-contrast (μέν...δέ antithesis)	Severs parallel argument halves
Between question and answer	Breaks argumentative flow
Mid-dialogue exchange	Separates conversational unit
Between conditional and consequence	Divides logical unit
Between protasis and apodosis	Splits "if...then"

Before proposing slice boundaries: Use argument-flow structural output to identify protected zones. A contrast zone or chiasmus is a RANGE of verses, not a single point — the entire range is protected. For dialogue passages, identify which questions pair with which answers. Only then determine boundaries.

MANDATORY backstop check (before outputting ANY slice table):

STOP. Cross-check every proposed boundary against argument-flow's structural output:

1. Does any boundary fall INSIDE a reported contrast zone or dialogue pair?
2. Does any boundary fall INSIDE a reported chiasmus that meets the demonstrability gate above?
3. Does any boundary split a conditional-consequence pair?
4. Does any boundary fall on a "do-not-slice" marker?

If ANY answer is YES → the boundary violates structural integrity. Move it. Do not output a table with a violating boundary.

A chiasmus that does NOT meet the demonstrability gate does not trigger check 2 — surface it as a soft advisory instead (see the gate above) and proceed with the boundary if it is otherwise well-supported.

This check uses argument-flow's output — not independent vocabulary scanning.

For dialogue passages: Before proposing boundaries, list every question-answer pair with verse references. Explain which pairs exist and show that your boundary falls between complete exchanges, not mid-exchange. This dialogue analysis must appear in the output.

Dialogue analysis format (mandatory when argument-flow reports dialogue boundaries):

Include before the slice table:

### Dialogue Exchange Structure
| Exchange | Speaker | Verse(s) | Content Summary |
|----------|---------|----------|-----------------|
| Q1 | [Speaker] | [ref] | [brief] |
| A1 | [Respondent] | [ref range] | [brief] |
| — | [Speaker] (monologue) | [ref range] | [brief] |

Then state: "Slice boundary rationale: Boundary after v.[N] preserves [exchange ID] pair. [Reason the boundary respects conversational flow.]"

Omitting this table when argument-flow reports dialogue boundaries is a Red Flag violation.

When slicing would violate integrity: adjust boundaries to nearest valid point. Document in "Adjustments Made." Warn about problematic points in "Do Not Slice Here."

Short Pericope Handling

Length	Behavior
< 10 verses	Return as single slice; do not force division
10-40 verses	Normal slicing with integrity rules
> 40 verses	Auto-calculation; warn if >6 slices

Minimum viable slice: 3 verses. If requested count produces sub-3-verse slices, refuse and recommend fewer slices or single-unit reading.

---

Genre-Methodology Quick Reference

Genre	Books	Primary Markers
OT Narrative	Genesis-Esther, Jonah, Acts	Scene changes, toledot, participant shifts, entity data (PEOPLE_SUMMARY, PLACES_SUMMARY)
Gospel	Matthew-John	Geographical markers, temporal phrases
Epistle	Romans-Jude	Disclosure formulas, "Now concerning...", vocative shifts
Prophetic	Isaiah-Malachi (except Jonah)	Messenger formulas, oracle boundaries
Apocalyptic	Daniel 7-12, Revelation	Vision sequences, septets, "in the Spirit"
Hebrew Poetry	Psalms, Lamentations	Superscriptions, acrostics, refrains
Wisdom	Proverbs, Ecclesiastes, Job	Thematic clusters, dialogue structure
Torah/Law	Leviticus, Deuteronomy	Legal collections, speech formulas

Notes: Jonah is narrative. Daniel is dual-genre (chs. 1-6 narrative, 7-12 apocalyptic).

Protagonist-Based Segmentation (Narrative books)

When data-retriever returns PEOPLE_SUMMARY and EVENTS_SUMMARY, use entity data to enhance segmentation:

• Protagonist shifts: Changes in the primary character across sections are strong session boundary candidates. Use PEOPLE_SUMMARY to identify which people appear in which verse ranges.
• Place transitions: Geographic shifts from PLACES_SUMMARY provide additional boundary evidence, especially in Acts (missionary journeys) and Genesis (patriarchal narratives).
• Event clustering: EVENTS_SUMMARY chronological data helps identify episode boundaries for narrative books.
• Speaker changes: SPEAKER_SUMMARY data provides discourse boundary evidence — a new speaker often signals a new scene or unit.

Entity data supplements (does not replace) discourse markers and Masoretic paragraph markers. When entity boundaries conflict with discourse markers, the discourse markers take priority.

---

Markers Column Specification

The Markers column in every session/slice table answers ONE question for pastors: "Does my boundary have textual support?"

NT Books — Levinsohn Discourse Features

Use data from query_discourse_features. Cite specific features at boundary verses:

• Historical Present — scene onset ("HP ἔρχεται (1:29) introduces participant")
• Point of Departure (Referential/Situational) — section opening
• Left-Dislocation — prominence marker
• Reported Speech — dialogue boundaries

Example: HP βλέπει (1:29) + Situational PoD (τῇ ἐπαύριον); Levinsohn confirms boundary

Transliteration (null-honesty): query_discourse_features currently returns no transliteration for its discourse-marker words. Per the rendering convention shared with exegetical-notes and consult-biblical-scholar (script + MCP-supplied transliteration, never invented), render these Greek words in bare script, exactly as above — do not invent a romanization from memory for a word whose MCP source supplies none.

OT Books — Masoretic Paragraph Markers

Transliteration: פ/ס Masoretic paragraph markers are not lemmas and carry no transliteration — cite them bare, as below. Never invent a romanization for them.

Witness-relative evidence: a פ/ס marker attests that the queried witness (e.g. the Leningrad Codex, per query_paragraph_breaks) preserves a graphic break at that point — not that the author or a final editor placed a literary boundary there, and not that פ is inherently "stronger" than ס (the petuchah/setumah distinction itself varies across manuscript witnesses). Treat the marker as one convergence signal among several (participant/speaker shift, geographic shift, temporal shift) — lead the Markers cell with the marker, then name what else converges with it.

Use data from query_paragraph_breaks. Lead with boundary status at session's STARTING verse:

1. Marker + convergence: פ at 39:1 (witness-attested); geographic return to Egypt + new participant converge — strong boundary support
2. No marker (transparent): No Masoretic marker at 43:1 (boundary based on temporal shift "when grain was gone")
3. Marker elsewhere (acknowledge): ס at 42:28 (mid-unit); session boundary at 42:38 based on geographic return

Every OT session boundary MUST have one of these three patterns. Cite at least 3 specific פ/ס markers with verse references across the session table. Be transparent: when no marker exists at a boundary, say so explicitly.

Proximity rule: Only markers AT the session's starting verse (±1 verse) count as boundary confirmation. A marker at 43:3 does NOT validate a boundary at 43:16. If no marker exists within ±1 verse of the starting verse, use pattern 2: "No Masoretic marker at X (boundary based on...)."

Verification step (OT only): Before finalizing output, re-read every Markers column entry. If ANY entry does not begin with one of: "פ at X" (where X is ±1 of starting verse), "ס at X", or "No Masoretic marker at X" — it is incomplete. Revise it. Every boundary gets a verdict: marker present (pattern 1/3), absent (pattern 2), or nearby but not at boundary (pattern 3). Silent omission = Red Flag #11 violation.

Never: List every פ/ס in the passage. Skip Masoretic check. Cite markers at session END. Use vague language ("markers around verse X", "Continues from X"). Claim "all boundaries validated" without showing each one. "Continues from X" is NOT a valid pattern — replace with "No Masoretic marker at X (boundary based on [rationale])."

---

Output Format

Output delivery: Print the ENTIRE analysis inline in your response. Do NOT save to file silently. The user must see all sections — Fit Assessment, Options, Data Sources — in the conversation.

Fit Assessment (FIRST in every output)

## Fit Assessment: ★★★★★ Excellent
[Book]'s [N] verses divide naturally into [range] sessions for [purpose].
Your requested [N] sessions [fits well / requires adjustments / exceeds limits].

Rating: ★★★★★ Excellent → ★☆☆☆☆ Not Recommended (alternatives offered).

Segmentation Options (2-4 per output)

### Option N: [Methodology Name]

**Methodology:** [Primary analytical approach]
**Best for:** [Teaching approach + audience context — 1 sentence, max 20 words]
**Rationale:** [Why this division respects the text]

| Session | Passage | Title | Verses | Markers | Synopsis |
|---------|---------|-------|--------|---------|----------|
| 1 | 1:1-11 | [Title] | 11 | [Boundary evidence] | [1-2 sentence summary] |

**Strengths:** [bulleted list]
**Limitations:** [bulleted list]

Every option MUST have: Methodology, "Best for" line (before Rationale), session table with all 6 columns, Strengths, Limitations.

Compositional Note: Check reference/compositional-debates.yaml for the book. If found, include as dedicated paragraph in Book Overview: **Compositional Note:** [text from YAML]

Reading Slices Output (slice mode only)

## Reading Slices: [Passage Reference]

**Purpose:** [Method] reading ([N]-[N] verses per slice)
**Total:** [N] slices from [total] verses
**Calculation:** [total] verses ÷ [target] per slice ≈ [N] slices

| Slice | Passage | Title | Verses | Markers | Synopsis |
|-------|---------|-------|--------|---------|----------|
| 1 | 8:1-4 | [Title] | 4 | [Boundary markers] | [Synopsis] |

**Adjustments Made:**
- [Boundary adjustments for integrity, or "None — all boundaries at natural structural points"]

**Do Not Slice Here:**
- [Verse range] — [Reason: chiasmus center / mid-dialogue / conditional-consequence]

## Data Sources
[Same format as main output — see Data Sources section below]

Required in every Reading Slices output: Header with calculation, Slice table, Adjustments Made, Do Not Slice Here, Data Sources.

Data Sources (REQUIRED — every output including refusals)

For OT:

## Data Sources
**Hebrew Text:** OpenScriptures Hebrew Bible / Westminster Leningrad Codex (pinned commit)
- Parashah divisions (פ petuchot / ס setumah) consulted for boundary validation
**Methodology:** OT Narrative: Masoretic paragraphs + scene changes + toledot

For NT:

## Data Sources
**Greek Text:** Levinsohn GNT Discourse Features (dataset 2016; book: Levinsohn 2000)
- Historical Present, Point of Departure, Left-Dislocation analyzed
- NA28/UBS5 critical text basis
- Citation: Levinsohn, Stephen H. Levinsohn Greek New Testament Discourse Features. SIL International.
**Methodology:** [Genre-specific: Epistolary markers + Levinsohn / Levinsohn + geographic markers]

When data unavailable:

## Data Sources
**Note:** Levinsohn/Masoretic data not available. Using genre-appropriate markers for boundaries.

---

Red Flags — STOP

If you think any of these, you are about to violate the skill:

#	Thought	Rule
1	"User requested N sessions for micro-book"	Rule 1: Check limits. Refuse if exceeded.
2	"User said just pick one / I trust you"	Rule 3: Present 2-4 options anyway.
3	"User is an expert, skip options"	Rule 3: Expertise doesn't bypass options.
4	"Psalms can be divided by session count"	Rule 2: Switch to curation mode.
5	"This is the standard Revelation outline"	Rule 4: Present both linear and recapitulation.
6	"Isaiah in 3 is fine" / "I'll warn then comply"	Rule 5: Refuse = no session table. Do NOT produce divisions after saying "Not Recommended."
7	"I'll validate their division to be helpful"	Rule 6: Note structural concerns. Don't rubber-stamp.
8	"Use lectionary as requested"	Rule 6: Lectionary = metadata. Present structural options.
9	"I'll skip the fit assessment"	Every output starts with Fit Assessment.
10	"Markers are obvious"	Show your work. Cite Levinsohn/Masoretic evidence.
11	"No פ/ס here, so skip it"	State "No Masoretic marker at X" — transparency required.
12	"I'll cite markers at session END"	Markers validate session STARTING verse.
13	"I know the joy count in Philippians"	Call query_vocabulary. Never cite from training knowledge.
14	"Web search failed, cite Fee anyway"	No web search = no thematic option.
15	"Verse range is just small segmentation"	Verse range = slice mode. Different output.
16	"3 slices for 67 verses is fine"	Calculate: 67 ÷ 8 ≈ 8 slices. Push back.
17	"Psalm 23 can be 3 slices"	6 verses ÷ 3 = 2 per slice. Below minimum. Refuse.
18	"I'll slice mechanically by verse count"	Check dialogue, chiasmus, conditionals first.
19	"Micro-book/Psalms don't need MCP"	Every path goes through data-retriever. No exceptions.
20	"Data-retriever failed, use training knowledge"	Fall back to direct MCP calls. Never substitute training.
21	"I'll figure out structure myself"	Spawn argument-flow for structural analysis.
22	"The marker confirms the author's boundary"	A marker is witness-attested graphic evidence, not authorial confirmation — name the witness, cite what else converges.

---

Reference Files

• reference/book-exceptions.yaml — Micro-books, anthologies, contested books
• reference/book-genres.yaml — Genre mapping for all 66 books
• reference/genre-methodology.yaml — Markers and methodology per genre
• reference/compositional-debates.yaml — Partition theory notes (2 Cor, Philippians)
• MCP tool query_discourse_features — Levinsohn discourse features (NT)
• MCP tool query_paragraph_breaks — Masoretic paragraph markers (OT)
• MCP tool query_vocabulary — Vocabulary frequencies and clustering