refactor(skills): convert shard-doc.xml to native skill directory

[alexeyv]

Summary

• Converts shard-doc.xml (single-file XML task) into a native skill directory at src/core/tasks/bmad-shard-doc/ with SKILL.md, workflow.md, and bmad-skill-manifest.yaml
• Updates module-help.csv to reference skill:bmad-shard-doc instead of the XML file
• Removes the old XML entry from bmad-skill-manifest.yaml

Test plan

• Verify bmad-shard-doc skill triggers correctly via Claude Code
• Confirm shard-doc workflow behaves identically to the old XML version
• Check that module-help lists the skill reference correctly

🤖 Generated with Claude Code

[augmentcode]

🤖 Augment PR Summary

Summary: Migrates the shard-document task from legacy XML into the repo’s native “skill directory” format so it can be invoked as bmad-shard-doc.

Changes:

• Added src/core/tasks/bmad-shard-doc/ with SKILL.md, workflow.md, and a bmad-skill-manifest.yaml declaring type: skill.
• Updated core module help to reference skill:bmad-shard-doc instead of the old XML task.
• Removed the legacy shard-doc.xml file and its entry from src/core/tasks/bmad-skill-manifest.yaml.

Technical Notes: The new workflow preserves the interactive sharding process using npx @kayvan/markdown-tree-parser explode, includes output verification, and provides options to delete/move/keep the original document.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 2 suggestions posted.

Comment augment review to trigger a new review at any time.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR migrates the shard-doc task from XML-based definition to a markdown-based skill format. The old XML task definition and its manifest entry are removed, replaced with markdown documentation files: SKILL.md for description, workflow.md for step-by-step instructions, and bmad-skill-manifest.yaml for skill metadata.

Changes

Cohort / File(s)	Summary
Removed Old Format src/core/tasks/shard-doc.xml, src/core/tasks/bmad-skill-manifest.yaml	Removed XML task definition (~108 lines) and corresponding manifest entry for shard-doc functionality.
Added New Markdown-based Skill src/core/tasks/bmad-shard-doc/SKILL.md, src/core/tasks/bmad-shard-doc/bmad-skill-manifest.yaml, src/core/tasks/bmad-shard-doc/workflow.md	Added skill description file, manifest descriptor, and detailed 100-line workflow documenting six-step sharding process with execution rules, user prompts, error handling, and post-sharding options for original document management.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• PR #1868: Refactors installer/validation to treat SKILL.md as canonical skill entry point; aligns with this PR's shift to markdown-based skill definitions.
• PR #1857: Performs identical XML-to-markdown skill conversion pattern for another task, demonstrating consistent refactoring approach across the codebase.

Suggested reviewers

