working-text

作業テキスト

このスキルは、リポジトリ、GitHub、CI の出力、Notion、図で、同僚が作業を進めるために読むテキスト全般を対象とします。README、コメント、説明やヘルプテキスト、PR や issue、レビューへの返信、コミット本文、エージェント向けブリーフ、Mermaid の図が該当します。読者がざっと目を通すのではなく、じっくり学ぶ論文、エッセイ、本は対象外です。

読者がざっと目を通して理解するテキストです。すべての事実を、最も素早く伝わる表現で示し、段落にはどの表現でも示せない情報だけを載せます。そこに記されたパス、記号、チェック項目はすべて実在します。プローブを使えば、2 つの機械的な読み取り結果が一致します。

作業テキストは、学ぶためではなく、行動するためにざっと目を通されます。このスキルは、どこにあるものであれ、その読みやすさ、構成、事実の扱いを定めます。各成果物に何を記載すべきかは、それぞれのスキルが定めます。PR 本文や issue については /pr-and-issue-discipline スキル、AGENTS.md については /code-standards スキルが担当します。

/unslop がインストールされている場合は、残った文章に対して最後に実行します。

例

あるリポジトリの merge-gate チェックのページにある CI ガイドの一段落です。3 つのルールと 2 つの例外を、73 語で説明しています。

The judgment, whole: every needed result must be `success`, or `skipped` for a job named in `allowed-skips`. Anything else (`failure`, `cancelled`, a skip the list does not name) fails the gate, and the step summary lists every job with its result. The default workflow names `checks` alone, so a scheduled run passes on `ci` and an all-skipped run cannot pass; the release workflow names nothing, since none of its gating jobs may skip.

同じ事実を示したもの：

The judgment, whole:

| Needed result | Gate |
| --- | --- |
| `success` | passes |
| `skipped`, for a job named in `allowed-skips` | passes |
| anything else: `failure`, `cancelled`, a skip the list does not name | fails; the step summary lists every job with its result |

- **Default workflow:** `allowed-skips` names `checks` alone, so a scheduled run passes on `ci` and an all-skipped run cannot pass.
- **Release workflow:** names nothing, since none of its gating jobs may skip.

そのページを開いた読者は、文章が壁のようだと言いました。プローブもそれに同意し、その箇所を示しています。

$ bun docs-probe.mts --shape-only docs/merge-gate.md
docs-probe: 19 finding(s)
  docs/merge-gate.md:10: paragraph of 73 words; the cap is 70. Split it, or turn its facts into bullets, a table, or numbered steps
  docs/merge-gate.md:28: list item of 173 words; the cap is 70. Split it, or turn its facts into bullets, a table, or numbered steps
  docs/merge-gate.md:99: list item of 218 words; the cap is 70. Split it, or turn its facts into bullets, a table, or numbered steps

内容に合った表現形式を選ぶ

決まった形式はありません。読者が何を見なければならないかを確認し、それをひと目で示せる形式を使います。

実際のページでうまく機能した形式と、それぞれに適した内容を以下に示します。別の形式が必要なページでは、そちらを使います。

読者が確認すること	それを示すのに適した形式	効果がある理由
どの値が優先され、継承がどこで止まるか	各リーフに優先される値を示した ASCII ツリー	表では分岐を示せません
コマンドの動作	実際に取得した出力を示し、その後に最小限の説明を添える	事実は出力そのものであり、それについての文章は単なる写しです
症状が出たときの対処方法	「表示される内容」「意味」「対処方法」の3行	症状を説明するには、引用したエラーと因果関係の流れが必要ですが、表のセルでは途中で切れてしまいます
バージョン間の変更点	古い形式、新しい形式、古い形式が現在どう動作するかを示す列を含む表	4列目はルールではなく、観測可能な症状を示します
2つの状態の比較	状態マトリックスと、左側と右側が何を意味するかを説明する1行の文章	マトリックスに状態を示し、文章でその読み方を示します
コードの構成	実際のファイル名とエクスポートを記したボックスを mermaid 図で示し、それを実証するテストへのリンクで締めくくる	チェッカーが検証できるボックスは陳腐化しません
手順	矢印付きのフロー、または各ステップで何かを実行するコードブロックを1つずつ含む番号付きの手順	内容そのものが順序を示します
変更の見え方	変更前と変更後のブロック	比較することで視覚化できます
基本的な事実	事実の内容を示す太字の導入文で始まる箇条書き	読者は導入文に目を通し、必要な箇所で読み進めます

