Ephasme/refine-document

ドキュメントのリファイン（Refine Document）

1つのドキュメントを、プロジェクトの経緯を知らない読者が すぐに行動に移せるバージョンに変換します：レガシーなし、事実ベース、簡潔、整理され、宣言された読者に合わせた形式。

4つのパスを固定順序で実行し、その後検証ゲートを通します。削除されたものはすべてレコードファイルに書き込まれるため、誤った呼び出しも復元可能です。

呼び出し方法（Invocation）

refine-document <path> [--target=agent|human] [--no-record]

フラグ	デフォルト	効果
--target	agent	最後のパスが最適化する読者を指定します。トーンだけでなくドキュメント全体が変わります — パス4 を参照。
--no-record	オフ	レコードファイルをスキップします。削除はバージョン管理からのみ復元可能になります。

ファイルを触る前に：

1. リクエストがこのドキュメントを指定していることを確認します。 これにより、ユーザーのファイルがその場で書き換えられます。
2. ファイルがバージョン管理で追跡されており、クリーンであることを確認します。 そうでない場合は、そのことを伝え、明示的な承認を得てください — --no-record では、それが唯一の復元手段です。
3. 最初のメッセージで使用するターゲットを明示します。 デフォルトの場合も含みます。暗黙のデフォルトは、ドキュメントが間違った読者向けに整形される原因になります。
4. 複数ドキュメントの場合： ドキュメントごとにこの手順を1回実行し、サブエージェントが利用可能な場合は1つのサブエージェントにつき1ファイルとし、同じターゲットとフラグをすべてのサブエージェントに渡します。

出力（Outputs）

出力	パス	内容
リファインされたドキュメント	元のパス（その場で上書き）	現在の状態のみ、ターゲットに合わせて整形
レコード	{名前}.changelog.md（同じディレクトリ）	削除されたものすべて、原文のまま、位置情報付き — 実行ごとに追記
レポート	あなたの返信	レポート を参照

パスの順序（Pass order）

以下の順序でパスを実行します。各パスはドキュメントを個別に読み取ります。各パスは次のパスの入力を縮小し、順序を間違えると互いの効果を打ち消します — パス1で削除されるはずの散文を圧縮すると作業が無駄になり、フィラーを整理してから圧縮するとフィラーが整理されます。

1. レガシーを除去 — 過去への参照としてのみ意味を持つものをすべて削除します。
2. 事実ベース — 残った主張はすべて検証、引用、またはマークされます。
3. 簡潔 — 1つの事実は1つの場所に、事実を保持する最短の形式で。
4. 整理 — 重要な情報を最初に、ターゲットに合わせた形状で。

パス1 — レガシーの除去（strip legacy）

必須のサブスキル： このパスには strip-legacy-content を使用します。このサブスキルは、レガシーの分類、削除・書き換え禁止ルール、およびこのスキルも書き込む {名前}.changelog.md 形式を所有します。--no-record はその --no-changelog にマッピングされます。

そのスキルが利用できない場合は、以下を削除します：履歴や進化の記述、決定記録やADR、非推奨通知、移行・アップグレードガイド、埋め込まれた変更履歴やリリースノート、後方互換性セクション、却下された代替案、日付付きのコメント、廃止されたセクション。範囲を正確に除去し、残った散文を書き換えないでください — パス2〜4が行います。

非推奨機能のルール。 非推奨とマークされた機能は自動的にレガシーではありません。このテストを適用し、どの分岐を採用したかを記録します：

その機能に「古いシステムをサポートする」以外の用途はありますか？

• いいえ — 後方互換性のためだけに存在します。機能とその通知を削除します。
• はい — 現在の動作です。維持し、削除のタイムラインと「v1以降」の枠組みを削除し、レコードにフラグを立てます。

パス2 — 事実ベース（factual）

ドキュメントが行うすべての主張は、継承されたものも含めて「クレーム（claim）」です。それぞれを分類し、対応するアクションを実行します。第5の選択肢はありません。