• bmadcode

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: converting shard-doc.xml to a native skill directory structure.
Description check	✅ Passed	The description accurately outlines the conversion from XML task to native skill directory, mentions key files and changes, and provides a test plan.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 9

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/core/tasks/bmad-shard-doc/SKILL.md`:
- Around line 2-3: The skill description for bmad-shard-doc is too literal and
may miss common phrasing; update the description string in SKILL.md (the name:
bmad-shard-doc block) to include broader trigger phrases and synonyms such as
"split", "shard", "chunk", "split into sections/files", "explode", "separate by
headings", and examples like "split this markdown into shards" or "explode
architecture.md into section files", while keeping the behavior note about using
level 2 sections as the default; ensure the new description still clearly
indicates it splits large markdown docs into smaller organized files by H2
(default).

In `@src/core/tasks/bmad-shard-doc/workflow.md`:
- Around line 79-85: The archive step currently moves the original file to
[archive-path] without checking for an existing file; update the workflow logic
around "Determine default archive location" and "Move original document to
archive location" so it first checks if [archive-path] already exists and avoids
silent overwrite: if the path exists, either prompt the user to confirm
overwrite, offer to provide a custom path, or automatically generate a
non‑colliding name (e.g. append a timestamp or incremental suffix), ensure the
archive directory is still created when missing, and only perform the move after
the existence check and user choice are resolved.
- Around line 23-30: Update the destination handling to reject non-empty
folders: after "Verify destination folder exists or can be created" and before
"Check write permissions for destination", add logic to inspect the destination
directory contents; if the directory exists and is not empty, halt and prompt
the user to either choose a different destination, confirm explicit
overwrite/clean (only if they explicitly opt-in), or cancel; ensure this
behavior is applied whether using the default path (from "Determine default
destination") or a custom path provided by the user, and only proceed to "Check
write permissions for destination" when the folder is empty or the user has
explicitly agreed to overwrite/clean it.
- Around line 58-75: The workflow currently recommends deletion without
verifying shards can reconstruct the original; update the prompt and the `If
user selects \`d\` (delete)` branch so deletion is only allowed after a
successful round-trip rebuild and validation: implement a reconstruction step
that concatenates shards, compare checksums or content equality with the
original, and only then perform removal and show "Original document deleted:
[source-document-path]"; also change the prompt text around the options (the
"recommended" label) to remove recommending `d` and instead flag deletion as
destructive unless verification passes.
- Around line 48-53: The completion report claims to show "section files
created" but the workflow only computes a total file count in Step 4; update the
report logic in the workflow so it either (A) computes a separate
sectionFilesCount by excluding index.md and known auxiliary files (e.g.,
subtract 1 for index.md and any other aux filenames) before rendering the
completion report, or (B) change the report text in Step 5 to accurately reflect
the computed metric (e.g., "total files created") so the label matches the
existing totalFiles value; refer to the Step 4 totalFiles computation and the
Step 5 completion report text and the literal "index.md" when making the change.
- Line 35: Update the shell example in workflow.md so the file-system
placeholders are quoted to handle spaces/special chars: replace the unquoted
command string `npx `@kayvan/markdown-tree-parser` explode [source-document]
[destination-folder]` with a version that wraps the two arguments in quotes
(e.g. `"...explode \"[source-document]\" \"[destination-folder]\""`), ensuring
the instruction consistently shows quoted placeholders for source and
destination to avoid shell-parsing issues.
- Line 35: Update the example command to pin the parser version to ensure
deterministic runs: replace `npx `@kayvan/markdown-tree-parser` explode
[source-document] [destination-folder]` with a version-pinned invocation such as
`npx `@kayvan/markdown-tree-parser`@1.6.1 explode [source-document]
[destination-folder]` (or another chosen fixed version) so the
`markdown-tree-parser` tool call is deterministic.
- Around line 73-86: The delete (`d`) and move (`m`) branches currently assume
filesystem ops succeed; update the workflow steps that perform "Delete the
original source document file", "Create archive directory if it does not exist",
and "Move original document to archive location" to check the result/error of
each filesystem operation, handle failures by aborting the workflow or prompting
the user, and only print the confirmations "Original document deleted:
[source-document-path]" or "Original document moved to: [archive-path]" after
success; on error include the error message, do not proceed to subsequent steps,
and ensure the mkdir/move functions return and surface errors to the caller so
the workflow can halt or retry.
- Around line 41-45: Replace the weak "index.md + file count > 0" check with
stronger content and coverage validation: derive the expected sections from the
source document's TOC (or expected section list), then (1) verify index.md
contains entries for each expected section, (2) ensure the number of shard files
in the destination folder matches the expected section count, (3) for each shard
file confirm it begins with the matching section header listed in index.md and
contains a minimum content threshold (e.g., >N words or tokens) to avoid
empty/malformed shards, and fail the workflow if any file is missing,
mismatched, too small, or if coverage of expected sections is incomplete.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 16c14fda-1b1d-405e-a703-481399095591

📥 Commits

Reviewing files that changed from the base of the PR and between 6292b03 and 367e7dc.

⛔ Files ignored due to path filters (1)

• src/core/module-help.csv is excluded by !**/*.csv

📒 Files selected for processing (5)

• src/core/tasks/bmad-shard-doc/SKILL.md
• src/core/tasks/bmad-shard-doc/bmad-skill-manifest.yaml
• src/core/tasks/bmad-shard-doc/workflow.md
• src/core/tasks/bmad-skill-manifest.yaml
• src/core/tasks/shard-doc.xml

💤 Files with no reviewable changes (2)

• src/core/tasks/shard-doc.xml
• src/core/tasks/bmad-skill-manifest.yaml