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.
Instrucciones de origen · Vista previa de solo lectura
name
shard-document
description
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)
