docs-audit

Docs Freshness Audit

痛点：代码改了 40 天了，文档还停在 3 个月前。没人专门盯，自然就 drift。这个 skill 每周扫一次、给出有证据的清单，让技术写作不用手动翻 git blame。

何时触发

• cron 每周跑一次
• 用户说："扫一下文档哪些过时了"、"查 docs freshness"
• PR 改了 src/ 但没改 docs/ 时触发（需要 hook 配合，本 skill 不负责触发点）

输入

• 窗口：默认 30 天（--since="30 days ago"），用户可覆盖
• 源目录：默认 src/、core/、tools/、lib/ 里实际存在的
• 文档目录：默认 docs/ + README.md + CHANGELOG.md

实际检测前先用 Glob 探一下项目里实际的目录布局，不要假设。

输出

一个 markdown 报告 + 可选 GitHub issue：

.prax/reports/docs-audit-<YYYY-MM-DD>.md

不自动改文档（写作是人的事）。不删已有报告（历史归档有价值）。

工作流程

Step 1：摸底

# 列出项目里实际的源目录和文档目录
ls -d src/ core/ tools/ lib/ docs/ 2>/dev/null
find . -maxdepth 2 -name "README*.md" -not -path "./node_modules/*"

Step 2：找近期改过的源文件

git log --since="30 days ago" --name-only --pretty=format: -- <source-dirs> \
  | sort -u \
  | grep -v '^$' \
  | grep -E '\.(py|ts|tsx|js|jsx|go|rs|java|kt|md)$'

.md 也保留——文档自己也可能"过时"（比如指向已删除的文件）。

Step 3：对每个源文件查文档提及

# 对 src/auth.py，grep docs/ 和 README
SOURCE=src/auth.py
STEM=$(basename $SOURCE .py)      # auth
grep -rln "$SOURCE\|$STEM" docs/ README*.md CHANGELOG.md 2>/dev/null

四种情况分类：

场景	判定	列入报告?
源文件新增（无 history）+ 文档无提及	可能是内部实现，skip	❌
源文件改过 + 文档也改过（窗口内）	健康	❌
源文件改过 + 文档完全没提过	可能是内部模块，不是公开 API	⚠ 低优先级
源文件改过 + 文档提过但文档未改	真 drift	✅ 高优先级

Step 4：生成报告

模板：

---
generated_at: 2026-04-22T09:00:00+08:00
window: "last 30 days"
repo_head: <short sha>
stale_count: 7
---

# Docs Freshness Audit — 2026-04-22

扫描窗口：过去 30 天。发现 **7 处可能的文档过时**。

## 🔴 高优先级（文档提及 + 代码改了 + 文档没改）

### 1. `src/auth.py` ↔ `docs/authentication.md`

**证据**：

- 源文件最近 commit：

a1b2c3d 2026-04-20 feat(auth): migrate session cookies to SameSite=Strict d4e5f6g 2026-04-15 fix(auth): token refresh race

- 文档最后修改：2026-02-10（64 天前）
- 文档中仍提到：SameSite=Lax（第 45 行）

**建议**：更新 `docs/authentication.md` 的 cookie 配置段。

### 2. ...

## 🟡 低优先级（代码改了但文档没提过）

- `core/cache.py`（3 commits in window）—— 可能是内部模块，酌情是否要补文档

## 📊 统计

- 扫描源文件：124
- 窗口内改动：18
- 真 drift：7
- 可能内部：11