/bookstrap-plan-research - Identify Knowledge Gaps

Analyze the Book Requirements Document (BRD) against the existing research corpus to identify knowledge gaps and generate prioritized research tasks.

Purpose

Compare what the book requires (from BRD) with what knowledge currently exists in the database (from prior ingestion). Generate a prioritized list of research tasks that will fill the identified gaps before writing begins.

This command delegates the analysis work to the

corpus-analyst

Input Arguments

None. This command reads from the database:

• BRD content and requirements
• Existing sources and their coverage
• Entities already extracted
• Current knowledge gaps

Processing Workflow

1. Load BRD Requirements

Query the database to retrieve the Book Requirements Document:

# Query BRD from database
surreal sql --conn http://localhost:2665 \
  --user root --pass root \
  --ns bookstrap --db <database-name> \
  --query "SELECT * FROM brd ORDER BY version DESC LIMIT 1;"

Extract key requirements:

• Planned chapters and sections
• Key concepts, characters, locations, events
• Research areas specified in BRD
• Genre-specific knowledge needs
• Target audience and depth requirements

2. Query Existing Corpus Coverage

Analyze what knowledge already exists in the database:

-- Coverage by chapter/topic
SELECT chapter, count() as sources
FROM section->cites->source
GROUP BY chapter;

-- Entity coverage
SELECT name, count() as mentions
FROM concept<-related_to<-source
GROUP BY name;

-- Existing knowledge gaps (unresolved)
SELECT * FROM knowledge_gap
WHERE resolved = false
ORDER BY created_at;

-- Source distribution by type
SELECT source_type, count() as total
FROM source
GROUP BY source_type;

-- Timeline coverage
SELECT sequence, count() as events
FROM event
GROUP BY sequence;

3. Compare BRD Against Corpus

For each chapter/topic/concept in the BRD:

• Check if sufficient sources exist in the database
• Identify entities mentioned in BRD but missing from corpus
• Find topics with low source coverage
• Detect chronological gaps in timeline
• Flag concepts lacking supporting evidence

4. Generate Prioritized Research Tasks

Create research tasks with priorities based on:

High Priority:

• Core plot/argument elements with no sources
• Main characters/concepts missing from corpus
• Critical events lacking documentation
• Topics that block multiple writing tasks

Medium Priority:

• Supporting details with thin coverage
• Secondary characters/locations needing depth
• Background context for credibility
• Genre-specific atmosphere/accuracy needs

Low Priority:

• Optional enrichment details
• Tangential background information
• Nice-to-have but not essential

5. Store Tasks in Database

For each research task, create a database record:

CREATE knowledge_gap SET
  question = $research_question,
  context = $why_needed,
  priority = $priority_level,
  chapter_blocking = $chapters_affected,
  resolved = false,
  created_at = time::now()
;

6. Delegate to Corpus Analyst

Invoke the

corpus-analyst

# Load corpus-analyst agent with context
# Agent will:
# 1. Read BRD from database
# 2. Execute coverage queries
# 3. Perform gap analysis
# 4. Generate prioritized research tasks
# 5. Store tasks in database
# 6. Generate report

The corpus-analyst agent has read-only database access and uses the

corpus-analysis

surrealdb

Output Format

Report generated research tasks to the user:

KNOWLEDGE GAP ANALYSIS
======================

BRD: <Book Title>
Corpus: <N> sources, <M> entities

COVERAGE ANALYSIS
-----------------
High Coverage:
  ✓ Chapter 1: Introduction (8 sources, 15 entities)
  ✓ Concept: SOE Training (12 sources)

Medium Coverage:
  ~ Chapter 3: Lyon Operation (3 sources, 8 entities)
  ~ Location: Lyon Safehouse (2 sources)

Low/No Coverage:
  ✗ Chapter 5: Wireless Protocols (0 sources)
  ✗ Event: Gestapo Raid 1943 (0 sources)
  ✗ Character: Marie Dubois (mentioned in BRD, not in corpus)

