anthropics / anthropics/claude-plugins-official

claude-md-improver: audit compares docs against the checked-out worktree without fixing a baseline ref — stale branches yield silently wrong reports

Aberta
#5,718 0 comentários 0 reações 0 responsáveis Ver no GitHub
Linguagem predominante
Python
Estrelas
36.3k
Forks
4.1k
Merge médio
2d 14h
PRs com merge (30d)
539

Descrição

## Summary

Phase 1 discovery (`find . -name "CLAUDE.md" ...`) and the Phase 2 "Currency" criterion both treat **the checked-out worktree as the codebase reality** to audit documentation claims against. When the worktree is not representative — an isolated docs-only branch, a stale clone, a git worktree pinned to an old ref — every file still reads fine, every check still runs, and only the conclusions are wrong. There is no error signal.

## What happened (field report)

Auditing a team CLAUDE.md from a docs-only branch that was **3,195 commits behind the mainline**, the skill produced three false findings of the form "documented dependency X is not installed" (X existed on the mainline; the audit read the stale `package.json`). The report was about to ship as fact until a human noticed the branch.

## Proposal

1. Add a **baseline-ref confirmation step** to Phase 1: for each discovered instruction file, record (a) which ref the document lives on and (b) which ref the code sample used for verification lives on.
2. When the worktree is the sample, measure drift first: `git rev-list --left-right --count HEAD...` — if `behind` is significant, switch the code sample to the mainline ref (or say so).
3. Print the baseline in the report header: `Compared against: (, )` — so a reader can tell *which reality* the scores refer to.

## Relationship to existing issues

Distinct from #1476 (rubric assumes project-context) and #633 (Glob vs find): both are about *how* discovery/scoring runs; this is about *which ref* the audit's "reality" sample comes from. Complements either.

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Direção de pesquisa

No file or test path is named. Start by locating the claude-md-improver entry point, Phase 1 discovery, and the Phase 2 Currency criterion; trace how the checked-out worktree is selected and how the report header is built. Done means the audit confirms or reports its baseline ref, measures relevant drift, and prints the ref, SHA, and date used for comparison.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
git
Domínio
documentation, tooling
Tipo de issue
Funcionalidade
Dificuldade
4/5
Tempo estimado
3-5 dias
Status de atividade
Ativa
Clareza
Razoavelmente clara
Facilidade para iniciantes
52/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.