update-readme

README 更新ワークフロー

使用するタイミング

README の構成を見直す必要がある場合は、このスキルを使用してください。 まず Skill(sanctum:git-workspace-review) を実行して、リポジトリのコンテキストと差分を把握してください。

使用しないタイミング

• インラインドキュメントの更新：doc-updates を使用
• 一時的なレポートの統合：doc-consolidation を使用

必須の進捗項目

1. update-readme:language-audit
2. update-readme:exemplar-research
3. update-readme:outline-aligned
4. update-readme:edits-applied
5. update-readme:slop-scanned - scribe による AI マーカーの検出
6. update-readme:verification-reporting

ステップ 1 - 言語監査（update-readme:language-audit）

• pwd、git status -sb、および参照用のベースラインブランチを確認します。
• リポジトリのヒューリスティック（マニフェストファイル、ファイル数）を使って、主要な言語を特定します。
• ドキュメントに影響する副次的な言語（例：TypeScript のフロントエンドと Rust のバックエンド）を記録し、README で両方を取り上げられるようにします。
• 手法と調査結果を記録します。

検出パターンとコマンドの詳細については、modules/language-audit.md を参照してください。

ステップ 2 - 参考事例の調査（update-readme:exemplar-research）

• 主要言語と副次的な言語ごとに、Web 検索を使って質の高い README を探します（スター数、更新の新しさ、メンテナーの活動状況を基準にします）。
• 言語ごとに参考となるリポジトリを 2～3 件選び、それぞれが参考になる理由（セクションの順序、ビジュアル、クイックスタートの分かりやすさ、ガバナンスに関するメッセージ、数式の解説など）を要約します。
• 最終的な概要で明示的に参照できるよう、各参考事例の引用情報を保存します。

検索クエリのパターンと評価基準については、modules/exemplar-research.md を参照してください。

ステップ 3 - 構成の調整（update-readme:outline-aligned）

README はマニュアルではなく、索引です。 まず、プロジェクトの内容とインストール方法を示し、構成要素（プラグイン、コマンド、パッケージ）を一覧できる表を掲載します。それ以外の情報にはリンクします。

README は newcomer 向けのドキュメントです。 読者はこのプロジェクトを見たことがありません。候補となる各セクションについて、その読者が何かをインストールして実行する前に必要かどうかを判断基準にします。背景、検討した代替案、内部構造は expert 向けの情報です。これらは docs/deep-dive/<topic>.md または book/ に移し、そのページの対象読者を一行で示したリンクを README に掲載します。README を短くするために、これらを削除してはいけません。対象読者別の表と削減基準については、scribe:slop-detector モジュールの audience-targeting.md を参照してください。

異なる対象層を想定する README（すでに実行している人だけが読む内部ツールなど）では、その旨を冒頭で説明します。

2026 年にこのリポジトリのルート README を簡潔にした際、本文をそのまま掲載していた詳細を削除して book/ へのリンクに切り替えた結果、行数は 435 行から 200 行に減りました（単語数は 65% 減）。セクションごとに網羅することではなく、このような構成を目指します。

• 現在の README の見出し（rg -n '^#' README.md）を、ステップ 2 の優れた例と比較します。マーケットプレイスや CLI ツールの README（asdf-vm/asdf-plugins、ohmyzsh/ohmyzsh、ryoppippi/ccusage）は、索引としての構成になっています。導入文は約 500 語以内で、情報は一覧表にまとめ、詳細はリンク先に置いています。
• 索引にふさわしいセクションだけを残します。たとえば、一行の価値提案、インストール方法一つ、簡潔なコマンドまたは構成要素の表、短い「内容紹介」、Documentation へのリンクをまとめた単一のセクション、最後にメタデータ（要件、コントリビューション、ライセンス）です。それ以外の候補となるセクションごとに、これは README に載せるべきか、それともリンク先に置くべきかを検討します。
• 基本的にはリンク先に案内します。詳細なアーキテクチャ、FAQ、ロードマップ、変更履歴、別のインストール方法、構成要素ごとの詳細は、それぞれのページに移します。構成要素のドキュメントは各構成要素と同じ場所に置き（ハブ・アンド・スポーク型）、ルート README に重複させません。
• 情報の順序で優先度を示します。タイトルとタグライン、インストール方法、索引表、簡潔な機能概要、Documentation のリンク、最後に運用情報（要件、コントリビューション、ライセンス）の順にします。
• 内部ドキュメント（docs/、book/、specs/、commands/）を、それらへのリンクを掲載するセクションに対応づけます。README では内容を繰り返さず、詳細への導線を示します。

