bookstrap-status

name	bookstrap-status
description	Display comprehensive project progress including BRD status, corpus statistics, research progress, and writing progress with recommendations for next actions
disable-model-invocation	true
allowed-tools	Bash, Read

/bookstrap-status - Display Progress Dashboard

Display comprehensive project status without making any changes. This is a read-only command that queries the database for all project metrics and recommends the next action based on current state.

Purpose

Provide a clear, actionable overview of the entire book project's status. Show what's complete, what's in progress, what's blocking progress, and what should be done next. This command helps users understand the project state at a glance and guides them toward the next logical step.

Input Arguments

None. This command reads all status information from the database and project files.

Output Format

Display a comprehensive status dashboard with the following sections:

1. Project Overview

BOOKSTRAP STATUS
================

Project: <book-title-from-BRD>
Database: <status> (SurrealDB <version>)
BRD: <status> (v<version>)
Config: <config-file-path>

Status indicators:

• BRD: ✓ Complete (v2) or ✗ Missing or ⚠ Outdated
• Database: Running (SurrealDB 2.0) or ✗ Not running or ⚠ Connection issues

2. Corpus Statistics

CORPUS
------
Sources: <N> ingested
  - Primary: <N>
  - Secondary: <N>
  - Web: <N>
Entities: <N> extracted
  - Characters: <N>
  - Locations: <N>
  - Events: <N>
  - Concepts: <N>

Query database for source and entity counts:

-- Count sources by type
SELECT count() AS total,
       source_type,
       reliability
FROM source
GROUP BY source_type, reliability;

-- Count entities by type
SELECT
  (SELECT count() FROM character) AS characters,
  (SELECT count() FROM location) AS locations,
  (SELECT count() FROM event) AS events,
  (SELECT count() FROM concept) AS concepts;

3. Research Progress

RESEARCH
--------
Tasks: <N>/<total> complete
Gaps: <N> open, <N> resolved
Sources needed: <N> high priority

Query for research status:

-- Knowledge gaps status
SELECT
  count() AS total,
  count(resolved = true) AS resolved,
  count(resolved = false) AS open
FROM knowledge_gap;

-- High priority gaps
SELECT count()
FROM knowledge_gap
WHERE resolved = false
  AND priority = 'high';

4. Writing Progress

WRITING
-------
Tasks: <N>/<total> complete
Chapters: <N>/<total> drafted
  - Complete: <N>
  - In progress: <N>
  - Not started: <N>
Word count: <N> / <target> target (<N>%)

Query for writing status:

-- Chapter status
SELECT
  count() AS total,
  count(status = 'complete') AS complete,
  count(status = 'draft') AS in_progress,
  count(status = 'planned') AS not_started
FROM chapter;

-- Total word count
SELECT sum(word_count) AS total_words
FROM chapter
WHERE status IN ['draft', 'complete'];

-- Target word count from BRD
SELECT target_word_count FROM brd ORDER BY version DESC LIMIT 1;

5. Next Action Recommendation

NEXT ACTION
-----------
Recommended: /bookstrap-<command> (<reason>)

Recommendation logic based on current state:

Condition	Recommendation
No BRD exists	/bookstrap-init (Create Book Requirements Document)
BRD exists, no sources	/bookstrap-ingest (Load initial research corpus)
Sources exist, no research tasks	/bookstrap-plan-research (Identify knowledge gaps)
Unresolved gaps exist	/bookstrap-research ( gaps blocking writing)
Gaps resolved, no writing tasks	/bookstrap-plan-write (Generate writing tasks from corpus)
Writing tasks exist, gaps block them	/bookstrap-research ( gaps blocking tasks)
Writing tasks ready	/bookstrap-write ( tasks ready to write)
Writing complete, not edited	/bookstrap-edit (Run consistency and voice checks)
All complete	All tasks complete! Run /bookstrap-query or /bookstrap-edit for refinements

Implementation Workflow

1. Check Database Connection

# Verify SurrealDB is running
curl -s http://localhost:2665/health || echo "Database not running"

# If running, get version
surreal version 2>/dev/null || echo "Unknown"

