plain-language

pl-01..pl-33 ルールカタログに照らしてプロジェクト内の文章を監査し、検証済みの書き換え案を含む指摘ドキュメントを1つ作成します。このスキルはレビュー対象ファイルを読み取り専用で扱い、修正は提案するだけで、ファイル自体は編集しません。状態ファイルは作業の再開に使うもので、人によるレビュー用ではありません。

ユーザーに進捗を示すため、ホストの todo ツールで以下の4つのフェーズを再現してください。

必須事項（最初に読む）

• レビュー対象ファイルは絶対に変更しないでください。 指摘と書き換え案は、計画ドキュメントにのみ記載します。
• 明示的な呼び出しがある場合のみ実行します。 このスキルはユーザーが /plain-language を呼び出した場合にのみ実行し、自動で有効化してはいけません。
• すべての指摘を FALSIFIABLE（反証可能）または OPINION（意見）に分類します。 FALSIFIABLE は Grep で確認できる特定の行にある正確な文章を引用する指摘、OPINION はトーン、対象読者への適合性、曖昧さなど、解釈に左右される指摘です。
• FALSIFIABLE の引用は、下書きに含める前にすべて Grep で検証してください。 引用元が見つからない場合、その指摘は削除し、幻覚による指摘として数えます。
• 出力ファイルは1つだけです。 統合された計画をユーザー向けの唯一の成果物とし、実行終了時の返信ではそのパスのみを伝え、状態ファイルや中間成果物については触れません。

対象範囲

• レビュー対象： .md、.mdx、.markdown、.txt、.rst、.adoc、.org、.wiki ファイル内の文章、UI 文字列、エラーメッセージ。
• 対象外： フェンス付きコードブロックやバッククォート内のコード、変数名、インポート文、設定値、URL、ファイルパス。
• 技術用語を維持： 正確さを損なわずにより簡単な言い換えができる場合に限り、専門用語を指摘します。
• 除外対象： ドットディレクトリ、node_modules/、vendor/、dist/、build/、coverage/、__pycache__/、target/、venv/、.gitignore に記載されたすべて。
• スキル自身のディレクトリは絶対にスキャンしないでください。 常にユーザーのプロジェクトルートから作業します。引数なしの /plain-language は、プロジェクトルートにある対象範囲内の文章をすべてレビューします。プロジェクトルートが曖昧な場合、またはユーザーが指定したファイルが存在しない場合に限り、確認してください。
• 平易な言葉のチェック対象は読みやすさです。ドキュメントとコードの正確性は対象外であり、両者のずれの検出も行いません。

状態ファイル

作業状態は .agents/local/state/plain-language-YYYY-MM-DD.md に保存します（今日の日付を使用）。Git から無視され、ユーザーには表示されず、コミットもされません。

開始時：

1. .agents/local/state/ が存在しない場合は作成します。
2. .agents/local/state/plain-language-*.md を Glob で検索します。最新のファイルに未完了の項目がある場合は、そのファイルを使って作業を再開します。今日の日付のファイルが存在し、完了している場合は ...-YYYY-MM-DD-2.md を作成します（必要に応じて -3.md 以降も同様）。それ以外の場合は今日の日付のファイルを作成します。ファイルを削除すると、新規の実行が始まります。

形式 — バッチごとにまとめた Markdown のチェックリスト：

# Plain Language — 2026-07-17

## Batch 1
- [ ] README.md
- [ ] docs/setup.md

## Batch 2
- [ ] docs/api.md

## Findings draft
- [pl-09] Use active voice — docs/setup.md:42 — sev:high — grep:`is initialized by` — "The database is initialized by the setup script" → "The setup script initializes the database"

このファイルへの書き込みはオーケストレーターのみが行います。項目にチェックを付け、各ワーカーから結果が返るたびに ## Findings draft の下へ指摘を追記してください。ワーカーは状態ファイルを編集してはいけません。フェーズ3では状態ファイル内の下書きをレビューするため、実行を再開しても既存の指摘は保持されます。

フェーズ1 — 検出（機械的に実施。サブエージェントは使用しない）

Glob またはシェルのリスティングをインラインで使い、対象範囲内の文章ファイルを列挙します。ツールがインストールされていない場合は、rg --files を優先し、次に fd --type f、その後 find . -type f を使ってください。対象範囲の除外ルールを適用します。ファイルを3～5個ずつのバッチに分け、状態ファイルにチェックリストを記入します。要約のために作業を中断せず、そのままフェーズ2へ進んでください。

フェーズ 2 — レビュー（バッチごとに並列）

未チェックのバッチごとにワーカーサブエージェントを 1 つディスパッチします。同時実行は最大 5 つです。1 つのウェーブの Agent 呼び出しはすべて 1 つのメッセージで送信し、並列実行します。上限を超えるバッチがある場合は、ウェーブを順次実行します。ワーカーにはホストの低コストモデルのエイリアスを使用します（例：model: haiku — バージョンを固定したモデルは使用しないでください）。ワーカーはユーザーのプロジェクトルートから実行されるため、ディスパッチ前にブリーフ内の references/… パスを、このスキルのディレクトリ内の絶対パスに展開してください。

