Document Sharding Guide

Use the bmad-shard-doc tool if you need to split large markdown files into smaller, organized files for better context management.

When to Use This

Only use this if you notice your chosen tool / model combination is failing to load and read all the documents as input when needed.

What is Document Sharding?

Document sharding splits large markdown files into smaller, organized files based on level 2 headings (## Heading).

Architecture

Before Sharding:
_bmad-output/planning-artifacts/
└── PRD.md (large 50k token file)

After Sharding:
_bmad-output/planning-artifacts/
└── prd/
    ├── index.md                    # Table of contents with descriptions
    ├── overview.md                 # Section 1
    ├── user-requirements.md        # Section 2
    ├── technical-requirements.md   # Section 3
    └── ...                         # Additional sections

Steps

1. Run the Shard-Doc Tool

/bmad-shard-doc

2. Follow the Interactive Process

Agent: Which document would you like to shard?
User: docs/PRD.md

Agent: Default destination: docs/prd/
       Accept default? [y/n]
User: y

Agent: Sharding PRD.md...
       ✓ Created 12 section files
       ✓ Generated index.md
       ✓ Complete!

How Workflow Discovery Works

BMad workflows use a dual discovery system:

Try whole document first - Look for document-name.md
Check for sharded version - Look for document-name/index.md
Priority rule - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead

Workflow Support

All BMM workflows support both formats:

Whole documents
Sharded documents
Automatic detection
Transparent to user