2. Check BRD Status

# Check if BRD.md exists
if [ -f "BRD.md" ]; then
  # Get version from BRD if tracked in database
  # Otherwise mark as "✓ Complete"
else
  echo "✗ Missing"
fi

3. Query Corpus Statistics

Execute SurrealDB queries to gather:

• Source counts by type and reliability
• Entity counts by category
• Total embeddings generated
• Relationship edge counts

surreal sql --conn http://localhost:2665 \
  --user root --pass root \
  --ns bookstrap --db <database-name> \
  --query "<query-from-above>"

4. Query Research Progress

Execute queries for:

• Total knowledge gaps (open vs. resolved)
• Research tasks completion
• High priority gaps
• Gaps blocking writing tasks

5. Query Writing Progress

Execute queries for:

• Chapter status distribution
• Section completion counts
• Total word count vs. target
• Tasks complete vs. pending

6. Calculate Recommendation

Use the decision logic above to determine the next command to run based on:

• What exists (BRD, sources, tasks)
• What's blocking progress (gaps, dependencies)
• What's ready to execute (unblocked tasks)

7. Format and Display

Present all information in the formatted output shown above.

Additional Statistics (Optional Verbose Mode)

If user requests detailed stats with /bookstrap-status --verbose:

DETAILED STATISTICS
===================

CORPUS BREAKDOWN
----------------
Total storage: <MB> in database
Average chunk size: <N> tokens
Average entities per source: <N>
Embedding coverage: <N>% of content

RESEARCH DETAILS
----------------
Average sources per gap: <N>
Source reliability distribution:
  - High: <N> (<N>%)
  - Medium: <N> (<N>%)
  - Low: <N> (<N>%)

Top unresolved gaps:
  1. <gap-question> (blocks <N> tasks)
  2. <gap-question> (blocks <N> tasks)
  3. <gap-question> (blocks <N> tasks)

WRITING DETAILS
---------------
Average section length: <N> words
Citations per section: <N> average
Longest chapter: <chapter-title> (<N> words)
Shortest chapter: <chapter-title> (<N> words)

Blocked tasks:
  - Task: <task-subject> (blocked by: <gap-question>)
  - Task: <task-subject> (blocked by: <dependency-task>)

TIMELINE
--------
Project started: <date>
Days elapsed: <N>
Last activity: <date> (<command>)
Estimated completion: <date> (based on current pace)

Error Handling

Error	Display
Database not running	Database: ✗ Not running (run: docker-compose up -d)
Database connection error	Database: ⚠ Connection issues (check config)
BRD missing	BRD: ✗ Missing (run: /bookstrap-init)
Query timeout	⚠ Database query timeout, showing partial results
Empty database	Show zeros for all stats, recommend /bookstrap-ingest

Configuration

Read database connection settings from bookstrap.config.json:

{
  "surrealdb": {
    "host": "localhost",
    "port": 2665,
    "namespace": "bookstrap",
    "database": "my_book",
    "username": "root",
    "password_env": "SURREAL_PASSWORD"
  }
}

Example Output

BOOKSTRAP STATUS
================

Project: The Silent Cipher (Historical Thriller)
Database: Running (SurrealDB 2.0)
BRD: ✓ Complete (v2)
Config: ./bookstrap.config.json

CORPUS
------
Sources: 47 ingested
  - Primary: 12
  - Secondary: 28
  - Web: 7
Entities: 156 extracted
  - Characters: 23
  - Locations: 45
  - Events: 88
  - Concepts: 38

RESEARCH
--------
Tasks: 3/15 complete
Gaps: 12 open, 8 resolved
Sources needed: 5 high priority

WRITING
-------
Tasks: 7/32 complete
Chapters: 2/10 drafted
  - Complete: 1
  - In progress: 1
  - Not started: 8
Word count: 12,450 / 80,000 target (16%)

NEXT ACTION
-----------
Recommended: /bookstrap-research (12 gaps blocking writing)

Pre-requisites

None. This command can be run at any time to check project status. It gracefully handles missing components and reports their status.

Related Commands

