rdd-wiki-lint
Audita integridade dos artefatos RDD: contradições entre seções, artefatos órfãos, referências cruzadas quebradas, links internos inválidos e drift de estrutura. Complementa rdd-validate (que valida a DAG de RNs → downstreams) e rdd-decision-audit (que valida DECISIONS.md) com foco em integridade documental dos artefatos individualmente. Use quando o usuário pedir "lint dos documentos", "verificar integridade dos artefatos", "wiki lint", "contradições nos docs" ou "validar estrutura".
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-04
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- rdd-wiki-lint
- description
- Audita integridade dos artefatos RDD: contradições entre seções, artefatos órfãos, referências cruzadas quebradas, links internos inválidos e drift de estrutura. Complementa rdd-validate (que valida a DAG de RNs → downstreams) e rdd-decision-audit (que valida DECISIONS.md) com foco em integridade documental dos artefatos individualmente. Use quando o usuário pedir "lint dos documentos", "verificar integridade dos artefatos", "wiki lint", "contradições nos docs" ou "validar estrutura".
03 SKILL.md 正文
rdd-wiki-lint — Lint de Integridade Documental
Audita os artefatos RDD em busca de problemas de integridade que não são cobertos pelas outras skills de validação: contradições entre seções, artefatos órfãos, referências cruzadas quebradas, links internos inválidos e desvio de estrutura/templado.
Diferenciação:
| Skill | Escopo | O que valida |
|---|---|---|
rdd-validate |
DAG de documentos | RNs sem downstream, IDs quebrados na DAG, CRs stale |
rdd-decision-audit |
DECISIONS.md | Conflitos semânticos, sequência de IDs, referências |
rdd-drift-detector |
Qualidade temporal | Tendência de degradação (baseline vs atual) |
rdd-wiki-lint |
Integridade documental | Contradições, órfãos, links, estrutura, placeholders |
Referências
- Estrutura de artefatos: IMP-011
- Templates de artefatos:
CONSTITUTION.md §4(DAG) - Formato de artefatos: convenções de front matter e seções
Resolução de caminhos (IMP-011)
Os artefatos do módulo seguem a estrutura com subpastas (IMP-011):
- Raiz: PROJECT_CHARTER.md, CONSTITUTION.md, REQUIREMENTS.md, DECISIONS.md, CHANGELOG.md
specs/: DATA_MODEL.md, API_CONTRACTS.md, ERROR_CATALOG.md, UI_SPEC.md, ARCHITECTURE.md, SECURITY.md, ACCEPTANCE_CRITERIA.md, USER_STORIES.md, US<NNN>.md, FIGMA_PROMPTS.md, COMPLIANCE.mdquality/: TEST_STRATEGY.md, DEFINITION_OF_DONE.md, TRACEABILITY.md, VALIDATION_REPORT.md, PROPAGATION_STATUS.md, PROGRESS_REPORT.mddelivery/: TASKS.md, TASKS_.md, TASKS_AZURE_CONSOLIDADO.md, SCOPE_AGREEMENT.md, CLIENT_REQUIREMENTS.md, CLIENT_REPORT_.md, HANDOVER_LOG.mdsupport/: LEGACY_CONTEXT.md, KNOWN_ERRORS.md, MIGRATION.md, CHANGE_REQUESTS.mdglossaries/: DEV_GLOSSARY.md, BUSINESS_GLOSSARY.md, USER_GLOSSARY.md, GLOSSARY.mddocs/: howto/*.md e documentos auxiliaresmeetings/,contracts/: checkpoints (inalterados)
Regra de fallback (transição): ao LER um artefato, verifique primeiro
o caminho novo (ex: specs/DATA_MODEL.md); se não existir, use o caminho
legado na raiz do módulo (ex: DATA_MODEL.md). Ao ESCREVER/GERAR, use
sempre o caminho novo. Módulos ainda não migrados via rdd-restructure
continuam legíveis durante a transição.
Lê (upstream)
- Todos os artefatos RDD do módulo (RAIZ + specs/ + quality/ + delivery/ + support/ + glossaries/ + docs/)
~/.config/opencode/skills/*/SKILL.md(para verificar templates esperados — opcional)
Gera (downstream)
<modulo>/<projeto>/quality/WIKI_LINT_<yyyy-MM-dd-hh:mm>.md(relatório de lint)
Nunca edita
- Nenhum artefato RDD. Read-only absoluto. Apenas diagnostica.
Tools
glob(listar todos os artefatos do módulo)read(ler artefatos para análise)grep(buscar referências cruzadas, placeholders, links)write(escrever WIKI_LINT_*.md)
Modo de erro
warn — se algum artefato não puder ser lido (encoding, permissão),
inclua no relatório como "não avaliado" em vez de falhar. O relatório
deve ser gerado mesmo com dados parciais.
Formato de commit
docs(quality): add wiki lint report <timestamp>
Algoritmo
Passo 1 — Descobrir módulo
Use glob para encontrar diretórios com PROJECT_CHARTER.md.
- Se nenhum → "Nenhum módulo RDD encontrado. Informe o caminho do módulo."
- Se 1 → use-o.
- Se múltiplos →
questionpara perguntar qual módulo analisar.
Registry lint: independentemente do módulo, se registry.yaml existir
na raiz da config, inclua a verificação §9 (drit registry vs views) no
relatório — escopo config, não módulo.
Passo 2 — Mapear artefatos
Use glob para listar todos os .md no diretório do módulo e subpastas.
Classifique cada arquivo pela sua localização (raiz, specs/, quality/, etc.).
Passo 3 — Executar verificações
Execute as 8 categorias de lint abaixo, em paralelo quando possível.
Passo 4 — Gerar relatório
Monte o relatório com o template e salve em quality/WIKI_LINT_<timestamp>.md.
Categorias de Lint
1. Artefatos Órfãos
Artefatos que existem mas não são referenciados por nenhum outro artefato no módulo.
Método:
- Para cada
.mdno módulo, extraia o nome base (ex:DATA_MODEL.md) - Busque por esse nome em todos os outros
.mddo módulo (exceto ele mesmo) - Se não for encontrado em nenhum → é órfão
- Warning:
specs/SECURITY.mdnão é referenciado por nenhum outro artefato - Info: Artefatos na raiz (REQUIREMENTS.md, DECISIONS.md) são naturalmente "raiz" — não são órfãos mesmo sem referência explícita
2. Referências Cruzadas Quebradas
Artefatos que referenciam outros artefatos que não existem.
Método:
- Busque por padrões de referência:
ver DATA_MODEL.md,conforme API_CONTRACTS.md,descrito em UI_SPEC.md,definido em ARCHITECTURE.md, etc. - Para cada referência encontrada, verifique se o arquivo referenciado existe
- Considere tanto o caminho novo (
specs/X.md) quanto o legado (X.md)
- Erro:
REQUIREMENTS.mdreferencia "ver specs/DATA_MODEL.md" mas o arquivo não existe - Warning:
API_CONTRACTS.mdreferencia "conforme ERROR_CATALOG.md" usando caminho legado
3. Contradições entre Seções
Detecta afirmações conflitantes dentro do mesmo artefato ou entre artefatos.
Estratégia:
- Para cada artefato, extraia afirmações factuais (frases com "é", "usa", "deve", "contém")
- Busque por termos opostos: "usar X" vs "não usar X", "obrigatório" vs "opcional", "sim" vs "não" sobre o mesmo tema
- Compare afirmações entre artefatos complementares (ex: ARCHITECTURE.md vs DATA_MODEL.md sobre tecnologia de banco)
- Erro:
ARCHITECTURE.mddiz "banco: PostgreSQL" masDATA_MODEL.mddiz "banco: MySQL" - Warning:
REQUIREMENTS.mddiz campo X é "obrigatório" masAPI_CONTRACTS.mddiz "opcional" - Warning:
TEST_STRATEGY.mdlista funcionalidade Y masREQUIREMENTS.mdnão menciona Y
4. Placeholders Não Preenchidos
Busca por marcadores de placeholder que ficaram na versão final.
Padrões buscados:
-
TODO,FIXME,XXX,HACK -
<descrição>,<nome>,<data>,<valor> -
[NÃO IMPLEMENTADO],[PENDENTE],[A DEFINIR] -
{{variavel}}(exceto em templates legais que usam Mustache) -
PLACEHOLDER,CHANGEME,LOREM -
Erro:
API_CONTRACTS.mdcontém<descrição do endpoint>na linha 45 -
Warning:
UI_SPEC.mdcontémTODO: definir validaçãona linha 120
5. Estrutura/Template Desviado
Verifica se os artefatos seguem a estrutura esperada (front matter + seções obrigatórias).
Para cada tipo de artefato, verifique:
| Artefato | Front Matter | Seções Obrigatórias |
|---|---|---|
| REQUIREMENTS.md | ✅ | §1 Visão Geral, §6 Regras de Negócio, §8 Pendências |
| DATA_MODEL.md | ✅ | Tabelas, Colunas, Relacionamentos |
| API_CONTRACTS.md | ✅ | Endpoints, Métodos, Request/Response |
| UI_SPEC.md | ✅ | Telas, Componentes, Validações |
| ARCHITECTURE.md | ✅ | Stack, Decisões, Padrões |
| DECISIONS.md | ✅ | DEC-XXX entries |
| TEST_STRATEGY.md | ✅ | Níveis, Ferramentas, Cenários |
| TRACEABILITY.md | ✅ | Matriz RN → Artefatos |
- Warning:
DATA_MODEL.mdnão tem front matter YAML - Warning:
UI_SPEC.mdnão tem seção "Validações"
6. IDs Inconsistentes
Verifica se IDs usados em um artefato são consistentes com o formato esperado.
-
RN-XXX deve ser numérico de 3 dígitos (RN-001, não RN-1 ou RN-0001)
-
PEND-XXX deve ser numérico de 3 dígitos
-
DEC-XXX deve ser numérico de 3 dígitos
-
KE-XXX deve ser numérico de 3 dígitos
-
CR-XXX deve ser numérico de 3 dígitos
-
Erro:
REQUIREMENTS.mdusaRN-1em vez deRN-001 -
Warning:
TRACEABILITY.mdreferenciaPEND-7em vez dePEND-007
7. Artefatos com Conteúdo Mínimo
Detecta artefatos que existem mas têm conteúdo insuficiente (possivelmente gerados mas não preenchidos).
Critérios:
-
Arquivo com menos de 10 linhas (excluindo front matter)
-
Arquivo com apenas front matter e nenhum conteúdo
-
Arquivo com seções todas vazias
-
Warning:
specs/SECURITY.mdtem apenas 5 linhas (front matter + título) -
Warning:
quality/TEST_STRATEGY.mdtem front matter mas nenhuma seção implementada
8. Links Internos Inválidos
Se os artefatos contêm links markdown para outros arquivos (formato [texto](caminho)),
verifique se os caminhos apontam para arquivos existentes.
- Erro:
howto/configuracao.mdcontém[ver modelo](../specs/DATA_MODEL.md)masspecs/DATA_MODEL.mdnão existe - Warning:
INDEX.mdcontém[DECISIONS](DECISIONS.md)usando caminho relativo que pode quebrar dependendo do renderer
9. Registry.yaml vs Views (drift detection)
Se o arquivo registry.yaml existir na raiz da config do OpenCode, valide
que as views geradas (ARCHITECTURE.md, tabelas de subagents dos primary agents)
estão sincronizadas com o manifesto.
Método:
- Leia
registry.yamle extraia a lista de componentes (primary_agents, subagents, skills) e suas relações - Compare com o conteúdo de
ARCHITECTURE.mddentro dos marcadores<!-- BEGIN_REGISTRY -->/<!-- END_REGISTRY --> - Drift detection:
- Componente no registry mas não na view: erro — re-renderizar
- Componente na view mas não no registry: erro — view manual obsoleta
- Relação divergente (ex: subagent delegado diferente): warning
- Skill sem arquivo: para cada skill no registry, verifique se
skills/<id>/SKILL.mdexiste. Se não → erro - Subagent sem arquivo: para cada subagent no registry, verifique se
agents/<id>.mdexiste. Se não → erro - Ownership inválido: para cada subagent, verifique se
ownerexiste emprimary_agents, seavailable_tocontém apenas primaries existentes e seregistered_by(quando presente) coincide comowner. - Delegação indisponível: para cada primary, verifique se todo subagent
em
delegatesaparece noavailable_tocorrespondente.
Severidade: error (bloqueante para o builder — registry inconsistente gera nós órfãos na próxima inferência)
Ação corretiva sugerida: executar rdd-registry-render para
regenerar as views, ou corrigir registry.yaml manualmente se o arquivo
físico foi deletado.
Template — WIKI_LINT_<timestamp>.md
---
project: <NOME_DO_MODULO>
module: wiki-lint
audience: [qualidade, governanca]
status: draft
generated_at: "YYYY-MM-DDTHH:mm:ssZ"
artifacts_scanned: N
---
# Wiki Lint — <nome-do-modulo>
> **Gerado em:** DD/MM/AAAA HH:MM
> **Artefatos analisados:** N
> **Resultado Geral:** ✅ Limpo | ⚠️ Warnings | ❌ Erros encontrados
---
## Resumo
| Categoria | Erros | Warnings | Info |
|-----------|-------|----------|------|
| 1. Artefatos Órfãos | — | N | N |
| 2. Referências Quebradas | N | N | — |
| 3. Contradições | N | N | — |
| 4. Placeholders | N | N | — |
| 5. Estrutura/Template | — | N | — |
| 6. IDs Inconsistentes | N | N | — |
| 7. Conteúdo Mínimo | — | N | — |
| 8. Links Inválidos | N | N | — |
| **Total** | **N** | **N** | **N** |
---
## 1. Artefatos Órfãos
| Artefato | Localização | Observação |
|----------|-------------|------------|
<ou "✅ Nenhum artefato órfão">
---
## 2. Referências Cruzadas Quebradas
| Artefato Origem | Referência | Artefato Esperado | Existe? |
|----------------|-----------|-------------------|---------|
<ou "✅ Todas as referências são válidas">
---
## 3. Contradições entre Seções
### <Artefato A> vs <Artefato B>
**<Artefato A>:** <afirmação encontrada>
**<Artefato B>:** <afirmação conflitante>
**Tema:** <descrição do tema conflitante>
<ou "✅ Nenhuma contradição detectada">
---
## 4. Placeholders Não Preenchidos
| Artefato | Linha | Placeholder | Contexto |
|----------|-------|-------------|----------|
<ou "✅ Nenhum placeholder encontrado">
---
## 5. Estrutura/Template
| Artefato | Front Matter | Seções Obrigatórias | Status |
|----------|-------------|---------------------|--------|
<ou "✅ Todos os artefatos seguem o template esperado">
---
## 6. IDs Inconsistentes
| Artefato | ID Encontrado | ID Esperado | Linha |
|----------|--------------|-------------|-------|
<ou "✅ Todos os IDs seguem o padrão">
---
## 7. Conteúdo Mínimo
| Artefato | Linhas | Observação |
|----------|--------|------------|
<ou "✅ Todos os artefatos têm conteúdo suficiente">
---
## 8. Links Internos Inválidos
| Artefato Origem | Link | Caminho | Existe? |
|----------------|------|---------|---------|
<ou "✅ Todos os links são válidos">
---
## Recomendações
| Prioridade | Ação | Artefato |
|-----------|------|----------|
| ❌ Alta | <ação> | <artefato> |
| ⚠️ Média | <ação> | <artefato> |
| ℹ️ Baixa | <ação> | <artefato> |
Casos de Borda
- Módulo com 1 único artefato: execute apenas as verificações aplicáveis (placeholders, estrutura, conteúdo mínimo). Órfãos e referências cruzadas não se aplicam com apenas 1 artefato.
- Módulo pré-IMP-011 (sem subpastas): verifique artefatos na raiz. No relatório, note que o módulo ainda não foi migrado.
- Artefatos muito grandes (>5000 linhas): execute as verificações em lotes por seção para manter performance.
- Contradição ambígua: quando a detecção automática não for conclusiva, marque como "⚠️ Revisão humana recomendada" em vez de classificar como erro.
- Artefatos legais com Mustache: os templates legais (TERMO_DE_USO,
POLITICA_DE_PRIVACIDADE) usam
{{placeholder}}intencionalmente — exclua-os da verificação de placeholders. - Relatório anterior existe: não sobrescreva — gere um novo com timestamp diferente (permite diff entre execuções).
04 同仓库更多 Skills
rdd-vps-troubleshoot
Diagnóstico guiado por sintoma para VPS da organização já configurada — container unhealthy / healthcheck expirando, GHCR denied/unauthorized no pull, git "could not read Username for 'https://github.com'", GitHub Actions (appleboy/ssh-action) falhando SSH (handshake failed, ParsePrivateKey), services systemd duplicados do cloudflared em activating (auto-restart), requisições caindo no servidor errado (tunnel compartilhado), porta ocupada, logs (journalctl / docker logs), conectividade (curl local vs público, ss, nc) e banco vazio / migrations não aplicadas. Base de conhecimento: runbook.md nesta pasta (sintomas genéricos de deploy em VPS; lições de produção da organização no pack `rules/<pack-da-organizacao>.md` — IMP-105). Modo guiado — sugere comandos com explicação; o operador executa na VPS. Use quando o usuário reportar "container unhealthy", "deploy falhou", "ssh action erro", "ghcr denied", "tunnel não responde", "banco vazio", "sem tabelas", "service duplicado", "vps com problema" ou pedir troubleshooting de deploy.
rdd-vps-setup
Wizard guiado de setup de VPS nova (OS do perfil — ex.: Amazon Linux) para hospedar uma API — atualização do sistema, Docker + Compose + buildx, permissões de arquivos, autenticação no registry do perfil (ex.: ghcr.io), git via SSH (deploy keys), chave SSH dedicada do GitHub Actions (appleboy/ssh-action), tunnel Cloudflare EXCLUSIVO por servidor + route DNS (domínio do perfil), tunnels como serviço systemd (autostart), logging do cloudflared com rotação, pipeline completo de deploy (push main → build → registry → ssh-action → deploy.sh) e backup automatizado (RClone + cronie + canal de alerta do perfil). Base de conhecimento validada: pack da organização em `rules/<pack-da-organizacao>.md` §infra-vps-setup (IMP-105). Modo guiado — sugere comandos com explicação; o operador executa na VPS. Use quando o usuário pedir "setup de VPS", "configurar VPS nova", "preparar servidor para deploy", "tunnel cloudflare", "ghcr", "deploy key", "backup rclone", "docker compose na vps" ou "pipeline de deploy na VPS".
rdd-validate
Percorre o grafo de documentos do projeto e valida integridade: RN sem downstream esperado, ID quebrado, CR aprovado sem reflexo. Gera relatório VALIDATION_REPORT.md. Suporta flag --fix para auto-correção. Use quando o usuário pedir "validar integridade", "checar a DAG", "validar referências cruzadas" ou "validação do módulo".
rdd-ui-spec
Gera UI_SPEC.md a partir das RNs em REQUIREMENTS.md. Descreve telas, componentes, fluxos de navegação, validações de frontend e regras de exibição condicional. Use quando o usuário pedir "especificação de UI", "spec de telas", "layout de formulários" ou "fluxo de navegação".
rdd-ui-capture
Captura evidência visual em runtime do sistema legado para migração (golden master de UI) via MCP Playwright — screenshots por rota/estado, requisições de rede observadas e erros de console, gravados em reverse/ui/ com manifesto reverse/UI_CAPTURE.md e candidatas visuais na fila reverse/CANDIDATES.md. Complemento runtime da engenharia reversa estática (IMP-144). Use quando o usuário pedir "captura visual", "golden master de UI", "screenshots do legado", "captura de UI" ou "ui capture".
rdd-typesafe-ai
Build AI-powered software with TypeSafe: small units of AI intelligence you can use like programming primitives. Its System One models, including Jev, turn natural language and application state into typed judgments and probabilities that code can combine. Use when a feature needs programmable common sense, when brainstorming what AI could make possible in an app, or when an LLM prompt-and-parse step could become a structured decision. Applications include routing, ranking, extraction, verification, and interactive experiences; these are starting points, not the limits. Read live docs and cookbooks to find useful patterns and discover new combinations.