3.6 KiB

Raw Blame History

Document Sharding Task

Purpose

Split a large document into multiple smaller documents based on level 2 sections
Create a folder structure to organize the sharded documents
Maintain all content integrity including code blocks, diagrams, and markdown formatting

Task Instructions

Identify Document and Target Location

Determine which document to shard (user-provided path)
Create a new folder under docs/ with the same name as the document (without extension)
Example: docs/prd.md → create folder docs/prd/

Parse and Extract Sections

CRITICAL AEGNT SHARDING RULES:

Read the entire document content
Identify all level 2 sections (## headings)
For each level 2 section:
- Extract the section heading and ALL content until the next level 2 section
- Include all subsections, code blocks, diagrams, lists, tables, etc.
- Be extremely careful with:
  - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
  - Mermaid diagrams - preserve the complete diagram syntax
  - Nested markdown elements
  - Multi-line content that might contain ## inside code blocks

CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]

3. Create Individual Files

For each extracted section:

Generate filename: Convert the section heading to lowercase-dash-case
- Remove special characters
- Replace spaces with dashes
- Example: "## Tech Stack" → tech-stack.md
Adjust heading levels:
- The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
- All subsection levels decrease by 1:
```
  - ### → ##
  - #### → ###
  - ##### → ####
  - etc.
```
Write content: Save the adjusted content to the new file

4. Create Index File

Create an index.md file in the sharded folder that:

Contains the original level 1 heading and any content before the first level 2 section
Lists all the sharded files with links:

# Original Document Title

[Original introduction content if any]

## Sections

- [Section Name 1](./section-name-1.md)
- [Section Name 2](./section-name-2.md)
- [Section Name 3](./section-name-3.md)
  ...

5. Preserve Special Content

Code blocks: Must capture complete blocks including:
```
content
```
Mermaid diagrams: Preserve complete syntax:
```
graph TD
...
```
Tables: Maintain proper markdown table formatting
Lists: Preserve indentation and nesting
Inline code: Preserve backticks
Links and references: Keep all markdown links intact
Template markup: If documents contain {{placeholders}} ,preserve exactly

6. Validation

After sharding:

Verify all sections were extracted
Check that no content was lost
Ensure heading levels were properly adjusted
Confirm all files were created successfully

7. Report Results

Provide a summary:

Document sharded successfully:
- Source: [original document path]
- Destination: docs/[folder-name]/
- Files created: [count]
- Sections:
  - section-name-1.md: "Section Title 1"
  - section-name-2.md: "Section Title 2"
  ...

Important Notes

Never modify the actual content, only adjust heading levels
Preserve ALL formatting, including whitespace where significant
Handle edge cases like sections with code blocks containing ## symbols
Ensure the sharding is reversible (could reconstruct the original from shards)

3.6 KiB Raw Blame History