各ワーカーには次のように指示します。「あなたは、平易な言葉遣いのルールカタログ pl-* を 1 バッチ分の文章ファイルに適用するレビュー担当者です。違反を指摘し、検証済みの書き換え案を提案してください。ソースファイルを変更してはいけません。」 各ワーカーは次の手順を実行します。

1. references/rules-quick-ref.md（pl-01..pl-33 のカタログ）と references/severity-rubric.md（high/medium/low の定義）を読み込みます。必要に応じて読み込むファイル：語句の選択を判断する場合は references/word-substitutions.md、受動態がある場合は references/active-voice-guide.md、単語の置き換えではなく構成の変更が必要な書き換えの場合は references/before-and-after-examples.md。
2. 担当するバッチのファイルを読みます。バッチ内のファイルごとに個別に読み込むのではなく、Read/Grep 呼び出しを 1 ターンにまとめてください。
3. 違反ごとに、FALSIFIABLE または OPINION に分類します。FALSIFIABLE の場合は、指摘したファイルに対して正確なパターンで Grep を実行します。一致がなければ、その指摘を削除し、削除件数を数えます。
4. 各書き換え案をその場で検証します。指摘されたルールに対処し、新たな違反を持ち込まず、技術的な正確さを保ち、文脈の中で自然に読める必要があります。書き換え案を検証できない場合は、推測せず、書き換え案の代わりに [Manual review required — unverified rewrite] と記します。
5. 重大度の基準に従って重大度を割り当て、簡潔な Markdown の箇条書きで、1 行につき 1 件の指摘を返します。あわせて、削除したハルシネーションの件数も返します。

ルールカタログと重大度の基準はワーカーが読むものであり、オーケストレーターは読み込みません。

指摘の形式（OPINION の指摘には grep: を含めません）：

- [pl-09] Use active voice — docs/setup.md:42 — sev:high — grep:`is initialized by` — "The database is initialized by the setup script" → "The setup script initializes the database"
- [pl-14] Use contractions — docs/faq.md:12 — sev:low — "It is not necessary to restart" → "You don't need to restart"

ルール違反 1 件につき指摘を 1 件とし、必ず行番号を付けます。指摘がないファイルも、レビュー済みファイルの合計に含めます。

オーケストレーターは、各ワーカーの指摘をファイルごとにまとめ、行番号順に並べてドラフトに追加し、バッチのチェックボックスにチェックを入れます。ワーカーが失敗した場合は記録し、そのバッチを 1 回再ディスパッチします。再度失敗した場合は、バッチを [x] (skipped — worker failed) として、次に進みます。

フェーズ 3 — 敵対的レビュー（1 ラウンド）

ホストのデフォルトモデルでレビュー用サブエージェントを 1 つディスパッチします。完全な指摘ドラフトとリポジトリへの読み取りアクセスを渡してください。プロンプトは references/adversarial-review-prompt.md です。レビュー担当者は、引用された grep を自ら再実行し、ハルシネーションによる引用を削除し、誤検出や重大度の過大評価に異議を唱え、書き換え案を検証し、指摘漏れを示して、KEEP/REVISE/DROP の判定リストを返します。

判定をドラフトに適用します。DROPs は削除し、REVISEs は適用し、追加された指摘も取り込みます。深度は 1 です。2 回目のラウンドや、修正内容の再レビューは行いません。

フェーズ 4 — レポート

レビュー済みの指摘をもとに、references/final-plan-format.md のテンプレートを使用して統合計画を作成します（それ以前ではなく、ここで読み込みます）。パスの解決方法：

1. リポジトリのルートに docs/ がある場合 → docs/YYYY-MM-DD-plain-language-plan.md。
2. それ以外の場合 → リポジトリのルートに YYYY-MM-DD-plain-language-plan.md。

YYYY-MM-DD は date +%Y-%m-%d です。状態ファイルの日付と異なる点は、計画は常に新規作成し、再開しないことだけです。引き続き [Manual review required — ...] とタグ付けされている指摘は、計画の <manual_review> 付録に記載し、<changes> セクションには記載しません。ユーザーへの返信には、このパスのみを記載します。

避けるべき失敗モード

• コードフェンス、インラインのバッククォート、URL、ファイルパス内のテキストは、文章のように見えても指摘しないでください。
• 正確な専門用語、そのまま記載する必要のある規制関連の文言、固有名詞は指摘しないでください。
• 2つのルール違反を1件の指摘にまとめたり、行番号のない指摘を出したりしないでください。
• 作業者に、検証されていない反証可能な指摘を出させないでください。grep ゲートはファイル単位ではなく、指摘ごとに適用されます。
• 検証されていない書き換えを計画の変更リストに紛れ込ませないでください。センチネルが手動レビューに回します。
• 状態ファイル、バッチ構成、サブエージェントの詳細をユーザーに示さないでください。

完了

すべての状態ファイルのチェックボックスにチェックが入り、計画ファイルが書き込まれたら作業は完了です。計画ファイルのパスを返信してください。コミットせず、レビュー済みのファイルを変更せず、状態ファイルも削除しないでください。