---
name: rcode-shard-doc
description: "Splits large markdown documents into smaller, organized files based on level 2 (default) sections."
triggers:
  - "shard doc"
---
@.rcode/references/karpathy-guidelines.md


# Shard Document

**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.

## Overview

Shard doc skill for rcode.

## CRITICAL RULES

- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
- DO NOT skip steps or change the sequence
- HALT immediately when halt-conditions are met
- Each action within a step is a REQUIRED action to complete that step

## EXECUTION

### Step 1: Get Source Document

- Ask user for the source document path if not provided already
- Verify file exists and is accessible
- Verify file is markdown format (.md extension)
- If file not found or not markdown: HALT with error message

### Step 2: Get Destination Folder

- Determine default destination: same location as source file, folder named after source file without .md extension
  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
- If user accepts default: use the suggested destination path
- If user provides custom path: use the custom destination path
- Verify destination folder exists or can be created
- Check write permissions for destination
- If permission denied: HALT with error message

### Step 3: Execute Sharding

- Inform user that sharding is beginning
- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
- Capture command output and any errors
- If command fails: HALT and display error to user

### Step 4: Verify Output

- Check that destination folder contains sharded files
- Verify index.md was created in destination folder
- Count the number of files created
- If no files created: HALT with error message

### Step 5: Report Completion

- Display completion report to user including:
  - Source document path and name
  - Destination folder path
  - Number of section files created
  - Confirmation that index.md was created
  - Any tool output or warnings
- Inform user that sharding completed successfully

### Step 6: Handle Original Document

> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.

Present user with options for the original document:

> What would you like to do with the original document `[source-document-name]`?
>
> Options:
> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
> - `[m]` Move to archive - Move original to a backup/archive location
> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
> - `[x]` Cancel - Keep original and exit without changing anything
>
> Your choice (d/m/k/x):

#### If user selects `x` (cancel)

- Do not delete or move the original document
- Inform user: "Cancelled. Original document kept at: [source-document-path]. No changes made."
- End the skill

#### If user selects `d` (delete)

- **Before deleting, confirm with the user:**
  > About to delete 1 file: `[source-document-path]`. This cannot be undone. Continue?
  > - `[y]` Yes — delete the original
  > - `[n]` No — keep the original and exit
- If user selects `n`: inform user "Cancelled. Original document kept at: [source-document-path]." and end the skill.
- If user selects `y`: proceed with deletion.
- Delete the original source document file
- Confirm deletion to user: "Original document deleted: [source-document-path]"
- Note: The document can be reconstructed from shards by concatenating all section files in order

#### If user selects `m` (move)

- Determine default archive location: same directory as source, in an `archive` subfolder
  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
- If user accepts default: use default archive path
- If user provides custom path: use custom archive path
- Create archive directory if it does not exist
- Move original document to archive location
- Confirm move to user: "Original document moved to: [archive-path]"

#### If user selects `k` (keep)

- Display warning to user:
  - Keeping both original and sharded versions is NOT recommended
  - The discover_inputs protocol may load the wrong version
  - Updates to one will not reflect in the other
  - Duplicate content taking up space
  - Consider deleting or archiving the original document
- Confirm user choice: "Original document kept at: [source-document-path]"

## Workflow

1. Read the user request and extract key parameters.
2. Execute the skill logic as described in the Overview.
3. Return output in the format specified below.

## Output Format

- Structured Markdown response
- Headers for each section
- Concise, actionable content

## Examples

### Happy path
**User:** "shard document ./docs/architecture.md"
**Result:** Splits into `architecture/` folder with section files + index.md → asks what to do with original

### Edge case
**User:** "shard document" + non-markdown file
**Result:** HALT — file must be .md format

### Negative boundary
**User:** "split this into smaller components"
**Result:** If referring to code, not a doc sharding task. If referring to a document, proceed with sharding.

## HALT CONDITIONS

- HALT if npx command fails or produces no output files

## Memory Bank Hooks

- **Reads:** the source document being sharded
- **Writes:** the sharded output files only; does NOT modify `.rcode/memory/`. If the sharded doc is a Memory Bank file, use `rcode-memory-distill` instead.
