From first-plan
Tracks provenance and freshness of findings in .first-plan/ with source, TTL, confidence decay, and supersedence chain. Use during discovery and refresh to prevent stale facts.
How this skill is triggered — by the user, by Claude, or both
Slash command
/fp:provenance-trackerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Cada finding em `.first-plan/` precisa de **rastreabilidade completa** - de onde veio, quando foi extraído, quão fresca é a info, quando expira, e o que substitui.
Cada finding em .first-plan/ precisa de rastreabilidade completa - de onde veio, quando foi extraído, quão fresca é a info, quando expira, e o que substitui.
Sem provenance, fatos viram lendas. Esta skill garante que toda afirmação em .first-plan/ tem cadeia auditável até o código fonte. Isso elimina:
Cada item em .first-plan/ (em qualquer arquivo) ganha campos no frontmatter ou inline (YAML/Markdown):
---
finding_id: F-<unique> # identificador estavel (ex: F-go-errors-001)
type: pattern | fact | rule | risk | feature | reuse_item
section: <section path> # ex: 02-conventions/errors
source: # de onde veio
type: code | doc | git | mcp | inferred
location: path:line # arquivo:linha
commit_sha: <SHA> # commit em que foi observado
extracted_from: # contexto adicional
- <file_path>
- <file_path>
extracted_at: 2026-05-04T22:00:00Z
extracted_by: discovery-analyst | pattern-archeologist | reconciliation-auditor | manual
confidence:
initial: 0.95 # confiança no momento da extração
current: 0.92 # após decay (calculado)
signals_used: # o que sustenta o score
- "10+ occurrences in current code"
- "documented in CLAUDE.md"
- "consistent across modules"
ttl:
days: 30 # validade default
expires_at: 2026-06-03T22:00:00Z
decay_curve: linear | step | none
lifecycle:
status: active | superseded | invalidated | expired
superseded_by: F-<id> # se substituido por finding mais novo
superseded_at: <timestamp>
invalidated_reason: <text> # se marcado invalido manualmente
---
| Type | Descrição | Onde aparece |
|---|---|---|
pattern | Convenção/padrão extraído | 02-conventions/* |
fact | Afirmação concreta sobre o projeto | qualquer seção |
rule | Regra inferida (do/dont) | 06-rationale/* |
risk | Risco identificado | 05-risks/* |
feature | Feature do projeto (Spec-Code) | 09-features/* |
reuse_item | Item reusável catalogado | 03-reuse/* |
Findings perdem confidence com o tempo se não revalidados:
| Idade | Confidence multiplier |
|---|---|
| < 7 dias | 1.00 (sem decay) |
| 7-30 dias | 0.95 |
| 30-90 dias | 0.85 |
| 90-180 dias | 0.70 |
| > 180 dias | 0.50 |
Fórmula:
current_confidence = initial_confidence * age_multiplier
Confidence current é recalculada a cada /fp:status ou /fp:refresh.
Se current < 0.5, o finding é marcado como expired e movido para 08-meta/expired.md (não deletado, preservado para auditoria).
| Type | TTL default | Razão |
|---|---|---|
pattern | 30 dias | Convenções podem mudar com refator |
fact | 14 dias | Fatos sobre código mudam rápido |
rule | 60 dias | Regras são mais estáveis |
risk | 30 dias | Risco pode ser resolvido |
feature | 7 dias | Status de implementação muda muito |
reuse_item | 30 dias | Refators podem mudar API |
Usuário pode override via campo ttl.days no finding.
Quando um finding novo torna outro obsoleto:
# Finding antigo
finding_id: F-go-errors-001
lifecycle:
status: superseded
superseded_by: F-go-errors-007
superseded_at: 2026-05-15T10:30:00Z
# Finding novo
finding_id: F-go-errors-007
supersedes:
- F-go-errors-001
- F-go-errors-003
Findings superseded permanecem no arquivo (apenas marcados) por 30 dias, depois movidos para 08-meta/superseded-archive.md.
codeExtraído por leitura direta do código.
source:
type: code
location: internal/auth/jwt.go:47
commit_sha: abc1234
extracted_from:
- internal/auth/jwt.go
- internal/middleware/auth.go
docExtraído de documentação local.
source:
type: doc
location: docs/auth.md#jwt-flow
commit_sha: abc1234
gitInferido do git history.
source:
type: git
location: git log --since="30 days"
commit_sha: HEAD
extracted_from:
- "47 commits affecting internal/payment/"
mcpObtido via MCP externo.
source:
type: mcp
location: jira-mm:PROJ-456
extracted_at: 2026-05-04T22:00:00Z
inferredConclusão derivada (não diretamente observada).
source:
type: inferred
location: cross-cutting analysis
extracted_from:
- 02-conventions/errors.md (uses errors.Wrap)
- 02-conventions/logging.md (uses slog)
inference: "logging+errors pattern indicates structured observability stack"
Sempre incluir todos os campos obrigatórios do schema. Se não souber commit_sha, usar git rev-parse HEAD no momento da extração.
Quando /fp:refresh reanalizá área:
extracted_at: 2026-05-04T22:00:00Z # mantém original
revalidated_at: 2026-05-15T10:00:00Z # novo campo
ttl:
expires_at: 2026-06-14T10:00:00Z # estendido
Usuário pode marcar finding errado:
lifecycle:
status: invalidated
invalidated_at: 2026-05-15T10:00:00Z
invalidated_reason: "Padrão anterior estava errado - verificar com PR #42"
Quando finding novo emerge que substitui antigo, marcar ambos com cross-reference.
lifecycle.status e confidence.current (não usar superseded/expired/invalidated)confidence.current e marca expired/superseded conforme regrasSchema aplicado em todos os arquivos do .first-plan/ que contêm findings. Para arquivos como 02-conventions/errors.md que tinham padrões ad-hoc, agora cada padrão é uma entrada YAML com schema completo.
Exemplo 02-conventions/errors.md v2.0:
---
section: conventions/errors
generated_at: 2026-05-04T22:00:00Z
findings_count: 3
active: 3
superseded: 0
expired: 0
average_confidence_initial: 0.95
average_confidence_current: 0.92
---
# Convenções de errors
## F-errors-001 - Wrapping com pkg/errors
```yaml
finding_id: F-errors-001
type: pattern
source:
type: code
location: internal/service/user.go:47
commit_sha: abc1234
extracted_at: 2026-05-04T22:00:00Z
extracted_by: pattern-archeologist
confidence:
initial: 0.95
current: 0.92
signals_used:
- "12 occurrences"
- "consistent across all services"
ttl:
days: 30
expires_at: 2026-06-03T22:00:00Z
lifecycle:
status: active
Padrão: ```go return errors.Wrap(err, "failed to save user") ```
Visto em: internal/service/user.go:47, internal/service/order.go:89, ...
npx claudepluginhub vynazevedo/first-plan --plugin fpAudits CLAUDE.md, rules, and memory files for stale references, orphaned content, contradictions, duplicates, misplacement, budget overruns, and unenforced claims.
Cross-references structured review findings against an implementation plan, classifies each finding into an action category, applies concrete edits, and produces a traceability summary.
Enhances existing plans by deploying parallel research agents per section to add best practices, optimizations, UI/UX improvements, edge cases, and real-world examples.