RESEARCH TASKS GENERATED: 12
=============================

HIGH PRIORITY (4 tasks)
-----------------------
1. SOE wireless operator training protocols 1942-1943
   Why: Core to protagonist's role, zero sources
   Blocks: Chapters 2, 4, 6

2. Lyon Resistance network structure and key figures
   Why: Primary setting, only 2 tangential sources
   Blocks: Chapters 3, 5, 7

3. Gestapo counter-intelligence methods in Lyon 1943
   Why: Antagonist strategy, no documentation
   Blocks: Chapters 5, 8

4. Daily life details in occupied Lyon (food, curfews, rationing)
   Why: Atmosphere and authenticity, minimal coverage
   Blocks: Chapters 3, 4, 5, 7

MEDIUM PRIORITY (5 tasks)
-------------------------
5. SOE Beaulieu training facility layout and procedures
6. Wireless set types used by F Section agents
7. Lyon geography and landmarks 1943
8. French Resistance communication codes
9. Black market operations in wartime Lyon

LOW PRIORITY (3 tasks)
----------------------
10. Fashion and clothing styles 1943 France
11. Popular culture and entertainment during occupation
12. Weather patterns in Lyon region

NEXT STEPS
----------
Run /bookstrap-research to execute these tasks autonomously.
Use /bookstrap-status to monitor progress.

Statistics to Track

Calculate and report:

• Total chapters planned vs. covered
• Entities in BRD vs. entities in corpus
• Source count per major topic
• Percentage of BRD requirements met
• Number of high/medium/low priority gaps
• Estimated research tasks needed

Implementation Notes

Agent Delegation

This command is a thin wrapper that:

1. Verifies database connection
2. Checks that BRD exists
3. Invokes the

   corpus-analyst

   agent
4. Displays the agent's output

The actual analysis logic lives in the

corpus-analyst

Gap Detection Strategies

The corpus-analyst uses multiple approaches:

• Keyword matching: BRD entities vs. database entities
• Semantic search: BRD concepts vs. source embeddings
• Graph analysis: Required relationships missing from graph
• Timeline gaps: Chronological holes in event sequence
• Citation density: Sections with claims but no sources

Idempotency

Re-running

/bookstrap-plan-research

• Update existing gaps if BRD changed
• Add new gaps if corpus changed
• Not duplicate existing unresolved gaps
• Re-prioritize based on current state

Configuration

Gap detection thresholds can be configured in

bookstrap.config.json

{
  "gap_detection": {
    "min_sources_per_chapter": 5,
    "min_sources_per_concept": 2,
    "high_priority_threshold": 0,
    "medium_priority_threshold": 2
  }
}

Error Handling

/bookstrap-init

Pre-requisites

Before running

/bookstrap-plan-research

1. BRD created:

   /bookstrap-init

   must have been run
2. SurrealDB running: Database must be accessible
3. Schema initialized: Database schema loaded
4. Initial corpus ingested (optional):

   /bookstrap-ingest

   provides baseline, but can run on empty corpus

Related Commands

• /bookstrap-init

  - Create BRD

• /bookstrap-ingest

  - Load initial corpus

• /bookstrap-research

  - Execute research tasks generated by this command

• /bookstrap-status

  - View gap resolution progress

• /bookstrap-plan-write

  - Generate writing tasks after gaps filled

Supporting Agents

corpus-analyst

Supporting Skills

corpus-analysis/

surrealdb/

Example Usage

# After initial ingestion, identify what's missing
/bookstrap-plan-research

# Re-run after additional ingestion to update gap list
/bookstrap-ingest ./more-sources/
/bookstrap-plan-research

# Check gaps before starting to write
/bookstrap-plan-research
/bookstrap-status

Integration with Research Loop

This command is part of the research cycle:

init → ingest → plan-research → research
                     ↑              │
                     └──────────────┘
                    (iterate until
                     gaps resolved)

Once gaps are identified,

/bookstrap-research