knowledge

/knowledge — federa busca + lifecycle em docs .md

Voce eh um "bibliotecario" pros docs .md do usuario. Tres fontes:

1. ~/Desktop/knowledge/ — cross-cutting docs (ideias, playbooks, audits, learnings)
2. Repo do projeto atual — find . -name "*.md" -not -path "*/node_modules/*" (cwd atual)
3. Memory do Claude — ~/.claude/projects/<projeto>/memory/ se aplicavel

Subcomandos

$1 define o que fazer. Se vazio, default eh index.

/knowledge index (default)

Imprime visao organizada de tudo. Format:

Knowledge base summary
======================

CENTRAL (~/Desktop/knowledge/)
- ideas/ (N docs, X stale)
- playbooks/ (N docs)
- audits/ (N docs, X stale)
- learnings/ (N docs)
- archive/ (N docs)

PROJECT (cwd)
- doc1.md (last_review: 2026-05-17, status: active)
- doc2.md (last_review: 2026-04-12, STALE)
...

MEMORY (~/.claude/projects/.../memory)
- memory1.md (type: feedback)
- memory2.md (type: project)

CONTENT DRAFTS
- 2026-05-17-claude-mcp-bigquery-ga4/ (4 platforms, status: drafted)
- ...

Format limpo, ordenado, status visiveis. Maximo ~50 linhas — se passar, agrupa por tag.

/knowledge stale [days]

Lista docs onde last_review > N dias atras (default 60).

Para cada .md em todas as fontes:

1. Le frontmatter, extrai last_review (ou usa file mtime se frontmatter ausente)
2. Calcula dias desde ultima review
3. Se > threshold, inclui na lista
4. Ordena por staleness (mais velho primeiro)

Output:

Docs stale (last_review > 60 dias):

1. ~/Desktop/knowledge/audits/ga4-audit-2025-q4.md
   last_review: 2025-11-20 (178 dias atras)
   tags: [analytics, ga4]
   sugestao: re-validar com dado atual ou archive

2. /Users/.../mysite/PORTFOLIO_STRUCTURE_RESEARCH.md
   last_review: ausente, mtime: 2026-02-10 (96 dias atras)
   sugestao: adicionar frontmatter ou archive

/knowledge drafts

Lista content drafts nao publicados.

Scaneia <project>/content/drafts/ no repo atual. Pra cada subdir:

• Le os 4 .md (linkedin/twitter/instagram/article)
• Checa se tem checklist [x] indicando posted ou se ainda esta [ ]
• Lista grouped por status

Output:

Content drafts:

UNPOSTED (todas checkboxes pendentes)
- 2026-05-17-claude-mcp-bigquery-ga4/ (4 platforms)
- 2026-05-17-site-audit-bot-discovery/ (4 platforms)
- 2026-05-17-claude-content-machine/ (4 platforms)

PARTIALLY POSTED
(nenhum)

POSTED (>=1 checkbox checked)
(nenhum)

/knowledge related <topico>

Faz grep semântico atraves de todas as fontes. Procura <topico> em:

• Frontmatter tags
• Titulos H1/H2
• Body content (ranqueado por densidade)

Retorna lista ordenada por relevancia (max 10).

Output:

Docs relacionados a "analytics":

[CENTRAL/audits] ga4-audit-2025-q4.md (5 hits)
[PROJECT] ENGAGEMENT_AUDIT.md (12 hits, recent)
[PROJECT] ANALYTICS_CLEANUP.md (8 hits, recent)
[PROJECT] ANALYTICS_DB_SETUP.md (6 hits, recent)
[PROJECT] MCP_ANALYTICS_SETUP.md (4 hits, recent)
[MEMORY] skill-content.md (1 hit)

Se 0 resultados, sugere criar novo: "Nenhum doc sobre 'X'. Quer criar um com /knowledge new?"

/knowledge suggest

Modo proativo: analisa o que foi trabalhado na sessao atual (git diff recente, commits, arquivos modificados) e sugere docs existentes relacionados.

Logica:

1. Identifica topicos da sessao (commit messages, file paths, conversation context)
2. Roda /knowledge related internamente pra cada topico
3. Apresenta docs candidatos pra:
   • Atualizar (mesmo topico, recent)
   • Conectar (topico adjacente, vale linkar)
   • Substituir (doc obsoleto sobre mesmo topico)

Output (compacto):

Trabalho da sessao toca em: [analytics, ga4, mcp]

Docs candidatos:
- ENGAGEMENT_AUDIT.md → atualizar com numbers novos
- MCP_ANALYTICS_SETUP.md → linkar do novo doc se criar
- ~/Desktop/knowledge/playbooks/ga4-audit.md → criar este (ainda nao existe, mas devia)

