---
id: shard-doc
agent: pm
title: Shardear um documento grande em partes consumíveis
inputs: [documento (PRD, arquitetura ou spec), destino do shard]
outputs: [pasta de shards por seção, index.md com links, documento-fonte preservado]
elicit: false
modes: [interactive, yolo]
---

# Shardear um documento grande em partes consumíveis

**Objetivo:** quebrar um documento grande (PRD, arquitetura, spec) em arquivos menores por seção,
com um índice navegável — para que @sm, @dev e @qa consumam só o pedaço que precisam, sem carregar
o documento inteiro.

**Pré-condições:**
- O documento-fonte existe e está em Markdown com headings de nível 2 (`##`) bem definidos. Se não
  tiver estrutura de seções clara, **pare** e reporte — shardear um documento sem fronteiras gera
  pedaços sem sentido.
- O destino do shard é uma pasta sob `docs/` (ex.: `docs/prd/`, `docs/architecture/`). Se não foi
  dado, derivo do tipo de documento; se ambíguo, elicito — não invento o destino.

## Passos

1. **Leia o documento-fonte completo** e mapeie as seções de nível 2 (`##`). Cada `##` vira um shard.
   Subseções (`###`) ficam dentro do shard do seu pai — não viram arquivo próprio.
2. **Defina a pasta de destino** sob `docs/` (ex.: `docs/prd/`, `docs/architecture/`). Crie-a se não
   existir. O documento-fonte original **permanece intacto** — shardear copia, não move nem apaga.
3. **Gere um arquivo por seção.** Para cada heading `##`:
   a. crie `docs/{destino}/{slug-da-seção}.md` (slug em kebab-case derivado do título);
   b. copie o conteúdo da seção (incluindo subseções `###`) sem alterar o texto — fidelidade ao
      fonte é a regra (No invention, Art. IV: não reescrevo o requisito ao shardear);
   c. promova o heading da seção a `#` (nível 1) no topo do shard, para o arquivo ler bem isolado.
4. **Crie o `index.md`** na pasta de destino: um sumário com link para cada shard, na ordem original
   do documento, mais uma linha apontando para o documento-fonte. É o ponto de entrada da navegação.
5. **Verifique a fidelidade:** a soma do conteúdo dos shards cobre todas as seções do fonte, sem
   perda e sem duplicação. Nenhum link do `index.md` aponta para arquivo inexistente.
6. **Reporte o resultado:** liste os shards gerados e o caminho do `index.md`. O documento-fonte segue
   como a fonte da verdade; os shards são a projeção consumível.
7. **Não subo nada.** Se os shards precisam ir pro repositório remoto, eu delego ao @devops — `git
   push` / PR são EXCLUSIVOS dele. Eu deixo os arquivos prontos no working tree.

## Critério de pronto (DoD)

- [ ] Um shard por seção de nível 2 do documento-fonte, em `docs/{destino}/`
- [ ] `index.md` criado com links na ordem original + link para o documento-fonte
- [ ] Conteúdo dos shards fiel ao fonte (sem perda, sem reescrita, sem duplicação)
- [ ] Documento-fonte preservado intacto
- [ ] Todos os links do `index.md` resolvem para arquivos existentes
- [ ] Nada de `git push` (delegado ao @devops)

## Falha / recuperação

- **Documento sem headings `##` claros** → HALT, reporto que o fonte não tem estrutura shardeável e
  devolvo para o autor estruturar antes.
- **Destino ambíguo ou inexistente** → elicito a pasta de destino em vez de adivinhar.
- **Conteúdo se perderia ou duplicaria na divisão** (seções aninhadas mal formadas) → paro, reporto a
  ambiguidade estrutural e não gero shards inconsistentes.
- **Os shards precisam ir ao remoto** → delego a subida ao @devops; não rodo `git push`.