read-text

name	read-text
description	Use when deeply comprehending a complex text — paper, specification, book chapter, codebase, legal document, or long documentation. Triggers on requests like "read this carefully", "analyze this paper", "understand this spec", "what does this document really say", or any task requiring thorough multi-pass reading rather than skimming or summarization.

Deep Reading

Overview

Multi-pass reading methodology that builds genuine comprehension — not just extraction — from complex texts. Each pass has a distinct purpose: survey structure, extract propositions, integrate into a situation model, then evaluate critically.

Core principle: Comprehension is not summarization. A summary captures what the text says (textbase). Comprehension captures what the text means, what it implies, what it assumes, and what it omits (situation model). Every phase targets the situation model.

When to Use

• Thoroughly understanding a paper, spec, RFC, book chapter, or complex document
• Reading to implement (extracting requirements, edge cases, ambiguities)
• Critical analysis of arguments, evidence, or technical claims
• Understanding a codebase or module in depth
• Comparing multiple documents on the same topic
• When NOT to use: quick fact lookup, skimming for a specific answer, reading short/simple content

Reading Modes

Declare the mode before starting. Each mode adjusts phase emphasis and artifacts.

Mode	When	Emphasis	Primary Artifacts
Learn	papers, docs, books	Phases 2, 3	concept map, explanation, questions
Critique	evaluating arguments/claims	Phase 4	critical assessment, assumption inventory
Implement	specs, APIs, RFCs	Phase 2	requirements checklist, glossary, edge cases
Audit	finding bugs, contradictions	Phases 2, 4	inconsistency list, assumption inventory
Compare	multiple related documents	Phase 3	comparison matrix, terminology mapping
Triage	deciding what to read closely	Phase 1	structural map, read/skip recommendation

If the user doesn't specify a mode, infer from context. If ambiguous, ask.

Process

Phase 0: Preparation ──→ Phase 1: Survey ──→ Phase 2: Extraction ──→ Phase 3: Integration
                                                                           │
                                                           ┌───────────────┘
                                                           ▼
                                                   Phase 4: Evaluation ──→ Phase 5: Assembly

For Triage mode, stop after Phase 1. For all other modes, complete all phases, with emphasis varying by mode.

Phase 0: Preparation

Before reading a single line:

1. Declare reading purpose. What mode? What question drives this reading? What will the output be used for?

2. Activate prior knowledge. Query statement-mcp for related indexed knowledge. Check if related documents exist in the project. Recall any domain context from the conversation. This is not optional — reading without schema activation produces weaker comprehension.

3. Classify the text. What type (paper, spec, code, legal, narrative, expository)? What domain? Estimated length? This determines which Phase 2-4 techniques apply.

4. Set up output. If the text is substantial, create an output file for comprehension artifacts. For shorter texts, inline artifacts in the conversation are fine.

Phase 1: Structural Survey

Purpose: Build a map of the text before reading it. Know where to invest attention.

Read only: title, headings, table of contents, abstract/introduction, conclusion, section headers, figures/tables list, any definitions section.

Produce a structural map:

• Classification: text type, domain, audience, scope
• Statement of the whole: one sentence capturing what this document is about
• Section inventory: each major section with heading, estimated scope, and importance rating (High/Medium/Low) for the declared reading purpose
• Glossary seed: any defined terms found during survey
• Survey questions: 3-5 questions this document should answer, given the reading purpose

For code: Scan directory structure, module organization, entry points, public API surface, README, and test structure. The structural map becomes a module dependency overview.

For Compare mode: Run Phase 1 on all documents before proceeding.

Phase 2: Focused Extraction

Purpose: Extract what the text claims, how it supports those claims, and what terms it uses — section by section.

Process sections in priority order from Phase 1 importance ratings, not necessarily linearly. For each section:

1. Key propositions: What does this section claim or assert?
2. Evidence/support: What backs each claim? (data, citations, examples, authority, logic)
3. Key terms: How does the author define or use important terms? Note any terms used differently than standard usage.
4. Cross-references: Internal references to other sections; external references to other works.
5. Section questions: What's unclear? What needs more context?
6. Macro-operations:
   • Delete: What detail is non-essential for the reading purpose?
   • Generalize: What clusters of specifics can be captured by a single statement?
   • Construct: What does this section imply but not state?

Write extraction notes to the output file as you go. Do not try to hold all extractions in context.

Mode-specific adaptations:

• Implement: Track MUST/SHOULD/MAY requirements (RFC 2119 style). Note every constraint, boundary condition, and error case. Flag ambiguous requirements.
• Audit: Read adversarially. Assume errors exist. Look for contradictions between sections, ambiguous requirements, and implicit assumptions that could fail.
• Compare: After extracting from each document, use Adler's "bring authors to terms" — build a shared vocabulary mapping where different documents use different words for the same concept, or the same word for different concepts.

