harness-documentation

name	harness-documentation
description	Use quando for atualizar documentação após concluir uma user story ou feature. Ativado por "documentar", "README", "doc da API", "atualizar catalog", "atualizar AGENTS.md". Sempre executar após harness-testing para fechar o loop de entrega.

Harness: Documentação (Etapa 07)

Persona: Technical writer.

Duas Camadas — Responsabilidades Distintas

.catalog/                    ← fonte de verdade técnica (versionada no repositório)
  architecture.md, conventions.md, concerns.md, features.md, stack.md...

[delivery_docs.path]/        ← docs de entrega quando `project_tracking.tool: local` ou fallback (padrão: .milestones/)
Ferramenta de rastreamento   ← issues/cards/epics/stories conforme project_tracking.tool

Regra: AGENTS.md é a tabela de roteamento (≤100 linhas) — aponta para .catalog/ e para os itens de rastreamento.

Tipo A — Docs de Entrega (atualizar quando forem a fonte ativa)

Após cada [level2] concluída, atualizar estes arquivos quando project_tracking.tool: local ou quando uma ferramenta externa caiu para fallback markdown:

• [delivery_docs.path]/[level1-nome]/[level2-XX]/changelog.md — o que mudou, por quê, impacto
• [delivery_docs.path]/[level1-nome]/[level2-XX]/tech-spec.md — marcar tasks completas, atualizar status para ✅
• [delivery_docs.path]/[level1-nome]/[level1].md — marcar [level2] completa

Fechar entrega conforme project_tracking.tool — ver references/11-project-tracking.md. Não duplique docs locais se GitHub/Jira/Linear/Azure DevOps é a fonte de verdade ativa e conectada.

Tipo B — Docs de Contexto (atualizar APENAS se algo mudou)

Atualizar somente quando a US introduziu algo novo:

Arquivo	Quando atualizar
.catalog/features.md	Nova funcionalidade implementada
.catalog/architecture.md	Novo ADR, mudança de camada, padrão estrutural
.catalog/conventions.md	Novo padrão de código emergiu
.catalog/concerns.md	Nova dívida técnica ou risco
.catalog/stack.md	Nova dependência ou configuração

Jamais delete ADRs — são a memória histórica do projeto.

Changelog e Release Notes

Situação	Abordagem
release_management.strategy: github-auto-release	Label release:* no PR e release notes geradas pelo workflow
release_management.strategy: github-legacy	Milestone versionada apenas se configurada; release notes conforme convenção
release_management.strategy: release-please	Conventional Commits → geração automática de CHANGELOG.md e Release
release_management.strategy: manual-changelog	Manter CHANGELOG.md ou changelog de entrega manual
release_management.strategy: none	Não criar changelog/release formal

Regra: Nunca escrever changelog versionado manualmente se release_management.strategy delega isso a github-auto-release ou release-please. Ver harness-engineering/references/13-release-management.md.

Saída Esperada

Sempre: entrega fechada conforme project_tracking.tool; [delivery_docs.path]/ atualizado apenas se for fonte ativa ou fallback.

Se aplicável: .catalog/ atualizado + AGENTS.md atualizado se houve mudança estrutural

Próximo Passo → harness-cicd

(ou voltar para harness-implementation para a próxima US do milestone)

---

Template completo de prompt: Ver ./prompt.md