分類	シグナル	アクション
確認可能、成果物にアクセス可能	動作、フラグ、デフォルト、パス、コマンド、設定キー、コード、設定、--help を読める場合	確認します。正しければ保持、誤っていれば修正。
確認可能、成果物にアクセス不可	同じ主張だが、リポジトリもバイナリも確認できるドキュメントもない場合	主張をソースが述べる通りに正確に保持し、マークせず、未確認としてレポートにリストアップ。
外部からソース可能	標準、プロトコル動作、サードパーティ製品の動作、バージョンサポート	一次情報源を日付またはバージョンとともにインラインで引用します。許容できるソースがない場合：主張を削除。
比較・プロモーション的	「10倍高速」、「業界最高」、「驚異的」、「エレガント」、「ほとんどのエンジニアが同意」、および現在のシステムの一部ではない比較対象（「Kafkaより軽量」）	引用可能な測定値が存在しない限り削除し、その場合は測定値とそのソースを記載。残る事実は保持：「Redis Streamsでジョブをキューイングする」。
検証不可能かつ危険	読者が元に戻せない行動を起こす可能性のある未確認の主張：データ損失、支出、認証情報、破壊的なコマンド、セキュリティ境界	保持し、ドキュメント内で [未確認] とマークし、レポートにリストアップ。

マーカーは出典ではなく危険性を示すものです。 アクセスできない成果物に関するドキュメントはほとんどが未確認の主張であり、それぞれにマークを付けると読者がマーカーを無視するようになります。未確認の出典はレポートとレコードに属し、ドキュメント内の [unverified] は、その失敗を読者が元に戻せない主張のために予約されます。もし多数のマーカーがドキュメントに残っている場合、あなたは出典を危険性として分類しています — 再分類してください。

ソースドキュメントにない事実を決して捏造しないでください。 設定場所、デフォルト、ファイル形式、前提条件 — ほぼ間違いなく真実であっても。平然と述べられた推測された事実は、検証された事実と区別がつかず、このパスだけが読者と自信を持った誤った回答との間にある唯一の防御です。ソースが沈黙しているなら、リファインされたドキュメントも沈黙します。

出典のない主張を曖昧なものに決して和らげないでください。 「約10倍高速」を「非常に高速」と書き換えるのは、精度が低下した同じ意見です。引用するか削除してください。

出典がないという理由で運用指示を決して削除しないでください。 マークすることは削除よりも優れています：マークされた指示は知識のある人が確認できますが、削除されたものは消えてしまいます。

主張の大部分が外部にあるドキュメントの場合は、続行する前に、ソーシングに cite-or-refuse を、完全なクレーム監査に fact-check-document を使用してください。

パス3 — 簡潔（concise）

1つの事実は1つの場所に。 各事実について、それを探す読者が最初にたどり着く単一のセクションを選びます。そこで完全に述べます。他の場所では、再述を削除するか、そのセクションを正確に指すポインターに置き換えます。

直接削除：

• フィラーの書き出し：「注目に値するのは」、「単に」、「基本的に」、「ご覧のとおり」。
• 読者が既に行っていることを指示する：「インストールするには、インストールコマンドを実行してください」。
• 最初の文としてのセクションタイトルの再述。
• 行動を変えない防御的な注意書き。
• 以前の例と同じことを示す例。

圧縮：

• 3つ以上の項目を2つ以上の属性で比較 → 表。
• 並列するものをリストアップした段落 → リスト。
• 主語が名詞化された文 → 動詞（「判断を下す」→「判断する」）。

圧縮の下限。 次の単語を削除すると事実が失われる時点で停止します。事実を失った短いドキュメントは後退であり、勝利ではありません。単語数は作業の症状であり、目標ではありません。

唯一条件付きで許容される重複 は、パス4で設定された長さのしきい値を超えた場合の、エージェントターゲットの重要なブロックの先頭と末尾での再述です。そのしきい値を下回る場合は他の繰り返しと同じであり、削除されます。

パス4 — 宣言された読者に合わせて整理（organize for the declared reader）

共通：順序のルール（Shared: the ordering law）

主題の履歴ではなく、読者をブロックするものによって順序付けます：

