---
name: extract-document-insights
description: Extract insights from external documents (research papers, books, articles). Spawns document-insight-extractor subagent. Requires session name.
allowed-tools: [Task]
user-invocable: true
arg-description: "<session name> <file path or content description>"
---

# Extract Document Insights

Extract insights from EXTERNAL documents with proper epistemic classification.

## Purpose

User-invocable wrapper that spawns the `document-insight-extractor` subagent to:
- Extract research findings, theoretical frameworks, hypotheses
- Classify epistemic status (confirmed, theoretical, speculative)
- Store in session-based folders
- Deduplicate against existing knowledge base
- Save to `Brain/Document Insights/[session]/`

## When to Use

- Analyzing research papers, academic articles
- Processing books or book chapters
- Extracting insights from web articles, reports
- Any EXTERNAL content (not your personal thoughts)

**NOT for personal content** - use `/extract-insights` for your conversations, transcripts.

## Usage

```
/extract-document-insights "2025-02-21 Ancient Wisdom Research" /path/to/document.md
/extract-document-insights "AI Agent Papers" "the transcript above"
```

**Session name is REQUIRED** - describes the research session for organization.

## Process

1. **Parse arguments** to extract session name and source
2. **Spawn document-insight-extractor subagent** via Task tool with:
   ```
   Task(
     subagent_type="document-insight-extractor",
     prompt="Extract insights from: [source] into session '[session-name]'. Follow your mandatory workflow - contextualize, classify epistemically, search duplicates, create notes, update changelog."
   )
   ```
3. **Report results** - number of insights extracted, session folder path
4. **Suggest insight interview** - Present to user:

   > "[N] insights from [source] saved to `Brain/Document Insights/[session]/`.
   >
   > Before these get indexed, consider running `/insight-interview [topic]` to capture your own angles - where you agree, disagree, or see connections the research missed. Your responses save to `Brain/AI Extracted Notes/` and both sets will be available for the next connection discovery run.
   >
   > Run `/insight-interview [topic]` to continue, or skip if you want to index these as-is."

## Outputs

- Insight notes in `Brain/Document Insights/[session]/`
- Session changelog in same folder
- Summary with epistemic breakdown (confirmed vs hypothetical)
- Suggested next step: `/insight-interview [topic]` to layer in your personal perspective