BMAD-METHOD/docs/conversion-report-shard-doc-2025-10-26.md

Legacy Task Conversion Report

Generated: 2025-10-26 Converted By: BMad Builder Agent Conversion Type: Legacy Task → v6 XML Task

---

Source Information

• Original Location: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/bmad-core/tasks/shard-doc.md
• Original Format: Markdown task (v4/legacy format)
• Original Type: Document sharding utility task

---

Target Information

• New Location: /Users/brianmadison/dev/BMAD-METHOD/src/core/tasks/shard-doc.xml
• New Format: v6 XML task format
• Task ID: bmad/core/tasks/shard-doc
• Task Name: Shard Document

---

Conversion Summary

Components Converted

✅ Task Structure: Converted from markdown to XML format ✅ Execution Flow: 6 steps properly structured in <flow> section (simplified to tool-only) ✅ Critical Instructions: Moved to <llm critical="true"> section ✅ Validation Rules: Extracted to <validation> section ✅ Halt Conditions: Extracted to <halt-conditions> section ✅ Special Guidelines: Moved to <critical-context> section ✅ Output Format: Documented in <output-format> section ✅ Tool Information: Preserved in <tool-info> section

Key Features Preserved

• Automated Tool: Uses @kayvan/markdown-tree-parser exclusively
• Simplified Flow: Removed all manual steps, tool handles everything
• Code Block Awareness: Tool automatically handles ## inside code blocks
• Content Preservation: Tool preserves all markdown formatting and special content
• Heading Adjustment: Tool automatically reduces heading levels by one
• Index Generation: Tool automatically creates index.md
• Validation Steps: Verification of tool installation and output
• Error Handling: Halt conditions for tool and file system issues

v6 Conventions Applied

• ✅ Proper <task> wrapper with id and name attributes
• ✅ <llm critical="true"> section with mandatory instructions
• ✅ <flow> section with numbered <step> elements
• ✅ Used <action> tags for required actions
• ✅ Used <i> tags for instruction lists and context
• ✅ Conditional logic with if attributes on actions
• ✅ Optional steps marked with optional="true"
• ✅ Supporting sections for validation, halt conditions, output format
• ✅ Consistent with existing v6 tasks (workflow.xml, adv-elicit.xml, index-docs.xml)

---

Structural Comparison

Legacy Format (Markdown)

# Document Sharding Task
## Primary Method: Automated Approach
## Manual Method (Fallback)
1. Identify target location
2. Parse sections
...
## Critical Guidelines

v6 Format (XML)

<task id="bmad/core/tasks/shard-doc" name="Shard Document">
  <objective>...</objective>
  <llm critical="true">...</llm>
  <critical-context>...</critical-context>
  <flow>
    <step n="1" title="...">
      <action>...</action>
    </step>
  </flow>
  <halt-conditions>...</halt-conditions>
  <validation>...</validation>
</task>
```yaml

---

## Validation Results

### XML Structure

- ✅ Valid XML syntax
- ✅ Properly nested elements
- ✅ All tags closed correctly
- ✅ Attributes properly formatted

### v6 Compliance

- ✅ Matches v6 task conventions
- ✅ Follows existing core task patterns
- ✅ Uses standard v6 tag set
- ✅ Proper section organization

### Content Integrity

- ✅ All original instructions preserved
- ✅ No functionality lost in conversion
- ✅ Critical warnings maintained
- ✅ Tool information preserved
- ✅ Validation logic intact

### File System

- ✅ Saved to correct location: `src/core/tasks/`
- ✅ Proper filename: `shard-doc.xml`
- ✅ Follows core task naming convention

---

## Usage Notes

### How to Invoke This Task

From an agent or workflow, reference:

```xml
<invoke-task>{project-root}/bmad/core/tasks/shard-doc.xml</invoke-task>

Or from agent menu:

menu:
  - trigger: shard
    description: 'Split large document into organized files'
    exec: '{project-root}/bmad/core/tasks/shard-doc.xml'