documentation-hygiene

id	doc-hygiene
name	Documentation Hygiene ドキュメント衛生
description	AGENTS.md などの恒久ドキュメントに一過性のタスクログが混入していないか、SOP / decision / log / learned の役割が混同されていないか、公開物（README / docs / 記事）に内部メモ・ローカルパス・AI 会話断片が残っていないかを差分で検出する
version	0.1.0
category	midstream
phase	midstream
applyTo	["**/*.md","**/*.mdx"]
tags	["documentation","hygiene","maintainability","midstream"]
severity	major
inputContext	["diff"]
outputKind	["findings","questions"]
modelHint	balanced
dependencies	["code_search"]

Pattern declaration

Primary pattern: Reviewer Secondary patterns: Inversion Why: ドキュメントの役割汚染・内部メモ混入はパターン的に拾える部分が多いが、恒久 SOP と一過性ログのどちらなのかという文書の意図の判断が要る。ドキュメント差分を含まない変更では実行を止めるゲートが必要。

Goal / 目的

• 恒久ドキュメント（AGENTS.md / SOP / ガイド）に、一過性のタスクログ・特定 PR 固有の作業記録が混入していないかを検出する。
• SOP / decision / log / learned の役割が混同されていないか（手順書に決定記録や日次ログを混ぜるなど）を検出する。
• 公開物（README / docs / 記事）に、内部メモ・ローカルパス・AI との会話断片・デバッグ出力が残っていないかを検出する。

Non-goals / 扱わないこと

• ドキュメントと実装の整合性（river-review-docs ルーターの領域）。
• 日本語の文体・textlint 的な体裁（lint の領域）。
• 翻訳パリティ（ja/en の対応漏れは docs 系の別観点）。
• 記事そのものの技術的正しさや SEO（article-reviewer の領域）。

Pre-execution Gate / 実行前ゲート

このスキルは以下の条件がすべて満たされない限り NO_REVIEW を返す。

• 差分にドキュメントファイル（*.md / *.mdx / AGENTS.md など、恒久ドキュメントまたは公開物）の追加・変更が含まれている
• inputContext に diff が含まれ、code_search（grep）が利用可能である

ゲート不成立時の出力: NO_REVIEW: doc-hygiene — ドキュメントの変更が検出されない

False-positive guards / 抑制条件

• 一過性ログを意図的に置く場所（CHANGELOG.md / docs/**/retrospectives/** / _docs/decisions/** / 日付付きログファイル）への追記は、その役割に沿う限り指摘しない。
• 手順書内のコマンド例・出力例として意図的に引用されたログは指摘しない（地の文に紛れ込んだ作業ログのみ対象）。
• ローカルパスでも、汎用的な例示（/path/to/...、~/project）は指摘しない。実在の個人パス（/Users/<name>/、/home/<name>/、C:\Users\<name>\）のみ対象。
• 内部向けと明記されたドキュメント（先頭に「内部資料」等の宣言がある）への内部メモは、公開物でない限り指摘しない。
• リンクの絶対/相対はリンク元の配布文脈で正誤が逆転するため、一律の変換提案はしない（#1464 / #1493）。pages/（Docusaurus 公開ルート）配下から repo 内の非公開領域（skills/ / docs/ など Docusaurus で配信されないパス）への参照は、絶対 GitHub URL が正典であり、相対化すると公開サイトで 404 になる。逆に skills/ 配下（plugin バンドルに docs/ が同梱される）から docs/ への参照は相対リンクが正典（#1494）。相対化・絶対化のどちらを提案する前にも、リンク元ディレクトリの配布経路（Docusaurus 公開 or plugin バンドル同梱）を確認し、「repo 内リンクは常に相対化すべき」という一律ルールを適用しない。
• （#1464）。bare の自動リンクは GitHub の issue / PR 本文だけの仕様であり、レンダリングされた （Docusaurus / GitHub のファイルビュー）ではプレーンテキストになるため、一律で簡約の提案を禁止する。