目安：マーケットプレイスやコレクションのルート README は、索引表を除き、おおむね本文 150～400 行に収めます。ロードマップ、FAQ、変更履歴など、時間とともに長くなるセクションは README ではなく、リンク先のページに置きます。

ステップ 4 - 編集の適用（update-readme:edits-applied）

• 新しい構成を README.md（または指定されたファイル）に直接反映します。
• Skill(leyline:markdown-formatting) の規則に従います。本文は 80 文字で折り返し（文や節の区切りを優先）、見出しの前後には空行を入れ、ATX 形式の見出しのみを使い、リストの前には空行を入れ、長い URL には参照形式のリンクを使います。
• 簡潔で根拠に基づく文章を保ち、誇張した宣伝文句は避けます。
• 本文への記載より、削除してリンクすることを優先します。ドキュメントのページと重複するセクションは削除してそのページにリンクし、時間とともに長くなるセクションは README から完全に移します。
• 比較表、機能一覧、図は、現在のリポジトリにある素材を基にする場合に限り追加します（推測に基づく内容は追加しません）。
• アルゴリズムやパフォーマンスに関する主張には、リポジトリ内のベンチマークやテスト、または文書化された数学的レビューを示します。

ステップ 4.5 - AI による低品質コンテンツの検出（update-readme:slop-scanned）

更新した README に AI 生成コンテンツの兆候がないか、Skill(scribe:slop-detector) を実行して確認します。

Scribe との統合

scribe プラグインは、AI 生成の粗雑な文章を検出します。

Skill(scribe:slop-detector) --target README.md

次の項目を検出します。

• Tier 1 の単語：delve、tapestry、comprehensive、leveraging など
• フレーズのパターン：「In today's fast-paced world」、「cannot be overstated」
• 構造上の特徴：ダッシュの過剰使用、箇条書きの多用、文の均一性
• マーケティング用語：「enterprise-ready」、「cutting-edge」、「seamless」

修正

スロップスコアが 2.0（中程度）を超えた場合は、Skill(scribe:doc-generator) の原則を適用します。

1. すべての主張を具体的な情報で裏付けます
2. 形式的な書き出しや締めくくりを削除します
3. 形容詞よりも、数値、コマンド、ファイル名を使います
4. 箇条書きと説明文のバランスを取ります
5. 執筆者の視点（トレードオフ、理由）を示します

大幅な修正が必要な場合は、次を使用します。

Agent(scribe:doc-editor) --target README.md

ステップ 5 - 検証と報告（update-readme:verification-reporting）

• 更新した README を読み直し、明瞭さ、アクセシビリティ（セクションの長さ、箇条書きのバランス）、リンクの正確性を確認します。
• git diff README.md（または編集したファイル）を実行し、最終報告用の抜粋を取得します。
• 検出した言語、代表的な参照元（引用付き）、主な構成上の決定事項、今後の TODO（例：バッジの追加、図のアップロード）を要約します。

完了条件

• すべての進捗項目が完了している。
• README がインデックス形式になっている：導入文は推奨の範囲内（およそ 150～400 行に単位テーブルを加えた程度）で、インストール方法が 1 つあり、単位／コマンドの一覧表が一目で確認できる。
• README のセクションが book/ または docs/ のページと重複していない。詳細はインラインで記述せず、リンクで示す（rg -n '^#' README.md の各見出しが、インデックスに含める価値のあるセクションに対応している）。
• README が初心者向けになっているか、導入部で対象とする層を明記している。
• 対象層に合わないために削除したコンテンツは、ゴミ箱ではなくリンク先のページ（docs/deep-dive/ または book/）に移されている。
• README が内部ドキュメントと外部の代表例を引用付きで参照している。
• 今後のレビュー担当者が手順を再現できるよう、調査メモとコマンドの参照先が記録されている。

トラブルシューティング

よくある問題

ドキュメントが同期していない make docs-sync-check を実行して、機能のドキュメントがプラグインの登録内容と引き続き一致していることを確認します。

ビルドに失敗する 必要な依存関係がすべてインストールされていることを確認します。

リンク切れ ドキュメントファイル内の相対パスを確認します。