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

Abierto
#5,718 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Python
Estrellas
36.2k
Forks
4.1k
Métricas de merge de PR
Métricas de PR pendientes

Descripción

## 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.

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.