形式を変更するのは、置き換える形式よりも内容をすばやく伝えられる場合に限ります。そうでなければ形式はそのままにします。表を使うのは、項目が2つ以上の共通フィールドを持ち、読者が列ごとに比較する場合に限ります。1行1項目のリストを名前と説明の表に変えても何も得られないため、元に戻します。

単調さも壁になります。ページ全体に表や箇条書きが続くと、スプレッドシートのように読めてしまいます。内容をまとめ直す、または統合する合図として捉えます。ただし、形式を変更する場合も、上記の効果があるかどうかの基準に従います。各セクションで最も速く伝えられる形式が箇条書きなら、そのまま使います。

どの形式にも共通するルールは4つです。

• どの形式も、選択して使います。 表、箇条書き、リンク、図は、文章よりもその内容をすばやく示せるために使います。前のセクションで使われていたからという理由では使いません。判断基準は、ざっと読んだときのわかりやすさです（以下の2つの層を参照）。
• 1つの内容には1つの伝達形式を使います。 図の後にそれを説明し直す段落が続くなら、図が役割を果たせていません。図を修正するか、段落を削除します。同じ内容を表と文章、または図で重ねて伝えてはいけません。図のアクセシブルな代替テキスト（alt テキスト、またはスクリーンリーダー向けの同等の1文）は、別の伝達形式には当たりません。
• 箇条書きは、リストに使います。 箇条書きでは、リストやチェックリストの項目を示します。論理の展開は文章で書きます。すべての文を箇条書きにすると、同じ種類の内容がどれなのかわかりにくくなります。
• 決まりを守るより、内容が伝わりやすいことを優先します。 表をやめて3行形式にしたトラブルシューティングのページは、表を使ったページよりも読みやすくなりました。理由はページではなく、レビューで説明します。

流し読みする読者のために書く

このページを読む人は誰もが流し読みし、その後、1 つのセクションを詳しく読みます。どちらの読み方にも同じルールが役立ち、ページは網羅的になりすぎず、役立つだけの詳細を備えています。

2 つの層。 上層（見出し、図、ダイアグラム、キャプチャしたブロック、表の形、最初の文、強調されたテキスト）だけで、ページ全体の意味が伝わります。詳細層（段落の本文、表のセル）は、読者がさらに詳しい情報を求めて開く部分です。上記の各デバイスの選択は、すべて上層のためのものです。

構成：

• 最も重要な点を各セクションの冒頭に置きます。 最初の文まで読んで止めた読者にも、正しい事実が伝わります。
• 見出しだけで話の筋が分かるようにします（「何が何を制御するか」「バージョンが変わるとき」など）。読者のレベルを示す見出し（「簡単な説明」など）は使いません。見出しを順に読むと、ページのアウトラインになります。見出しを付けるのは、およそ 500 語を超えるページだけです。
• 1 段落につき 1 つの考えを扱い、 1～3 文、70 語未満にします。文は短くし、 1 文につき 1 つの考えを、約 20 語で表します。
• 入れ子は 1 階層までにします。 リストの中にリストを入れる必要がある内容には、表、ツリー、サブセクションなど、内容を見せる別の手段を使います。
• ページは冒頭から末尾まで順を追って読めるようにします。 セクションは、読者がその題材に触れる順に並べます。事実は、使う前に導入します。

言葉づかい：

• 平易で、率直に、能動態で書きます。 「ビルドがロックファイルを書き込みます」とし、「ロックファイルはビルドによって書き込まれます」とはしません。同じものにはページ全体で同じ用語を使います。読者がまだ知らない名前は、初出時に平易な言葉で説明してから、仕組みの名前を示します（merge-gate というジョブ名より先に、「すべてのマージを制御するチェック」と説明します）。
• 例を先に示し、その後にルールを説明します。 ブロックや行で例を示し、次の文でその意味を述べます。
• 成果物を示します。 ログ行、エラーテキスト、ツリー出力は言い換えず、そのまま引用します。
• プログラマー向けの文体にします。 正確な名詞とリポジトリ固有の名称を使い、宣伝調にはしません。インストール先にある /unslop は、取り除けずに残った AI らしい表現を削除します。

事実：

