Break large documents into smaller, manageable shards with maintained relationships and navigation, improving document usability and maintenance for PRDs, specs, and technical documentation. Use when large documents (>5000 words) need splitting for better maintainability, navigation, or when documentation becomes difficult to navigate.
Break large documents into smaller, manageable shards with maintained relationships and navigation, improving document usability and maintenance for PRDs, specs, and technical documentation. Use when large documents (>5000 words) need splitting for better maintainability, navigation, or when documentation becomes difficult to navigate.
acceptance
[{"shards_created":"Document split into logical, focused shards"},{"navigation_provided":"Index/navigation document created for shard discovery"},{"relationships_maintained":"Cross-references and dependencies preserved"},{"metadata_complete":"Each shard includes metadata (title, purpose, dependencies)"},{"validation_passed":"All internal links verified, no broken references"}]
inputs
{"source_document":{"type":"string","required":true,"description":"Path to document to be sharded (absolute path)"},"sharding_strategy":{"type":"string","required":false,"description":"logical | size-based | semantic | custom (default: logical)","default":"logical"},"max_shard_size":{"type":"number","required":false,"description":"Maximum lines per shard (for size-based strategy, default: 500)","default":500},"output_directory":{"type":"string","required":false,"description":"Directory for shard output (default: <source>-shards/)"},"preserve_original":{"type":"boolean","required":false,"description":"Keep original document alongside shards (default: true)","default":true}}
outputs
{"sharding_complete":{"type":"boolean","description":"Whether sharding completed successfully"},"shard_count":{"type":"number","description":"Number of shards created"},"output_location":{"type":"string","description":"Directory path containing shards and index"},"index_file":{"type":"string","description":"Path to navigation index file"},"broken_references":{"type":"array","description":"List of broken cross-references found during validation"}}
Break large, monolithic documents into smaller, manageable shards that are easier to navigate, maintain, and understand. Particularly valuable for lengthy PRDs, technical specifications, architecture docs, and API documentation.
Core Principles:
Logical boundaries (shard by topic/section, not arbitrary size)
Action: Parse document to understand structure, identify logical boundaries, and assess sharding approach.
Key Activities:
Parse Document Hierarchy
Example document structure:
# Product Requirements Document## 1. Executive Summary (200 lines)## 2. Vision & Objectives (150 lines)## 3. User Personas (400 lines)### 3.1 Persona: Sarah (SaaS Admin)### 3.2 Persona: Mike (End User)### 3.3 Persona: Lisa (Manager)## 4. Market Analysis (600 lines)### 4.1 Competitive Landscape### 4.2 Market Segmentation### 4.3 Differentiation Strategy## 5. Feature Specifications (1200 lines) ⚠️ Large### 5.1 Feature: Authentication### 5.2 Feature: Dashboard### 5.3 Feature: Reporting### ... (20 more features)## 6. Technical Requirements (800 lines)## 7. Success Metrics (300 lines)
Total: ~3,650 lines (too large for single document)
Identify Shard Boundaries
Logical Strategy (Recommended):
Shard by major sections (Executive Summary, Personas, Market Analysis, etc.)
Break large sections into sub-shards (e.g., Features → one shard per feature)
Keep related content together (don't split mid-topic)
Size-Based Strategy:
Split when section exceeds max_shard_size (default 500 lines)
Find nearest heading boundary
Create shard at logical break point
Semantic Strategy:
Analyze content similarity
Group related topics even if in different sections
Advanced: requires NLP analysis
Assess Cross-References
Scan for internal links:
- [See Market Analysis](#market-analysis)
- [Feature dependencies in Technical Requirements](#technical-requirements)
- [Success metrics for Dashboard feature](#feature-dashboard)
Catalog all cross-references for later validation
Original document:
See [Market Analysis](#market-analysis) for details.
Sharded version (from feature-authentication.md):
See [Market Analysis](market-analysis.md) for details.
Update format:
#section-name → filename.md#parent-section-name → filename.md#section-name
---
## Search by Tag
**#core-feature:** Authentication, Dashboard, Reporting
**#security:** Authentication, Data Encryption, Access Control
**#analytics:** Dashboard, Reporting, Success Metrics
**#user-facing:** All features under features/
---
## Original Document
The original, unshard document is preserved at:
[`product-requirements-document.md`](../product-requirements-document.md)
Create Directory README Files
For subdirectories (like features/), create README.md:
# Features Directory
This directory contains detailed specifications for all 20 product features.
## Core Features (Must Have)1. [Authentication](authentication.md) - User login and security
2. [Dashboard](dashboard.md) - Main user interface
3. [Reporting](reporting.md) - Analytics and reports
## Secondary Features (Should Have)4. [Notifications](notifications.md) - Email and in-app alerts
5. [User Profile](user-profile.md) - Profile management
...
## Legacy Features (Won't Have v1)18. [Old Admin Panel](old-admin-panel.md) - Deprecated interface
[◄ Back to PRD Index](../index.md)
Output: Comprehensive index with multiple navigation paths
See:references/navigation-patterns.md for index design patterns
Step 4: Validate Relationships
Action: Verify all cross-references, dependencies, and links work correctly.
Key Activities:
Validate Internal Links
# Scan all shards for markdown linksfor file in *.md; do
grep -o '\[.*\](.*\.md[^)]*)'"$file"done# Check each link target exists# Report broken links
Verify Dependencies
For each shard with dependencies:
- Check dependency shards exist
- Verify dependency sections referenced exist
- Ensure no circular dependencies
Example:
authentication.md depends on user-management.md
→ Check: user-management.md exists ✅
→ Check: No circular dependency (user-management depends on authentication) ✅
Check Cross-References
From authentication.md:
"See [Success Metrics: Auth Metrics](success-metrics.md#auth-metrics)"
Validation:
→ success-metrics.md exists? ✅
→ Section #auth-metrics exists in success-metrics.md? ✅
→ Link format correct? ✅
Test reading paths from index:
Path 1: Executive Overview
1. Index → Executive Summary ✅
2. Executive Summary → Vision & Objectives ✅
3. Vision & Objectives → User Personas ✅
4. User Personas → Market Analysis ✅
5. All "Back to Index" links work ✅
Generate Validation Report
# Shard Validation Report**Total Shards:** 28
**Validation Status:** ✅ PASSED
## Validation Results
✅ Internal Links: 142/142 valid (0 broken)
✅ Dependencies: 35/35 resolved
✅ Cross-References: 89/89 valid
✅ Metadata: 28/28 complete
✅ Navigation Paths: 3/3 working
## Issues Found
None ✅
---
## Recommendations- Consider adding more tags to personas.md (currently only 1 tag)
- Feature shards could benefit from examples section
- Add glossary shard for technical terms
Output: Validation report with broken link list and recommendations
See:references/validation-checklist.md for comprehensive validation
Common Scenarios
Scenario 1: Large PRD (3,000+ lines)
Context: Single PRD file too large to navigate
Approach:
Strategy: Logical sharding
Shard by major sections (Executive, Personas, Features, etc.)
Create features/ subdirectory (one shard per feature)