1. これが何か — 1文、前置きなし。
2. 他のすべてをブロックする前提条件 — それがなければ何も起動しない環境変数、認証情報、必要なバージョン。
3. 破壊的で元に戻せない操作 — 削除、上書き、支出、元に戻せないもの。これはトピックではなく結果による配置です：コマンドが obscure でも先頭近くに配置され、マークされ、単に言及されるだけではありません。
4. メインパス — ほとんどの読者が実行しに来たこと、最初から最後まで。
5. その他すべて、使用頻度の高い順。
6. エッジケース、トラブルシューティング、参照テーブル は最後。

ドキュメントに約5つのセクション以上ある場合、要約ブロックは先頭に属します。これは散文の要約ではなく、読者が何かをする前に必要な事実をリストアップします。

--target=agent

読者はドキュメントをコンテキストとして読み込むモデルであり、しばしば1つの用語でgrepし、一致したスライスのみを読みます。この形状のドキュメントを作成します：

1. 常に最初に重要なブロック。約100行を超える場合のみ、最後に同じブロックをそのまま繰り返す。 前提条件、破壊的操作、ハード制約は、長さに関係なく最初に配置します。中間の劣化（Liu et al., TACL 2024）は、数千から数万トークンのマルチドキュメントコンテキストで測定されます — 1回のパスで読める短いドキュメントにはその意味での「中間」はなく、そこでの末尾コピーは取得上の利点のない純粋な重複です。重複は、同じ約100行のしきい値を超えた場合のみ行われ、そのしきい値を超えるとコンテンツリスト（#9を参照）が追加され、grep-and-sliceリーダーがドキュメントの途中に着地しブロックを見逃す可能性が生じます。しきい値を下回る場合は、先頭に一度だけ述べ、そこで終了します — そこでの2番目のコピーは、このターゲットの機能ではなく、パス3で捕捉されるべき後退です。重複が正当化される場合：最初のコピーに ## 重要な制約（Critical constraints）、最後のコピーに ## 重要な制約（繰り返し）（Critical constraints (repeat)） の見出しを付けます — 2つの一意のアンカー、同一の本文、ドキュメントに含まれる唯一のほぼ重複した見出しです。
2. 肯定的な表現。 取るべき行動を述べます。禁止が本当に必要な場合は、同じ文に肯定的な代替案を入れます：「/tmp ではなく state/ に書き込んでください」。モデルは否定文よりも肯定文の方が測定可能なほど良好に処理します。
3. 1つの見出し、1つの取得可能な単位。 すべての見出しはドキュメント内で一意であり、リテラルであり、エージェントがgrepするであろう単語で構成されます — 上記の重要なブロックのペアを除く。そのセクションは単独で成立します：「上記のとおり」や、他のセクションにある指示語を含む代名詞はありません。
4. 使用時点でのリテラル識別子。 フルパス、正確なコマンドライン、正確な環境変数名、正確なファイル名 — 毎回、一度だけの参照ではなく。
5. ナラティブよりも検証可能な記述。 コマンド、パス、値、終了条件。文が検証できない場合はおそらく根拠（rationale）であり、エージェントの行動を変える場合にのみ保持します。
6. マークダウン構造のみ — 見出し、リスト、フェンスで囲まれたコード、小さな表。マークダウンドキュメントにXMLタグ付けスキームを追加しないでください。JSONまたはYAMLブロックは、真に機械可読データであるコンテンツのために予約します。
7. すべての事実を保持する最短の形式。 入力長はそれ自体で取得を劣化させ、何も答えないトピック的に隣接するコンテンツは注意散漫要因として機能します — ニアミスの散文は不在よりも悪いです。
8. 矛盾なし。 互いに矛盾する2つの記述はどちらも持たないより悪いです。書く前に解決します。
9. 約100行を超える場合のみコンテンツリスト、エージェントがファイル全体ではなくスライスを読む可能性があり、そうでなければスコープが見えないため。

受入基準： 1つの見出しをgrepし、そのセクションのみを読むエージェントが正しく行動すること。

--target=human