• 各事実の管理元は 1 つにします。 事実は 1 つのページだけに記載します。他のページでは、その事実が必要な文中でリンクします（この制限はリトライのページが管理します）。同じ事実を別のページで繰り返すことはありません。リンクまたはナビゲーション専用のセクションを設けるのは、そのページが索引である場合だけです。
• 内部リンクはすべて機能するようにします。 リンク先が存在し、アンカーがそのページの見出しを指している必要があります。検査ツールがリンク先を確認し、アンカーも読み取ります。
• 事実の種類を明示します。 確認済みの事実は、そのまま記載します。仮定、他者が提示した主張、リスク、推奨事項、または独立して検証されていない内容には、該当箇所でその旨を明記します（「往復を省くための推測」や「ユーザーからの報告であり、再現はしていません」など）。
• 読者に不要なものだけを削ります。 実装の詳細、重複、埋め草は省き、定義、理由、制限、次の手順は残します。削除はコンテンツの変更として PR に明記し、再構成（下記）では、事実をすべて移動し、何も削りません。
• 最初に、ページが何であり、何ではないかを伝える案内文を 1 文置き、その後に読者が最初に必要とする情報を続けます。 背景説明から始めてはいけません。

成果物内の文章

コード成果物の中で人が読む説明やヘルプテキストも、段落、デバイス、見出しに関する上記のルールに従う、通常の文章です。該当する成果物は次のとおりです。

• GitHub アクションまたはワークフローの description
• パッケージマニフェストの description
• CLI のヘルプテキスト
• issue および PR のテンプレート

スキルのフロントマターにある description は対象外です。これはトリガーであり、/craft-skills-and-memories スキルが管理します。

成果物固有の事実：

