ejklock/living-docs-skill

Living Docs

Trate a documentação como um sistema vivo que permanece sincronizado com o código, não como um artefato escrito uma vez que apodrece. A disciplina tem uma espinha dorsal — cada pedaço de conhecimento tem exatamente um lar, esse lar é indexado, e nada estrutural é enviado sem seu documento — e vários tipos de documento que pendem dela: uma constituição, ADRs, BDRs, PRDs, issues, pesquisa, diagramas de arquitetura e um índice de contexto semântico.

Esta habilidade é independente de stack. Ela governa como os documentos são organizados e mantidos, nunca qual tecnologia um projeto usa.

---

Invariantes centrais (a espinha dorsal)

Eles se aplicam a todos os tipos de documento. Todo o resto é detalhe.

1. Documentação primeiro. Crie o corpo no repositório (docs/…) antes de publicá-lo externamente (tracker, wiki). O arquivo no repositório é a fonte da verdade; a cópia externa é um espelho.
2. Um lar por fato. Cada conceito, decisão ou requisito vive em exatamente um arquivo. Sem duplicação — faça referência cruzada em vez de copiar. Prosa duplicada é deriva esperando para acontecer.
3. Indexado ou não existe. Todo documento é acessível a partir de um índice (uma listagem index.md em seu diretório, e o docs/index.md raiz do pacote que o guia do projeto referencia). Nenhum arquivo órfão.
4. Suplantar, nunca reescrever a história. Decisões e requisitos são registros somente de acréscimo. Quando algo muda, marque o registro antigo como suplantado e escreva um novo — nunca edite o passado silenciosamente.
5. Nenhuma mudança estrutural sem seu documento. Novo módulo, arquivos movidos, mudança de esquema, novo fluxo de dados → atualize o documento relevante e seu diagrama na mesma alteração. Sem "documentarei depois".

Em caso de dúvida, derive a ação correta a partir destes cinco. Os arquivos de regras abaixo são apenas estes invariantes aplicados a cada tipo de documento.

---

Formato: conforme OKF

Os cinco invariantes governam organização e ciclo de vida; o Open Knowledge Format governa o formato do arquivo para que o corpus permaneça portátil e analisável por agentes. Cada documento no sistema é também um conceito OKF. Carregue a habilidade okf-knowledge-format (ela fornece a especificação) ao criar ou verificar o formato.

OKF é uma dependência fina e substituível — não uma fundação (risco de versão). OKF é v0.1 de um único fornecedor; uma v0.2 incompatível com versões anteriores é uma possibilidade real. Os invariantes acima não dependem de OKF — dependem apenas de um pequeno conjunto de campos de frontmatter, para que uma quebra do OKF não derrube a camada de governança junto. Mantenha o limite explícito:

• Obrigatório pelo Living Docs (o contrato de fato que scripts/lint-docs.sh aplica): um type não vazio, e status + superseded_by em registros suplantados. Estes são nossos; eles sobrevivem independentemente de OKF.
• Herdado do OKF (convenções de formato): index.md/log.md reservados, o okf_version raiz do pacote, links relativos ao pacote, o cabeçalho # Referências (§8). Se OKF mudar, apenas esta linha se move — repinque a versão na habilidade okf-knowledge-format e ajuste.

Duas regras se aplicam a todo arquivo de conceito:

1. Frontmatter com um type obrigatório. Todo documento .md não reservado abre com um bloco de frontmatter YAML cujo type nomeia o tipo de documento (Constitution, PRD, ADR, BDR, Issue, Context, Architecture View, Research, Reference). Recomendado: title, description, tags, timestamp. Living-docs adiciona chaves de produtor: status, supersedes, superseded_by. Status vai para o frontmatter — sem linha de corpo **Status:**.
2. Arquivos reservados + links relativos ao pacote. A raiz do pacote é docs/. Listagens de diretório são index.md (OKF §6, sem frontmatter — exceto o docs/index.md raiz do pacote, que carrega okf_version: "0.1"). log.md opcional registra o histórico do diretório (§7). Faça referência cruzada com caminhos relativos ao pacote prefixados por / (/adr/0007-slug.md); liste fontes sob um cabeçalho # Referências (§8), cada entrada formatada conforme rules/citation-conventions.md — estrutura ABNT NBR 6023, sempre carregando o link, com rótulos conectivos no idioma do documento do projeto (padrão inglês: Available at: <URL>. Accessed on: <date>) conforme rules/doc-language.md.

---

Trilha de documentos

Toda mudança segue esta cadeia, da fonte fundamental da verdade até o código:

flowchart LR
  C[constituição] --> P[PRD]
  P --> A[ADR]
  P --> B[BDR]
  A --> I[issues]
  B --> I
  I --> K[código]

Artefato	Função
constituição	Fonte fundamental da verdade: o que é o produto, modelo de dados central, inegociáveis. Todos os outros documentos estão abaixo dela.
PRD	O que o sistema deve fazer e porquê — especificação de requisitos de produto/recurso.
ADR	Como o sistema é estruturado — decisão arquitetural/de implementação e justificativa.
BDR	O que o sistema deve fazer observavelmente — entradas, saídas, efeitos colaterais, cenários Dado/Quando/Então — e como cada um é testado (a matriz de Design de Teste; lar único para "como testar", uma issue de execução o referencia).
issues	Fatias de execução — unidades discretas de trabalho que rastreiam de volta para ADRs/BDRs.
código	Implementação — todo comportamento, estrutura e interface especificados acima, realizados.

---

Quando invocar

• Estruturando documentação para um projeto (criando a estrutura docs/, o índice de documentos, diretórios ADR/issue/BDR/constituição).
• Primeira vez que living-docs é executado em um projeto (sem bloco ## Living Docs no guia do projeto) → faça a pergunta do modo de aplicação e persista a resposta → veja Modos de aplicação.
• Adotando living-docs em um projeto existente/legado (decisões já tomadas mas não documentadas) → siga Procedimento → Adotando living docs em um projeto existente: faça um inventário das decisões, confirme cada uma com o usuário antes de registrar qualquer ADR, nunca preencha retrospectivamente apenas por inferência.
• Escrevendo ou editando um ADR (uma decisão arquitetural/de implementação) → carregue rules/adr-conventions.md + templates/adr.md.
• Escrevendo ou editando um PRD (uma especificação de requisitos de produto/recurso) → carregue rules/prd-conventions.md + templates/prd.md.
• Escrevendo ou editando um BDR (comportamento observável — entradas, saídas, cenários Dado/Quando/Então, e a matriz de Design de Teste para como cada um é testado) → carregue rules/bdr-conventions.md + templates/bdr.md. Uma decisão de estratégia de teste (nível/técnica não padrão, desvio de barra) é um ADR tags: [testing], não um novo tipo de registro (sem "TDR").
• Especificando um requisito não funcional (desempenho, disponibilidade, segurança, escala) → um cenário de atributo de qualidade vinculado a um instrumento no PRD (rules/prd-conventions.md regra 9 + templates/prd.md); a decisão + função de adequação vão em um ADR. Não é um novo tipo de documento.
• Estabelecendo ou alterando a constituição (escopo fundamental, modelo de dados, inegociáveis) → carregue rules/constitution-conventions.md + templates/constitution.md.
• Criando ou editando uma issue/ticket → carregue rules/issue-workflow.md + templates/issue.md.
• Registrando pesquisa (avaliação de tecnologia, trade-offs externos) → carregue a habilidade research-artifacts. Ela é responsável pelo formato de nota de pesquisa OKF (um arquivo por nota, sem subpasta por pesquisa), pela disciplina de fonte e pela cadeia rastreável pesquisa → decisão → issue, e referencia este documento para os artefatos ADR/BDR/issue. Pareia com a habilidade deep-research.
• Desenhando ou atualizando um diagrama de arquitetura, fluxo de dados ou chamada de ferramenta → carregue rules/architecture-diagrams.md + templates/architecture-index.md.
• Definindo um termo ou acrônimo que os documentos usam → adicione-o ao glossário (docs/context/glossary.md), um lar por termo → carregue rules/glossary-conventions.md + templates/glossary.md.
• Um documento cresceu demais ou mistura preocupações → divida em um índice semântico → carregue rules/semantic-index.md + templates/context-index.md.
• Aplicando a regra de manutenção sem deriva após qualquer mudança estrutural → carregue rules/maintenance-invariant.md.
• Criando ou verificando o formato OKF de qualquer documento (frontmatter type, index.md/log.md reservados, links relativos ao pacote, # Referências) → carregue a habilidade okf-knowledge-format.
• Decidindo qual idioma os documentos serão escritos (padrão inglês; o usuário pode substituir no início da sessão e fixá-lo) → carregue rules/doc-language.md.

---

Mapa de documentos

Tipo	Vive em	Propósito	Mutabilidade
Guia do projeto	CLAUDE.md / README.md (raiz)	Ponto de entrada: escopo, stack, índice de documentos, fluxos de trabalho obrigatórios	Vivo — edite livremente
Constituição	docs/constitution.md	Fonte fundamental da verdade: escopo do produto, modelo de dados, inegociáveis	Somente acréscimo uma vez ratificada (registro de emendas)
Índice de contexto	docs/context/index.md + arquivos de grupo	Vocabulário de domínio e módulo, agrupado semanticamente	Vivo — edite livremente
Glossário	docs/context/glossary.md	Termos e acrônimos definidos uma vez, no idioma do documento (acrônimos principais como estão)	Vivo — edite livremente
Arquitetura	docs/architecture.md ou docs/architecture/ + índice	Diagramas Mermaid vivos: estrutura, modelo de dados, fluxos, chamada de ferramenta	Vivo — deve corresponder ao código
ADR	docs/adr/NNNN-slug.md	Uma decisão arquitetural/de implementação	Somente acréscimo (suplantar)
BDR	docs/bdr/NNNN-slug.md	Uma decisão de comportamento observável	Somente acréscimo (suplantar ou alterar)
PRD	docs/prd/NNNN-slug.md	Uma especificação de requisitos de produto/recurso	Somente acréscimo uma vez aceito
Issue	docs/issues/NNNN-slug.md	Espelho do tracker (corpo), um por ticket	Corpo editável; cópia publicada segue
Pesquisa	docs/research/NNNN-<slug>.md (arquivo único, sem subpasta; número sequencial lidera, data no frontmatter timestamp; termina em # Referências)	Evidência externa com alegações com fonte	Somente acréscimo (evidência é datada)

Cada diretório carrega seu próprio index.md de listagem (OKF §6, sem frontmatter). O "Índice de documentos" do guia do projeto referencia o docs/index.md raiz do pacote. Veja rules/semantic-index.md para o contrato de indexação.

---

Procedimento

Configurando living docs em um novo projeto

1. Faça a pergunta do modo de aplicação (veja Modos de aplicação → Pergunta de primeira execução) antes de qualquer outra coisa, já que nenhuma preferência está persistida ainda. Registre a resposta como o bloco ## Living Docs no guia do projeto; padrão para strict se o usuário não tiver preferência.
2. Crie o guia do projeto (CLAUDE.md ou equivalente) com uma seção Índice de documentos e uma seção Regra de manutenção (copie o texto de rules/maintenance-invariant.md). Use templates/claude-hard-rules.md como ponto de partida para a seção de regras rígidas do guia do projeto — ela já carrega o bloco de aplicação ## Living Docs; preencha os placeholders antes de commitar.
3. Crie docs/ com os diretórios que o projeto precisa (adr/, bdr/, issues/, prd/, research/, context/). Semeie docs/constitution.md a partir de templates/constitution.md. Adicione o docs/index.md raiz do pacote (carregando okf_version: "0.1"), e dê a cada diretório sua própria listagem index.md desde o primeiro dia — mesmo que quase vazia.
4. Semeie o índice de contexto (docs/context/index.md) com qualquer vocabulário de domínio que exista, e o glossário (docs/context/glossary.md) com os termos e acrônimos que os documentos já assumem (rules/glossary-conventions.md). Aumente ambos conforme conceitos são nomeados.
5. Semeie o documento de arquitetura (docs/architecture.md) com as visões Mermaid de alto nível que o sistema já possui. Promova para um diretório docs/architecture/ + índice quando crescer (rules/architecture-diagrams.md).
6. Registre quaisquer decisões já tomadas como ADRs para que não sejam re-litigadas — mas confirme cada uma com o usuário antes de registrar (veja Adotando living docs em um projeto existente, passos 3–5); nunca preencha um ADR retrospectivamente apenas por inferência.

Adotando living docs em um projeto existente (legado)

Uma base de código existente já incorpora decisões que nunca foram escritas. O modo de falha aqui é o agente preenchendo ADRs retrospectivamente por inferência e apresentando-os como estabelecidos — registrando decisões que o usuário nunca foi solicitado a confirmar. A adoção é, portanto, um exercício de elicitação, não de transcrição.

1. Faça a pergunta do modo de aplicação (primeira execução) e persista o bloco ## Living Docs, exatamente como para um novo projeto.
2. Estruturar sem decidir. Crie docs/ + o index.md de cada diretório, o docs/index.md raiz do pacote, e semeie o glossário/índice de contexto a partir de vocabulário já presente no código, no README e nos guias de agente (CLAUDE.md / AGENTS.md). Isso é mecânico — nenhuma decisão é tomada aqui.
3. Leia o contexto existente primeiro, depois faça o inventário das decisões — como candidatos, não como registros. Colha o que o projeto já carrega: o próprio código, mais o README, os guias de agente (CLAUDE.md / AGENTS.md), manifestos de pacote e quaisquer notas ou comentários de design. A partir disso, produza uma lista das decisões estruturais que o projeto parece incorporar (stack, limites, modelo de dados, trade-offs principais). Ainda não escreva ADRs.
4. Apresente o inventário ao usuário e confirme cada um. Para cada candidato, declare a decisão inferida e as alternativas que parece ter descartado, e peça ao usuário para confirmar, corrigir ou descartá-la — questione as estruturais (grill-me se instalado). O usuário é dono da decisão; o agente apenas traz à tona o que o código implica.
5. Registre apenas as decisões confirmadas como ADRs. Estes são registros de origem — eles não suplantam nada. Capture a opção escolhida e as alternativas rejeitadas que o usuário confirmou. Um candidato que o usuário descarta, ou cuja justificativa ninguém realmente conhece, não é inventado em um ADR.
6. Semeie o documento de arquitetura com as visões Mermaid de alto nível que o sistema já possui (rules/architecture-diagrams.md), então retome o loop de Manutenção abaixo.

Mantendo living docs (toda tarefa)

1. Antes de codificar: leia o modo de aplicação ## Living Docs do guia do projeto (se o bloco estiver ausente, esta é a primeira execução — faça a pergunta de primeira execução e persista a resposta). Em seguida, leia a constituição relevante, ADRs, BDRs e o contexto.

2. Durante a codificação: atualize os documentos conforme as mudanças são feitas. Se uma mudança estrutural (nova função, novo módulo, alteração de esquema) for necessária, primeiro escreva ou atualize o documento correspondente, depois implemente. O documento serve como especificação.

3. Após a codificação: execute scripts/lint-docs.sh para verificar a conformidade com os invariantes. Corrija quaisquer violações antes de commitar.

4. Para cada documento novo ou alterado: verifique se ele está listado no índice apropriado (index.md no diretório) e se o docs/index.md raiz do pacote está atualizado.

5. Para mudanças que afetam a arquitetura, modelo de dados ou fluxo: atualize os diagramas Mermaid correspondentes.

---

Modos de aplicação

O bloco ## Living Docs no guia do projeto (CLAUDE.md) contém uma única linha que define o modo:

## Living Docs

Mode: strict

Os modos disponíveis são:

• strict (padrão): Todos os cinco invariantes são aplicados. Nenhuma mudança estrutural sem documento. O script scripts/lint-docs.sh é executado a cada tarefa e falha em violações.
• advisory: Os invariantes são recomendados, mas não aplicados. O script scripts/lint-docs.sh é executado, mas falhas são avisos, não erros. Útil durante a adoção inicial.
• lax: Nenhuma aplicação. O agente ainda sugere o uso dos invariantes, mas não os verifica. Útil para exploração rápida.

Pergunta de primeira execução

Na primeira vez que Living Docs é executado em um projeto (sem o bloco ## Living Docs), faça esta pergunta:

Este projeto está adotando Living Docs? Se sim, qual modo de aplicação você prefere? (strict/advisory/lax; padrão strict)

• strict: Todos os invariantes são aplicados.
• advisory: Os invariantes são recomendados, mas não aplicados.
• lax: Nenhuma aplicação.

Se você não tem preferência, usarei strict.

Persista a resposta como o bloco ## Living Docs no guia do projeto.

---

Scripts

• scripts/lint-docs.sh: Verifica a conformidade com os invariantes centrais. Espera-se que falhe se violações forem encontradas.

---

Dependências

• okf-knowledge-format: Fornece a especificação OKF para formato de arquivo. Carregue esta habilidade ao criar ou verificar o formato de qualquer documento.
• research-artifacts: Gerencia o formato de nota de pesquisa OKF e a cadeia rastreável pesquisa → decisão → issue.
• deep-research: Pareia com research-artifacts para pesquisa aprofundada.

---

Templates

Templates para cada tipo de documento estão localizados em templates/:

• templates/adr.md
• templates/bdr.md
• templates/prd.md
• templates/constitution.md
• templates/issue.md
• templates/architecture-index.md
• templates/context-index.md
• templates/glossary.md
• templates/claude-hard-rules.md

---

Regras

Regras detalhadas para cada tipo de documento e processo estão localizadas em rules/:

• rules/adr-conventions.md
• rules/bdr-conventions.md
• rules/prd-conventions.md
• rules/constitution-conventions.md
• rules/issue-workflow.md
• rules/architecture-diagrams.md
• rules/semantic-index.md
• rules/maintenance-invariant.md
• rules/doc-language.md
• rules/citation-conventions.md
• rules/glossary-conventions.md