読者は読む前にスキャンし、単語の少数派のみを読みます。書式が手がかりを提供しない場合、そのスキャンは左端に沿ったF字型の掃引に劣化します — 構造はそれを防ぐものであり、模倣するものではありません。この形状のドキュメントを作成します：

1. ドキュメントと各セクションのポイントを最初の文に。 最も重要なコンテンツは最初の2段落にあります。そこで止まる読者は、彼らが求めていたものを手に入れます。
2. フロントローディングされた行。 すべての見出し、箇条書き、段落は、情報を伝える単語で始まります — 行の最初の2語は読まれ、残りはスキャンされます。
3. 記述的な見出し：「状態ディレクトリの設定」、決して「概要」、「注記」、「詳細」、「セクション3」ではありません。
4. 段落ごとに1つのアイデア、最大約4文。
5. 客観的な言葉遣い。 中立的な表現は、プロモーション的な表現よりもユーザビリティにおいて測定可能なほど優れています。これは理解の結果であり、スタイルの好みではありません。
6. 比較には表、推論には散文。 2つ以上の属性を超える3つ以上の項目 → 表。接続された、因果的な、または微妙な説明は散文のままにします — 議論を箇条書きに断片化するとリンクが失われます。
7. ドメイン語彙はそのまま。 用語は一度、インラインで、最初の使用時に定義します。技術的な精度を簡略化して失わないでください。可読性スコアのために書き換えないでください — それらのスコアは整理を見ることができず、正しい用語をペナルティにします。
8. 約2画面または5セクションを超える場合にコンテンツリスト。

受入基準： 読者がドキュメントのみを使用して、ドキュメントが説明するタスクを完了できること。

ターゲット間で異なる必要があるもの（What must differ between targets）

決定項目	--target=human	--target=agent
重要な制約	1回、最初の画面に、マーク付き	約100行未満では先頭に1回；それを超えると最初 と 最後にそのまま繰り返し
セクションの独立性	セクションは前のセクションに基づいて構築可能	すべてのセクションは自己完結型
相互参照	「上記参照」で問題ない	正確な見出しを名前で指定
見出し	記述的で読みやすい	一意、リテラル、grepに適した形状
禁止表現	「Xをするな」で問題ない	「Yをせよ」が禁止を伝える
識別子	一度導入したら短縮可	毎回完全でリテラル
推論	散文は因果関係を保持	行動を変える場合のみ保持
コンテンツリスト	約2画面超	約100行超
長さ	元の単語数の約半分	すべての事実を保持する最短形式

乖離チェック — 必須。 ファイルを書き込む前に、この実行が 宣言されたターゲットのために 異なる方法で行った少なくとも3つの決定を挙げ、レポートに記載します。

レポート（Report）

応答には、リファインされたドキュメントの前または後に、以下の構造のセクションを含めます。ドキュメントのマークダウンブロックを壊さないでください。

Refine report

File: <path>

Target: agent | human

Target-driven decisions (3以上を挙げ、ターゲットがどのように選択を変えたかを説明します)：

1. ...
2. ...
3. ...

Summary by pass

Pass	Removed	Added	Changed	Unchecked claims	Hazards marked
1 — Strip legacy	5 items (3 changelog references, 2 migration notes)	—	0	—	—
2 — Verifiable	—	3 citations	2 values corrected	1 (version constraint, no access to registry)	0
3 — Compress	40% of original prose	1 table (replacing 3 paragraphs)	2 section boundaries	—	—
4 — Organize	0	1 critical block (agent) / TOC (human)	section order, heading edits	—	—

Unchecked claims report: (各主張の短い説明、ソースが利用可能でない理由、およびその位置)

Record: {name}.changelog.md

出力の例（Example output）

（実際の変更を示すために、簡略化されたドキュメントの断片をここに含めることができます。）

依存関係（Dependencies）

• strip-legacy-content — パス1（レガシー除去）に必須。
• cite-or-refuse — パス2で外部ソーシングが必要な場合に推奨。
• fact-check-document — パス2で完全なクレーム監査が必要な場合に推奨。