• アクションの description は、リテラルブロック（|）にします。
• 入力と出力の説明 は、それぞれ 1 文にします。
• アクションまたはワークフローの description に ${{ を入れてはいけません。 ファイルの読み込み時に GitHub が評価するため、余分な ${{ があると、読み込み直後にアクションが失敗します。

プローブ

プローブは、レビュアーが目視で確認するほかない2つの項目を報告します。scripts/docs-probe.mts はこのスキルに同梱されており、ページの文章単位、つまり段落とリスト項目を読み取ります。

フロントマター、見出し、フェンス、表、コメント、生成領域は文章ではありません。プローブは次の項目を報告します。

• 上限（--max-words、デフォルトは70語）を超える単位と、その開始行
• 文章で言及されている、存在しないリポジトリパス：バッククォートで囲まれた <dir>/<file>.<ext>、./<file>、../<file>、または <dir>/、あるいは相対リンクのターゲット

山括弧のプレースホルダーは、リポジトリ固有のパスに置き換えてください。

bun "<skill-dir>/scripts/docs-probe.mts" README.md docs/*.md               # exit 0: docs-probe: 4 page(s) clean (cap 70 words)
bun "<skill-dir>/scripts/docs-probe.mts" --shape-only <skill pages>          # a recipe page names files of the repository it describes
bun "<skill-dir>/scripts/docs-probe.mts" --base <template-dir> docs/*.md     # pages that name files a template or generator writes into other repositories

usage: docs-probe.mts [--root <dir>] [--base <dir>]... [--max-words <n>] [--shape-only] <page.md>...
  --root        the repository root paths resolve against (default: cwd)
  --base        a directory under the root that paths also resolve against (repeatable)
  --max-words   the cap on a paragraph or list item (default: 70)
  --shape-only  word counts only; skip the check that named paths exist
exits: 0 every page is clean; 1 findings, one per line as page:line: message; 2 usage or an unreadable page

パスチェックでは、意図的に次のものを対象外とします：プレースホルダー（<skill-dir>/x）、グロブ、owner/repo 形式のスラッグ、絶対パス、ファイル名のみ（package.json）。また、最初のセグメントがページからルートまでのどこにも存在せず、--base の下にも存在しないパスも対象外です（別のレイアウトを説明するページ）。

パスはルート、ページのディレクトリ、その間にある各ディレクトリ、および各 --base を基準に解決されます。そのため、スキルのリファレンスページでは独自の scripts/ フォルダー内のスクリプトを参照できます。また、テンプレートを説明するページでは、そこから生成されるリポジトリで使われるパスでファイルを参照できます。

リポジトリのチェックコマンドで上限を適用すれば、上限は好みの問題ではなく合格条件になります。公開パッケージを通じて適用する方法（すでに Vale を実行しているリポジトリ向けに、同じ上限が vale/ の Vale ルールとして同梱されています）と、リポジトリ独自のプローブで適用する方法があります。スキルのスクリプトはスキルディレクトリから実行するツールのままとし、リポジトリにコピーすることはありません。

既存ページの再構成

文章を組み替えると、事実の配置が変わります。変更では、すべての事実を移し、それ以外は移してはなりません。

1. 変更前の調査：見出しとアンカー（grep -n '^#' <page>）、およびプローブの検出数を記録します。
2. 再構成します。古い段落にあったすべての事実を、新しいページのどこかに配置します。古いページに記載されていなかった事実は追加しません。
3. 変更後の調査：同じ見出しとアンカー（別のページからリンクされている場合もあります）を確認し、プローブの指摘がない状態にします。
4. /rubber-duck-review スキルがインストールされている環境では、そのスキルを使って新旧のページを比較レビューし、次の問いを常に確認します。新しいページにない古いページの事実をすべて列挙し、新しいページにあって古いページにはない事実もすべて列挙します。どちらのリストも空であれば合格です。

PR の本文には、上の例のように変更前と変更後の段落を1つずつ載せ、両方の調査結果を含めます。

アーキテクチャページ

最も劣化しやすいページの種類には、references/architecture-page.md に専用の手順があります。この手順では、1つのレイヤリング宣言、両方向で失敗するリンター、宣言から生成されるモジュールマップ、およびページテストを用います。ページテストでは、図の各ボックスが既存のファイル名と、そのファイルがエクスポートするシンボルを示していることを確認します。

レビュー基準

• 段落またはリスト項目が70語を超えている（目視で数えるのではなく、docs-probe.mtsを実行してください）、または段落が3文を超えている。
• デバイスに何が一目で表示されるかを説明する文章で、コマンドだけが示されて出力がないもの、読者が段落から再構成しなければならないルール、観測できる症状が記載されていない障害など。
• 利点のないデバイスの変更（1行のリストを名前と説明の表に変えるなど）、内容を再構成または統合したほうが素早く読めるのにデバイスが単調なもの（表が続く、箇条書きが続くなど）、同じ内容を二度記載しているもの（図の説明を段落で繰り返す、矢印を箇条書きで言い換えるなど。ただし、図の代替テキストやスクリーンリーダー向けの1文の説明は除きます）。
• リンクで情報の管理元を示せば済むのに、別のページでも事実を繰り返している。
• リンク先またはアンカーが存在しない内部リンク。
• インデックスではないページにあるリンクまたはナビゲーションのセクション。
• 内容ではなく、読者のレベルを示す見出し。
• 続けて読んだときにページの概要が分からない見出し、または約500語未満のページにある見出し。
• 要点が前置きの後に置かれているセクション、またはリストの中にリストがある箇所。
• 本来は文章にすべき論理展開を箇条書きにしている。
• 最上位の要素（見出し、図、図解、引用ブロック、表の形、最初の文、強調テキスト）だけでは話の全体像が伝わらないページ。
• 前提、提示された主張、リスク、推奨事項、または未検証の解釈を確定した事実として示している。
• ページを短縮した際に、読者に必要な定義、理由、制限事項、または次の手順が削られている。
• ページに記載されたパス、リンク、記号、またはチェック項目が存在しない（パスとリンクの検証にはプローブを、図のボックスの検証には​​scripts/architecture/check-page.mtsを使用します）。
• ページを再構成した結果、事実が失われた、事実が追加された、または別のページからリンクされている見出しアンカーが削除された。
• モジュールマップに、コードでは描かれていない接続を示しているアーキテクチャページ。
• ファイルがエクスポートしていないシンボルを示すボックス、またはDemonstrated by:行のない概念図。
• このスキルの「Prose inside artifacts」サブセクションに照らして、ページのルールに違反しているコードアーティファクト内の文章。リテラルブロックではないアクションの説明、または入力や出力を2文以上で説明するもの。アクションまたはワークフローの説明内の${{。
• 人がざっと読むあらゆる場所にある、長々と続く文章：ドキュメント、レポート、PRの文章（PR本文の内容は/pr-and-issue-disciplineスキルの管轄です）。