Phase 3: Integration

Purpose: Build a situation model — a unified representation of what the text means, not just what it says. This is where comprehension happens.

1. Synthesize extractions. Read all Phase 2 notes. Connect propositions across sections into a coherent whole.

2. Build entity-relation map. Key concepts and how they relate. For complex texts, write this as a structured list:

   [Concept A] --{relationship}--> [Concept B]
   

3. Trace argument/logic structure (varies by text type):

   • Argumentative: Toulmin decomposition — claims, grounds, warrants, qualifiers, rebuttals. Flag unstated warrants.
   • Narrative/process: Event chain with causal links.
   • Specification: Requirement dependency graph — which requirements depend on others.
   • Code: Call graph, data flow, and state transitions for the relevant paths.

4. Identify unstated assumptions. Check five categories:

   • Ontological: What entities/categories does the author take for granted?
   • Epistemic: What does the author assume the reader knows?
   • Normative: What values or priorities are assumed?
   • Definitional: What terms are used without definition?
   • Causal: What cause-effect relationships are assumed without evidence?

5. Feynman check. Generate a plain-language explanation of the document's core content as if explaining to someone unfamiliar with the domain. Where the explanation breaks down or becomes hand-wavy — those are comprehension gaps. Re-read those sections.

Output: Integrated comprehension artifact — concept map, argument graph, or system model depending on text type.

Phase 4: Evaluation

Rule: Do not criticize until you can say "I understand." Phases 1-3 must be complete before Phase 4.

1. Evidence quality: For each major claim, assess — What type of evidence? How strong? Sufficient for the claim's scope? Current?

2. Logical structure: Check for fallacies, non sequiturs, equivocation, circular reasoning, false dichotomies. Check whether conclusions follow from premises.

3. Negative space: What is not said? What topics are conspicuously absent? What counterarguments are not addressed? What alternative explanations are not considered? Omissions are often more revealing than content.

4. Scope alignment: Does the scope of evidence match the scope of claims? Watch for: local evidence supporting global claims, lab results presented as field-applicable, and correlation framed as causation.

5. Comparison with known material: Does this contradict or confirm other sources? Where does it diverge from established understanding?

Output: Critical assessment with strengths, weaknesses, and open questions.

For Critique mode, this phase is expanded — produce a formal assumption inventory and evidence evaluation for every major claim.

Phase 5: Artifact Assembly

Consolidate all intermediate outputs into final comprehension artifacts, tailored to the reading mode:

Standard Artifacts (all modes)

• Structural map (from Phase 1)
• Concept extraction — glossary, entity-relation map, requirements list if applicable
• Questions — factual (verification), inferential (what follows), critical (what's assumed), connective (how this relates to other knowledge), unresolved (what's left open)

Mode-Specific Artifacts

• Learn: Plain-language explanation (Feynman output), concept map, study questions
• Critique: Assumption inventory, evidence evaluation table, logical gap analysis
• Implement: Requirements checklist with section refs, edge case inventory, ambiguity list, glossary
• Audit: Defect/inconsistency list with severity and location, assumption inventory
• Compare: Comparison matrix, terminology mapping, real vs. apparent disagreements

Indexing

If statement-mcp is available, index key findings:

• Core propositions and their evidence
• Assumptions identified
• Open questions
• Connections to existing indexed knowledge

Context Window Management

For documents that exceed what can be held in a single context:

1. Phase 1 always fits — it reads only structure, not content.
2. Phase 2 processes section by section, writing to file between sections. Only one section needs to be in context at a time.
3. Phase 3 reads the Phase 2 output file, not the original document. The extraction notes are much shorter than the source.
4. Phase 4 reads the Phase 3 output plus targeted re-reads of specific sections.

If using sub-agents for parallel extraction of different sections, each agent reads the Phase 1 structural map first, then its assigned sections.

Common Mistakes

Mistake	Fix
Summarizing instead of comprehending	Check: does the output capture implications and assumptions, or just content?
Single-pass reading	Multi-pass is structurally required. Each pass has a distinct purpose.
Skipping schema activation	Phase 0 is not optional. Prior knowledge retrieval changes what you notice.
Treating all sections equally	Phase 1 creates an attention budget. Use it.
Reading linearly when priority order helps	Process sections by importance for the reading purpose, not document order.
Accepting claims uncritically	Phase 4 exists. Understanding precedes evaluation, but evaluation must happen.
Ignoring what is not said	Omissions and negative space are often more important than explicit content.
Generating questions without answering	Every question: answered, flagged as unanswerable from text, or marked for external lookup.
Stopping at extraction	Extraction (Phase 2) is not comprehension. Integration (Phase 3) is where meaning forms.
Conflating plausible CoT with understanding	Verify every reasoning chain against what the text actually says.