• /bookstrap-init - Create BRD (if missing)
• /bookstrap-ingest - Load initial corpus (if needed)
• /bookstrap-plan-research - Generate research tasks
• /bookstrap-research - Execute research to fill gaps
• /bookstrap-plan-write - Generate writing tasks
• /bookstrap-write - Execute writing tasks
• /bookstrap-edit - Run editing passes
• /bookstrap-query - Query database for specific information

Supporting Queries

BRD Status Query

-- Get latest BRD version
SELECT content, version, created_at
FROM brd
ORDER BY version DESC
LIMIT 1;

Comprehensive Corpus Query

-- Get all corpus statistics in one query
SELECT
  (SELECT count() FROM source) AS total_sources,
  (SELECT count() FROM source WHERE source_type = 'primary') AS primary_sources,
  (SELECT count() FROM source WHERE source_type = 'secondary') AS secondary_sources,
  (SELECT count() FROM source WHERE source_type = 'web') AS web_sources,
  (SELECT count() FROM character) AS characters,
  (SELECT count() FROM location) AS locations,
  (SELECT count() FROM event) AS events,
  (SELECT count() FROM concept) AS concepts,
  (SELECT count() FROM knowledge_gap WHERE resolved = false) AS open_gaps,
  (SELECT count() FROM knowledge_gap WHERE resolved = true) AS resolved_gaps,
  (SELECT count() FROM chapter) AS total_chapters,
  (SELECT count() FROM chapter WHERE status = 'complete') AS complete_chapters,
  (SELECT count() FROM chapter WHERE status = 'draft') AS draft_chapters,
  (SELECT sum(word_count) FROM chapter WHERE status IN ['draft', 'complete']) AS total_words;

Blocking Analysis Query

-- Find what's blocking progress
SELECT
  question,
  context,
  created_at,
  (SELECT count() FROM task WHERE blocked_by CONTAINS $parent.id) AS blocking_task_count
FROM knowledge_gap
WHERE resolved = false
ORDER BY blocking_task_count DESC
LIMIT 10;

Implementation Notes

Read-Only Guarantee

This command:

• ✓ Reads from database and files
• ✓ Displays statistics and recommendations
• ✗ Does NOT modify any data
• ✗ Does NOT create or update records
• ✗ Does NOT trigger any workflows

Performance

For large projects:

• Cache query results for 5 minutes
• Use COUNT queries instead of fetching full records
• Execute queries in parallel where possible
• Timeout long queries and show partial results

Refresh

Status can be refreshed by simply re-running /bookstrap-status. The command always shows current state from the database.

Troubleshooting

Database not accessible

Database: ✗ Not running

Start database:
  docker-compose up -d
  OR
  ./scripts/start-surreal.sh

No data in database

CORPUS
------
Sources: 0 ingested
Entities: 0 extracted

NEXT ACTION
-----------
Recommended: /bookstrap-ingest (Load initial research corpus)

Stale recommendations

If recommendation doesn't match your intent:

• Run the recommended command to update state
• Or run a different command if you know what's needed
• Recommendations are guidance, not requirements

Advanced Features

Progress Tracking

Track velocity and estimate completion:

-- Calculate average tasks per day
SELECT
  count() AS total_tasks,
  count(status = 'completed') AS completed_tasks,
  time::diff(min(created_at), max(updated_at)) AS time_elapsed
FROM task;

Use this to estimate remaining time based on historical completion rate.

Visualization Export

For future enhancement, export data for visualization:

/bookstrap-status --export json > status.json
/bookstrap-status --export csv > status.csv

Continuous Monitoring

For long-running sessions, watch status updates:

watch -n 60 '/bookstrap-status'

Example Use Cases

Starting a new project

/bookstrap-status
# Output: "Recommended: /bookstrap-init"
/bookstrap-init

Mid-project check

/bookstrap-status
# See what's done, what's next
# Run recommended command

Debugging stalls

/bookstrap-status --verbose
# See what's blocking progress
# Identify gaps or dependencies

Final review

/bookstrap-status
# Verify all chapters complete
# Check word count against target
# Run final edit pass