Quer que eu abra algum ou crie o novo playbook?

Esse modo eh particularmente util ao final de uma sessao tecnica — dispara junto com a sugestao de /content (skill content) se aplicavel.

/knowledge new <type> <title>

Cria novo doc com frontmatter padronizado, no lugar certo.

Args:

• $1 (subcommand): new
• $2 (type): idea | playbook | audit | learning | doc
• $3+ (title): titulo livre, sera kebab-case'd pro filename

Logica:

1. Determine target dir baseado no type:
   • idea → ~/Desktop/knowledge/ideas/
   • playbook → ~/Desktop/knowledge/playbooks/
   • audit → ~/Desktop/knowledge/audits/
   • learning → ~/Desktop/knowledge/learnings/
   • doc → repo atual (root) — pra docs project-specific
2. Kebab-case do title + date prefix pra audits: YYYY-MM-DD-<title>.md
3. Cria com frontmatter pre-preenchido:

---
type: <type>
status: active
tags: []
created: 2026-05-17
last_review: 2026-05-17
priority: medium
related: []
---

# <Title>

[content goes here]

4. Abre no editor padrão (code ou nvim baseado em $EDITOR) ou apenas reporta o path criado

5. Auto-commit (so quando criar em ~/Desktop/knowledge/):

cd ~/Desktop/knowledge
git add <novo-arquivo>
git commit -m "Add <type>/<title>: created via /knowledge new"
git push

Falhas devem ser reportadas mas nao bloquear (ex: sem network, conflito merge). Se ocorrer, mostra:

WARN: auto-commit falhou ([erro]). Arquivo criado em <path>, mas nao versionado ainda.
Pra resolver manualmente: cd ~/Desktop/knowledge && git status

6. Mensagem final pro usuario (sempre, mesmo se commit deu certo):

Doc criado: <path>
Commitado e pushado pra origin/main (commit <sha>).

LEMBRE-SE: revisar e ajustar o conteudo. Frontmatter foi pre-preenchido com defaults — voce
provavelmente quer ajustar:
- tags: agora vazia, adiciona 2-3 tags
- related: vincular a outros docs se aplicavel
- priority: default eh medium

Depois de editar: cd ~/Desktop/knowledge && git add -A && git commit -m "..." && git push

NAO auto-commitar quando type=doc cria em repo do projeto atual (nao central) — esse fica na responsabilidade do usuario porque o repo do projeto tem seu proprio fluxo (ex: PRs, branches).

/knowledge migrate

Helper raro: percorre .md files existentes (em ~/Desktop/knowledge/ ou repo), detecta ausencia de frontmatter, e oferece pra adicionar boilerplate.

NAO modifica arquivos sem confirmacao. Apresenta lista, espera "yes" pra cada um.

Regras criticas

• NAO modifica arquivos sem confirmacao explicita — exceto quando o usuario invoca /knowledge new
• NAO publica nada — eh so descoberta, organizacao, sugestao
• Respeita git — se um doc esta versionado num repo, considera last commit como last_review se frontmatter ausente
• Project-aware — sempre detecta cwd e scaneia o projeto atual, nao so o central
• Performance — pra repos grandes (>200 .md), considera limit ou paginacao
• Output compacto — preferir tabelas/listas curtas a textao corrido

Convencao de frontmatter (obrigatoria pra docs novos)

---
type: idea | playbook | audit | learning | doc | draft
status: active | stale | archived
tags: []  # lower-case, kebab-case, max 5
created: YYYY-MM-DD
last_review: YYYY-MM-DD
priority: high | medium | low
related: []  # paths absolutos ou relativos pra outros .md
---

Quando o usuario criar doc via /knowledge new, frontmatter eh pre-preenchido. Quando ele criar manualmente (Write tool, $EDITOR), eu (Claude) devo sugerir adicionar frontmatter se faltar.

Quando NAO usar essa skill

• Pra ler/editar UM doc especifico que ja foi mencionado → use Read/Edit direto
• Pra criar doc novo num lugar especifico fora da convencao → use Write
• Pra git/version control de docs → use git direto
• Pra busca lexical simples ("achar string X") → use grep direto

A skill eh pra organizar, descobrir, e dar lifecycle a uma colecao de docs — nao pra micro-edicoes.

Integracao com /content

Se a skill content ja existe (ver ~/.claude/skills/content/SKILL.md), /knowledge suggest deve considerar:

• Drafts em content/drafts/ como output da skill content
• Sugerir "rodar /content" se trabalho recente bate como content-worthy AND nao tem rascunho ainda