From 19ca934d3ccc6b02f89458491973c568af611598 Mon Sep 17 00:00:00 2001 From: gitt510 <190343966+gitt510@users.noreply.github.com> Date: Tue, 1 Sep 2026 23:57:42 +0900 Subject: [PATCH 1/2] feat(writing-documents): extract the shared writing discipline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit build-readme と build-pr-description が持っていた形式の規律を writing-documents に 1箇所化し、両者は委譲を宣言する。 Co-Authored-By: Claude Opus 5 (1M context) --- skills/build-pr-description/SKILL.md | 75 +++++++++---------- skills/build-readme/SKILL.md | 73 +++++++------------ skills/writing-documents/SKILL.md | 104 +++++++++++++++++++++++++++ 3 files changed, 164 insertions(+), 88 deletions(-) create mode 100644 skills/writing-documents/SKILL.md diff --git a/skills/build-pr-description/SKILL.md b/skills/build-pr-description/SKILL.md index 94b7fb6..6874b99 100644 --- a/skills/build-pr-description/SKILL.md +++ b/skills/build-pr-description/SKILL.md @@ -5,9 +5,10 @@ description: > argument — the claims that make the change necessary, each backed by verifiable facts — and What / Test / Notes carry only the facts a reviewer needs to read the diff. Claims and facts are gathered from the diff, commits, and conversation; an existing body is broken down - sentence by sentence and only what survives verification is kept. Use when creating or - rewriting a PR body, including when running gh pr create or gh pr edit. Not for a few added - lines to an existing description — a normal edit covers that. + sentence by sentence and only what survives verification is kept. Format discipline is + delegated to the writing-documents skill. Use when creating or rewriting a PR body, + including when running gh pr create or gh pr edit. Not for a few added lines to an existing + description — a normal edit covers that. --- # build-pr-description @@ -18,8 +19,10 @@ PR description は reviewer が diff を読むための文書。**Why は論証 （Google の CL description ガイド・Kubernetes template などが収束する Why → What → Test）に従う。 how の解説は diff 自身が語るので書かない。 -build-readme と同じく、匂い狩り（denylist）ではなく -**書いてよい文の allowlist** で判定する。該当しない文は書かない。 +**形式の規律は `writing-documents` に委譲する。** allowlist で判定するという方法、3形式 +（bullet / table / code block）と paragraph 禁止、書き換え技法、1 fact = 1 home、共通の完了 +チェックはそちらが持つ。この skill が持つのは PR 固有の allowlist・骨子・fact の収集経路・ +PR 固有のチェックだけ。書き始める前に `writing-documents` を invoke する。 publish-pr（PR 作成 flow）は body の作成をこの skill に委譲する。 body の有無で変えるのは fact の収集経路だけ。既存 body は候補の入手元にはするが、 @@ -43,7 +46,7 @@ body の有無で変えるのは fact の収集経路だけ。既存 body は候 根拠のない主張はただの意見 — 根拠を見つけるか、主張ごと落とす。 どの主張も支えない fact は Why に置かない（Notes 行きか削除）。 -文単位で迷ったら: **その文を消したとき、reviewer の diff の読み方や質問が変わるか？** +削除テストの主体は **reviewer**: その文を消したとき、reviewer の diff の読み方や質問が変わるか。 変わらないなら落とす。 ### 骨子 @@ -64,34 +67,23 @@ body の有無で変えるのは fact の収集経路だけ。既存 body は候 - allowlist と section の対応: 主張 + 根拠 → Why、変更の fact → What、 検証結果 → Test、注記 → Notes -### 形式 — section 内に置けるのは3形式のみ +### 形式 — PR 固有の例外 -- **bullet list** — 1 bullet = 1 fact。句点なし。「以下は〜」のような document 自身への言及は - bullet に形を変えた paragraph であり、fact ではない -- **table** — 各行が fact で、列の比較に意味があるとき bullet より優先する - （test 一覧・endpoint と契約の対応など。bullet 化すると比較可能性が落ちる） -- **code block** — 実行した検証コマンドなど、コピペして実行できる verbatim 成果物 +`writing-documents` の3形式に従い、PR では次の2つだけを例外として宣言する。 -- **Why は主張 → 根拠の2段 bullet**。主張が top-level、根拠をその直下に nest する。 +- **Why は主張 → 根拠の2段 bullet。** 主張が top-level、根拠をその直下に nest する。 nest を使ってよいのは Why だけ -- What / Test / Notes は上の3形式 + 1 fact 1 bullet -- paragraph（地の文）は全 section で禁止 +- **Notes の bullet は理由節をぶら下げてよい。** README では理由節は弁明の再侵入だが、 + Notes では rationale が fact そのもの（「Tavern も検証のうえ pure pytest を採用 — + assertion が YAML から漏れるため」で1 fact） -例外: **Notes の bullet は理由節をぶら下げてよい**。README では理由節は弁明の -再侵入だが、Notes では rationale が fact そのもの -（「Tavern も検証のうえ pure pytest を採用 — assertion が YAML から漏れるため」で1 fact）。 +What / Test は例外なし。paragraph（地の文）は全 section で禁止。 +table は test 一覧・endpoint と契約の対応のように列の比較に意味があるときに選ぶ。 -### 書き換え技法 — What を書くときの変換 +### What の変換 -- **rationale → 観測可能な保証。** What で理由を説明したくなったら、変更後に成り立つ契約に変換する - - 悪: `synchronize` では発火しない — push のたびに再付与すると人間の操作と競合するため - - 良: `synchronize` では付与せず、人間による assignee の付け替えを上書きしない - - 契約に変換できない rationale は Notes の管轄 -- **操作 → 不変条件。** 手続き（上書きする・剥がす・付け直す）が書きにくいときは、結果の状態を書く - - 悪: 更新のたびに label を上書きし、古い label を削除する - - 良: PR には常に、最新の変更量を反映した `size/*` が1つだけ付く -- **曖昧動詞の対象を明示。** 削除する・更新する・作る は、何に対する操作か読者が誤読する - （「label を削除」= repo の label 定義の削除に読める）。対象を書くか不変条件に変換する +`writing-documents` の「rationale → 観測可能な保証」は、PR では **What で理由を説明したく +なったときの変換**として効く。契約に変換できない rationale は Notes の管轄。 ### 判断の住処 — 問いの向きと寿命で分ける @@ -119,41 +111,40 @@ body の有無で変えるのは fact の収集経路だけ。既存 body は候 - **diff 内 doc の再掲** — README に書いた恒久 fact の丸写し。reviewer は diff で doc を読む - **動機の取り違え** — assertion や実装が参照する issue を「関連 issue:」として 動機に昇格させたもの。test が #N の契約を検証することと、PR の動機が #N であることは別 -- **session leak** — 会話の文脈への言及・自己弁護 tone ## 手順 — 主張と fact の収集・適用 -1. 既存 body がある場合は `gh pr view --json body` で取得し、**文単位**で allowlist に照合する。 +1. `writing-documents` を invoke し、共通の判定方法・形式・書き換え技法を読み込む +2. 既存 body がある場合は `gh pr view --json body` で取得し、**文単位**で allowlist に照合する。 section や構成は継承せず、生き残る文だけを候補にする -2. **What** — diff（`git diff` / `gh pr diff`）から観測できる変更と、変更後の対外契約を拾う。 +3. **What** — diff（`git diff` / `gh pr diff`）から観測できる変更と、変更後の対外契約を拾う。 既存 body と diff が食い違う場合は diff を正とする -3. **Why の主張は diff から導出できない**。既存 body・会話・commit message・既存 issue に求め、 +4. **Why の主張は diff から導出できない**。既存 body・会話・commit message・既存 issue に求め、 無ければ user に確認する。根拠はコード・実 resource・実測で検証してから主張の下に置く。 関連しそうな issue link を勝手に動機へ昇格させない -4. **Test** — session 中に実際に実行した検証コマンドと実測値を拾う。既存 body の記載値は +5. **Test** — session 中に実際に実行した検証コマンドと実測値を拾う。既存 body の記載値は 信じず、安全に再実行できるもの（`--collect-only`・lint 等）は再実行して照合する。 外部環境を叩くものは既存の実測値を使う -5. **Notes** — 既存 body・session から却下した代替案・設計の前例を拾う。 +6. **Notes** — 既存 body・session から却下した代替案・設計の前例を拾う。 merge 後に失われ、reviewer の一往復を減らす rationale だけを残す -6. 主張と fact を骨子に配置し、形式ルールを適用する。既存 body・会話由来の文は session leak を +7. 主張と fact を骨子に配置し、形式ルールを適用する。既存 body・会話由来の文は session leak を **文単位**で検査する -7. **適用前に「完了チェック」を1項目ずつ機械的に検査する**。書く行為と検査する行為を +8. **適用前に「完了チェック」を1項目ずつ機械的に検査する**。書く行為と検査する行為を 分けないと守れない -8. `gh pr create --body-file ` または `gh pr edit --body-file ` で適用する -9. 以後 PR に commit を積んだら、What / Test に同じ規律で追記して同期する +9. `gh pr create --body-file ` または `gh pr edit --body-file ` で適用する +10. 以後 PR に commit を積んだら、What / Test に同じ規律で追記して同期する ## 完了チェック +`writing-documents` の共通チェックに、以下を足して検査する。 + - [ ] Why の各 top-level bullet が主張（判断の叙述文）である — 事実の陳列になっていない - [ ] 全主張が「偽なら PR が不要になる」を満たす - [ ] 各主張の直下に検証済みの根拠が1つ以上 nest されている - [ ] どの主張も支えない fact が Why に残っていない - [ ] 主張が user 確認済みか、既存 body / commit / 会話に根拠がある -- [ ] paragraph（地の文）が1つも無い -- [ ] 各 bullet が単一の主張または fact（Notes 以外は理由節なし） -- [ ] 「以下は〜」型の meta-bullet（document への言及）がない +- [ ] nest が Why 以外に無く、理由節が Notes 以外に無い - [ ] 恒久 fact が diff 内 doc と重複していない（PR は参照のみ） - [ ] 外部 SoT の値の snapshot に「現在値」の銘がある - [ ] Test の数値・コマンドが実装・再実行と照合済み - [ ] Notes が「reviewer が聞くであろう質問への先回り」だけで構成されている -- [ ] 消しても reviewer の読み方が変わらない文が残っていない diff --git a/skills/build-readme/SKILL.md b/skills/build-readme/SKILL.md index 80526c3..baf57ce 100644 --- a/skills/build-readme/SKILL.md +++ b/skills/build-readme/SKILL.md @@ -5,8 +5,9 @@ description: > itself (code, terraform, actual behavior), composes sections from those facts, and writes one fact per bullet; decision rationale and internal how-it-works are left out. An existing README is broken down sentence by sentence and only facts verifiable against the - implementation survive. Use when creating, rewriting, condensing, or restructuring a README. - Not for a few added lines to an existing README — a normal edit covers that. + implementation survive. Format discipline is delegated to the writing-documents skill. Use + when creating, rewriting, condensing, or restructuring a README. Not for a few added lines + to an existing README — a normal edit covers that. --- # build-readme @@ -14,8 +15,10 @@ description: > README を「system が何であるか」の観測可能な事実の集合として書く。 決定の物語・レビューへの弁明・実装の how は README の管轄外（PR / ADR / code の管轄）。 -悪い文の variation は無限にあるため、匂い狩り（denylist）ではなく -**書いてよい文の allowlist** で判定する。該当しない文は書かない。 +**形式の規律は `writing-documents` に委譲する。** allowlist で判定するという方法、3形式 +（bullet / table / code block）と paragraph 禁止、書き換え技法、1 fact = 1 home、共通の完了 +チェックはそちらが持つ。この skill が持つのは README 固有の allowlist・section composition・ +fact の収集経路・README 固有のチェックだけ。書き始める前に `writing-documents` を invoke する。 README の有無で変えるのは fact の収集経路だけ。新規作成では system から収集し、 全面再構築では既存 README を文単位で解体して候補を救出する。 @@ -38,7 +41,7 @@ README の有無で変えるのは fact の収集経路だけ。新規作成で 例外として、値の出典 link 1行（例: threshold は Prow size plugin の default）は bikeshedding 防止として許可する。 -判定に迷ったら: **その文を消したとき、読者の行動や期待が変わるか？** +削除テストの主体は **README の読者**: その文を消したとき、読者の行動や期待が変わるか。 変わらないなら弁明なので落とす。変わるなら（保証・非自明な挙動）残す。 ### section composition @@ -82,37 +85,15 @@ allowlist は「その fact を書いてよいか」、section は「読者が **Resources** は宣言、**Setup** は一度だけ行う操作、**Usage / Running** は繰り返す操作。 前提・準備・日常操作を同じ section に混ぜない。順序に意味がある手順だけ ordered list を使う。 -### 形式 — section 内に置けるのは3形式のみ +### 形式 — README 固有の適用 -- **bullet list** — 1 bullet = 1 fact。句点なし。「〜だが」「〜のため」で理由をぶら下げない - （bullet は接続詞を持てないので、弁明の再侵入を構文で防げる）。 - fact とは **system についての事実**。「以下は〜」のような document 自身への言及は - bullet に形を変えた paragraph であり、fact ではない。section の意味は見出しと配置で示す -- **table** — 各行が fact で、列の比較に意味があるとき bullet より優先する - （threshold 表・課金表など。bullet 化すると比較可能性が落ちる） -- **code block** — コピペして実行する verbatim 成果物（deploy commands など） +`writing-documents` の3形式に従い、README ではさらに次を課す。 -paragraph（地の文）は禁止。ordered list は順序に意味がある手順だけに使う。 - -**1 fact = 1 home。** 同じ fact を2箇所に書かない。手で維持する概要 table・目次は -subsection 見出しの再述になり、drift の温床（機能の列挙は `##`/`###` 見出し自体が担う）。 -fact はそれが固有に属する場所に1回だけ書き、他所からは名前で参照する。 - -### 書き換え技法 - -**操作 → 不変条件。** 手続き（上書きする・剥がす・付け直す）が書きにくいときは、 -結果の状態を書く。冪等性・重複排除・掃除が1文に含意される。 - -- 悪: 更新のたびに label を上書きし、古い label を削除する -- 良: PR には常に、最新の変更量を反映した `size/*` が1つだけ付く - -**rationale → 観測可能な保証。** 理由を説明したくなったら、読者から見える契約に変換する。 - -- 悪: `synchronize` では発火しない — push のたびに再付与すると人間の操作と競合するため -- 良: `synchronize` では付与せず、人間による assignee の付け替えを上書きしない - -**曖昧動詞の対象を明示。** 削除する・更新する・作る は、何に対する操作か読者が誤読する -（「label を削除」= repo の label 定義の削除に読める）。対象を書くか不変条件に変換する。 +- **paragraph の例外は h1 直下の lead 1-2文だけ。** section 内は例外なし +- **理由節・nest の例外は宣言しない。** README では理由節が弁明の再侵入になる +- **table を選ぶのは列の比較に意味があるとき**（threshold 表・課金表など） +- **概要 table・目次を手で維持しない。** subsection 見出しの再述であり、機能の列挙は + `##`/`###` 見出し自体が担う ### 落ちる典型（allowlist が自動で弾くもの） @@ -130,30 +111,30 @@ fact はそれが固有に属する場所に1回だけ書き、他所からは ## 手順 -1. 対象 README の状態に応じて fact の候補を収集する +1. `writing-documents` を invoke し、共通の判定方法・形式・書き換え技法を読み込む +2. 対象 README の状態に応じて fact の候補を収集する - README がない場合: 実装（code・terraform・justfile 等）から収集する - README がある場合: 現 README を**文単位**で allowlist に照合する。既存 section や構成は 継承せず、生き残る文だけを候補にする -2. 候補を実装と照合する。README の prose・記憶・推測・会話の記載を根拠にしない。 +3. 候補を実装と照合する。README の prose・記憶・推測・会話の記載を根拠にしない。 内部 pipeline は、読者が観測できる結果（不変条件）に変換するか落とす -3. 読者が体感する値と限界を抽出する。cost は +4. 読者が体感する値と限界を抽出する。cost は 常時課金 resource の有無 → 従量課金の軸（何に比例するか）→ 上限・抑制の仕組みの順に確認する -4. system が前提とするが管理しない外部リソースを抽出する -5. 読者自身が行う操作を抽出し、初回の準備・繰り返す操作・保守操作を区別する -6. allowlist を通った fact を読者の関心ごとに cluster 化し、section composition のルールと +5. system が前提とするが管理しない外部リソースを抽出する +6. 読者自身が行う操作を抽出し、初回の準備・繰り返す操作・保守操作を区別する +7. allowlist を通った fact を読者の関心ごとに cluster 化し、section composition のルールと canonical section palette を使って header と順序を決める -7. 形式ルールを適用し、**提出前に「完了チェック」を1項目ずつ機械的に検査する** +8. 形式ルールを適用し、**提出前に「完了チェック」を1項目ずつ機械的に検査する** （grep / 目視走査）。書く行為と検査する行為を分けないと守れない ## 完了チェック -- [ ] section 内に paragraph がない（prose は h1 lead のみ） +`writing-documents` の共通チェックに、以下を足して検査する。 + +- [ ] prose が h1 直下の lead 1-2文に収まっている（section 内に paragraph がない） - [ ] 内容がない section や、固定骨子を埋めるためだけの section がない - [ ] 各 header が配下の fact に対する読者の関心を具体的に表している - [ ] 前提・一度だけ行う準備・繰り返す操作が同じ section に混ざっていない -- [ ] 各 bullet が単一の fact で、理由節をぶら下げていない -- [ ] 「以下は〜」型の meta-bullet（document への言及）がない -- [ ] 同じ fact が2箇所に書かれていない（概要 table・再掲・重複 link） +- [ ] 概要 table・目次が subsection 見出しの再述になっていない - [ ] 読者が体感しない内部 config 値（batch window 等）が table や bullet に紛れていない - [ ] Cost がある場合、その数値・上限が実装と一致している -- [ ] 「消しても読者の行動・期待が変わらない文」が残っていない diff --git a/skills/writing-documents/SKILL.md b/skills/writing-documents/SKILL.md new file mode 100644 index 0000000..955b3f1 --- /dev/null +++ b/skills/writing-documents/SKILL.md @@ -0,0 +1,104 @@ +--- +name: writing-documents +description: > + The shared writing discipline for documents whose value is the facts a reader acts on — + README, PR description, issue, handover, design note. Judges every sentence against an + allowlist the caller defines instead of hunting smells, permits only three forms inside a + section (bullet, table, code block) with paragraphs banned, converts rationale into + observable guarantees, and separates writing from a mechanical final check. Use when + writing or fully rebuilding such a document, and when asked to strip prose, 地の文, + padding, or self-justification out of an existing draft. build-readme and + build-pr-description delegate this layer and add their own allowlist and skeleton; this + skill owns no document type of its own. +--- + +# writing-documents + +読者が行動するための fact を運ぶ document に共通の規律。 + +**この skill が持つのは判定の方法と形式だけで、document 型は持たない。** allowlist の中身・ +section 骨子・fact の収集経路は呼び出し側（`build-readme`・`build-pr-description` など）が定義する。 +単独で呼ばれた場合は、対象 document の読者と「読者が取る行動」を先に確定させてから適用する。 + +## 呼び出し側との分担 + +| この skill が持つ | 呼び出し側が持つ | +| --- | --- | +| allowlist で判定するという方法 | allowlist の中身（許す文の種類） | +| 形式 — 3形式・paragraph 禁止・1 bullet 1 fact | section 骨子と header の決め方 | +| 書き換え技法 | fact の収集経路 | +| 削除テストの形 | 削除テストの主体（読者・reviewer・引き継ぎ先） | +| 共通の完了チェック | document 型固有の完了チェック | +| 例外を宣言できるという仕組み | 例外の宣言（理由節を許す section など） | + +## 判定 — allowlist で書く + +悪い文の variation は無限にあるため、匂い狩り（denylist）ではなく**書いてよい文の allowlist** +で判定する。該当しない文は書かない。呼び出し側の allowlist が数種類の文型を列挙するので、 +候補の文をその型に照合し、どれにも当たらなければ落とす。 + +**削除テスト** — 判定に迷ったら: **その文を消したとき、読者の行動・期待・判断が変わるか？** +変わらないなら落とす。変わるなら残す。主体（読者か reviewer か）は呼び出し側が決める。 + +新規作成と全面再構築の差は **fact の収集経路だけ**。既存 document は文単位で allowlist に照合し、 +section や構成は継承しない。生き残った文だけを候補にする。既存の記載を「正しい記載」として +継承しない。 + +## 形式 — section 内に置けるのは3形式のみ + +- **bullet list** — 1 bullet = 1 fact。句点なし。「〜だが」「〜のため」で理由をぶら下げない + （bullet は接続詞を持てないので、弁明の再侵入を構文で防げる）。fact とは + **document の主題についての事実**。「以下は〜」のような document 自身への言及は + bullet に形を変えた paragraph であり、fact ではない。section の意味は見出しと配置で示す +- **table** — 各行が fact で、列の比較に意味があるとき bullet より優先する + （bullet 化すると比較可能性が落ちるもの） +- **code block** — コピペして実行できる verbatim 成果物 + +**paragraph（地の文）は禁止。** ordered list は順序に意味がある手順だけに使う。 +nest と理由節は、呼び出し側が section を名指しで例外宣言したときだけ使える。 + +**1 fact = 1 home。** 同じ fact を2箇所に書かない。fact はそれが固有に属する場所に1回だけ書き、 +他所からは名前で参照する。手で維持する概要 table・目次は見出しの再述であり、drift の温床。 + +## 書き換え技法 + +**操作 → 不変条件。** 手続き（上書きする・剥がす・付け直す）が書きにくいときは、結果の状態を書く。 +冪等性・重複排除・掃除が1文に含意される。 + +- 悪: 更新のたびに label を上書きし、古い label を削除する +- 良: PR には常に、最新の変更量を反映した `size/*` が1つだけ付く + +**rationale → 観測可能な保証。** 理由を説明したくなったら、読者から見える契約に変換する。 + +- 悪: `synchronize` では発火しない — push のたびに再付与すると人間の操作と競合するため +- 良: `synchronize` では付与せず、人間による assignee の付け替えを上書きしない + +契約に変換できない rationale は、その document の管轄外（呼び出し側が行き先を決める）。 + +**曖昧動詞の対象を明示。** 削除する・更新する・作る は、何に対する操作か読者が誤読する +（「label を削除」= repo の label 定義の削除に読める）。対象を書くか不変条件に変換する。 + +## 落ちる典型 + +- **session leak** — 会話の文脈への言及・自己弁護 tone・「先ほどの指摘を反映し」型の編集履歴。 + document は成果物であり、それが作られた過程の記録ではない +- **meta-bullet** — 「以下は〜」「この section では〜」。document 自身についての言及は fact ではない + +## 手順への組み込み + +呼び出し側の手順に、次の2点を必ず含める。 + +1. 形式ルールの適用と、**提出前の完了チェックを1項目ずつ機械的に検査する行程** + （grep / 目視走査）。書く行為と検査する行為を分けないと守れない +2. 会話・既存 document 由来の文の session leak 検査を**文単位**で行う + +## 完了チェック（共通） + +呼び出し側の document 型固有チェックに、以下を常に足す。 + +- [ ] paragraph（地の文）が1つも無い（呼び出し側が許した lead を除く） +- [ ] 各 bullet が単一の fact で、理由節をぶら下げていない（例外宣言された section を除く） +- [ ] 「以下は〜」型の meta-bullet がない +- [ ] 同じ fact が2箇所に書かれていない +- [ ] 会話への言及・自己弁護 tone が残っていない +- [ ] 消しても読者の行動・期待が変わらない文が残っていない From 9d7b09d17793dee9b49863f523b65e6618e8207e Mon Sep 17 00:00:00 2001 From: gitt510 <190343966+gitt510@users.noreply.github.com> Date: Wed, 2 Sep 2026 19:14:46 +0900 Subject: [PATCH 2/2] refactor(writing-documents): remove facts duplicated across the shared and caller skills Co-Authored-By: Claude Fable 5.1 --- skills/build-pr-description/SKILL.md | 38 ++++++------------- skills/build-readme/SKILL.md | 29 ++++----------- skills/writing-documents/SKILL.md | 55 +++++++++------------------- 3 files changed, 36 insertions(+), 86 deletions(-) diff --git a/skills/build-pr-description/SKILL.md b/skills/build-pr-description/SKILL.md index 6874b99..feee703 100644 --- a/skills/build-pr-description/SKILL.md +++ b/skills/build-pr-description/SKILL.md @@ -5,10 +5,9 @@ description: > argument — the claims that make the change necessary, each backed by verifiable facts — and What / Test / Notes carry only the facts a reviewer needs to read the diff. Claims and facts are gathered from the diff, commits, and conversation; an existing body is broken down - sentence by sentence and only what survives verification is kept. Format discipline is - delegated to the writing-documents skill. Use when creating or rewriting a PR body, - including when running gh pr create or gh pr edit. Not for a few added lines to an existing - description — a normal edit covers that. + sentence by sentence and only what survives verification is kept. Use when creating or + rewriting a PR body, including when running gh pr create or gh pr edit. Not for a few added + lines to an existing description — a normal edit covers that. --- # build-pr-description @@ -19,14 +18,9 @@ PR description は reviewer が diff を読むための文書。**Why は論証 （Google の CL description ガイド・Kubernetes template などが収束する Why → What → Test）に従う。 how の解説は diff 自身が語るので書かない。 -**形式の規律は `writing-documents` に委譲する。** allowlist で判定するという方法、3形式 -（bullet / table / code block）と paragraph 禁止、書き換え技法、1 fact = 1 home、共通の完了 -チェックはそちらが持つ。この skill が持つのは PR 固有の allowlist・骨子・fact の収集経路・ -PR 固有のチェックだけ。書き始める前に `writing-documents` を invoke する。 - +**形式の規律は `writing-documents` に委譲する。** この skill が持つのは PR 固有の +allowlist・骨子・fact の収集経路・PR 固有のチェックだけ。 publish-pr（PR 作成 flow）は body の作成をこの skill に委譲する。 -body の有無で変えるのは fact の収集経路だけ。既存 body は候補の入手元にはするが、 -正しい記載として継承しない。新規作成と全面再構築に同じ骨子・形式・完了チェックを適用する。 ## ルール @@ -67,9 +61,9 @@ body の有無で変えるのは fact の収集経路だけ。既存 body は候 - allowlist と section の対応: 主張 + 根拠 → Why、変更の fact → What、 検証結果 → Test、注記 → Notes -### 形式 — PR 固有の例外 +### 形式 — PR の例外宣言 -`writing-documents` の3形式に従い、PR では次の2つだけを例外として宣言する。 +次の2つだけを例外として宣言する。 - **Why は主張 → 根拠の2段 bullet。** 主張が top-level、根拠をその直下に nest する。 nest を使ってよいのは Why だけ @@ -77,17 +71,12 @@ body の有無で変えるのは fact の収集経路だけ。既存 body は候 Notes では rationale が fact そのもの（「Tavern も検証のうえ pure pytest を採用 — assertion が YAML から漏れるため」で1 fact） -What / Test は例外なし。paragraph（地の文）は全 section で禁止。 -table は test 一覧・endpoint と契約の対応のように列の比較に意味があるときに選ぶ。 - -### What の変換 - -`writing-documents` の「rationale → 観測可能な保証」は、PR では **What で理由を説明したく -なったときの変換**として効く。契約に変換できない rationale は Notes の管轄。 +What / Test は例外なし。 ### 判断の住処 — 問いの向きと寿命で分ける -- 「なぜこの変更が要るか」→ Why の主張。「なぜ X という代替じゃないか」→ Notes に 1-2 bullet +- 「なぜこの変更が要るか」→ Why の主張。「なぜ X という代替じゃないか」→ Notes に 1-2 bullet。 + What で説明したくなった rationale は観測可能な保証に変換し、できないものは Notes へ - 将来コードを触る人が必要とする決定 → ADR / code comment。PR は merge 後に 発掘されにくく、寿命の長い決定の恒久の家にならない - フル装備の「Rationale and alternatives」section を PR に張らない（RFC / ADR の形式） @@ -127,10 +116,8 @@ table は test 一覧・endpoint と契約の対応のように列の比較に 外部環境を叩くものは既存の実測値を使う 6. **Notes** — 既存 body・session から却下した代替案・設計の前例を拾う。 merge 後に失われ、reviewer の一往復を減らす rationale だけを残す -7. 主張と fact を骨子に配置し、形式ルールを適用する。既存 body・会話由来の文は session leak を - **文単位**で検査する -8. **適用前に「完了チェック」を1項目ずつ機械的に検査する**。書く行為と検査する行為を - 分けないと守れない +7. 主張と fact を骨子に配置し、形式ルールを適用する +8. 完了チェックを1項目ずつ機械的に検査する 9. `gh pr create --body-file ` または `gh pr edit --body-file ` で適用する 10. 以後 PR に commit を積んだら、What / Test に同じ規律で追記して同期する @@ -143,7 +130,6 @@ table は test 一覧・endpoint と契約の対応のように列の比較に - [ ] 各主張の直下に検証済みの根拠が1つ以上 nest されている - [ ] どの主張も支えない fact が Why に残っていない - [ ] 主張が user 確認済みか、既存 body / commit / 会話に根拠がある -- [ ] nest が Why 以外に無く、理由節が Notes 以外に無い - [ ] 恒久 fact が diff 内 doc と重複していない（PR は参照のみ） - [ ] 外部 SoT の値の snapshot に「現在値」の銘がある - [ ] Test の数値・コマンドが実装・再実行と照合済み diff --git a/skills/build-readme/SKILL.md b/skills/build-readme/SKILL.md index baf57ce..612cc52 100644 --- a/skills/build-readme/SKILL.md +++ b/skills/build-readme/SKILL.md @@ -5,9 +5,8 @@ description: > itself (code, terraform, actual behavior), composes sections from those facts, and writes one fact per bullet; decision rationale and internal how-it-works are left out. An existing README is broken down sentence by sentence and only facts verifiable against the - implementation survive. Format discipline is delegated to the writing-documents skill. Use - when creating, rewriting, condensing, or restructuring a README. Not for a few added lines - to an existing README — a normal edit covers that. + implementation survive. Use when creating, rewriting, condensing, or restructuring a README. + Not for a few added lines to an existing README — a normal edit covers that. --- # build-readme @@ -15,14 +14,8 @@ description: > README を「system が何であるか」の観測可能な事実の集合として書く。 決定の物語・レビューへの弁明・実装の how は README の管轄外（PR / ADR / code の管轄）。 -**形式の規律は `writing-documents` に委譲する。** allowlist で判定するという方法、3形式 -（bullet / table / code block）と paragraph 禁止、書き換え技法、1 fact = 1 home、共通の完了 -チェックはそちらが持つ。この skill が持つのは README 固有の allowlist・section composition・ -fact の収集経路・README 固有のチェックだけ。書き始める前に `writing-documents` を invoke する。 - -README の有無で変えるのは fact の収集経路だけ。新規作成では system から収集し、 -全面再構築では既存 README を文単位で解体して候補を救出する。 -どちらも同じ allowlist・section composition・形式・完了チェックを適用する。 +**形式の規律は `writing-documents` に委譲する。** この skill が持つのは README 固有の +allowlist・section composition・fact の収集経路・README 固有のチェックだけ。 ## ルール @@ -83,17 +76,12 @@ allowlist は「その fact を書いてよいか」、section は「読者が | `Troubleshooting` | 観測できる症状と読者が行う対処 | **Resources** は宣言、**Setup** は一度だけ行う操作、**Usage / Running** は繰り返す操作。 -前提・準備・日常操作を同じ section に混ぜない。順序に意味がある手順だけ ordered list を使う。 - -### 形式 — README 固有の適用 +前提・準備・日常操作を同じ section に混ぜない。 -`writing-documents` の3形式に従い、README ではさらに次を課す。 +### 形式 — README の例外宣言 - **paragraph の例外は h1 直下の lead 1-2文だけ。** section 内は例外なし - **理由節・nest の例外は宣言しない。** README では理由節が弁明の再侵入になる -- **table を選ぶのは列の比較に意味があるとき**（threshold 表・課金表など） -- **概要 table・目次を手で維持しない。** subsection 見出しの再述であり、機能の列挙は - `##`/`###` 見出し自体が担う ### 落ちる典型（allowlist が自動で弾くもの） @@ -124,17 +112,14 @@ allowlist は「その fact を書いてよいか」、section は「読者が 6. 読者自身が行う操作を抽出し、初回の準備・繰り返す操作・保守操作を区別する 7. allowlist を通った fact を読者の関心ごとに cluster 化し、section composition のルールと canonical section palette を使って header と順序を決める -8. 形式ルールを適用し、**提出前に「完了チェック」を1項目ずつ機械的に検査する** - （grep / 目視走査）。書く行為と検査する行為を分けないと守れない +8. 形式ルールを適用し、完了チェックを1項目ずつ機械的に検査する ## 完了チェック `writing-documents` の共通チェックに、以下を足して検査する。 -- [ ] prose が h1 直下の lead 1-2文に収まっている（section 内に paragraph がない） - [ ] 内容がない section や、固定骨子を埋めるためだけの section がない - [ ] 各 header が配下の fact に対する読者の関心を具体的に表している - [ ] 前提・一度だけ行う準備・繰り返す操作が同じ section に混ざっていない -- [ ] 概要 table・目次が subsection 見出しの再述になっていない - [ ] 読者が体感しない内部 config 値（batch window 等）が table や bullet に紛れていない - [ ] Cost がある場合、その数値・上限が実装と一致している diff --git a/skills/writing-documents/SKILL.md b/skills/writing-documents/SKILL.md index 955b3f1..3c3e324 100644 --- a/skills/writing-documents/SKILL.md +++ b/skills/writing-documents/SKILL.md @@ -7,9 +7,8 @@ description: > section (bullet, table, code block) with paragraphs banned, converts rationale into observable guarantees, and separates writing from a mechanical final check. Use when writing or fully rebuilding such a document, and when asked to strip prose, 地の文, - padding, or self-justification out of an existing draft. build-readme and - build-pr-description delegate this layer and add their own allowlist and skeleton; this - skill owns no document type of its own. + padding, or self-justification out of an existing draft. Owns no document type; + build-readme and build-pr-description delegate to it and add their own allowlist and skeleton. --- # writing-documents @@ -17,48 +16,33 @@ description: > 読者が行動するための fact を運ぶ document に共通の規律。 **この skill が持つのは判定の方法と形式だけで、document 型は持たない。** allowlist の中身・ -section 骨子・fact の収集経路は呼び出し側（`build-readme`・`build-pr-description` など）が定義する。 +section 骨子・fact の収集経路・削除テストの主体・形式の例外は呼び出し側 +（`build-readme`・`build-pr-description` など）が定義する。 単独で呼ばれた場合は、対象 document の読者と「読者が取る行動」を先に確定させてから適用する。 -## 呼び出し側との分担 - -| この skill が持つ | 呼び出し側が持つ | -| --- | --- | -| allowlist で判定するという方法 | allowlist の中身（許す文の種類） | -| 形式 — 3形式・paragraph 禁止・1 bullet 1 fact | section 骨子と header の決め方 | -| 書き換え技法 | fact の収集経路 | -| 削除テストの形 | 削除テストの主体（読者・reviewer・引き継ぎ先） | -| 共通の完了チェック | document 型固有の完了チェック | -| 例外を宣言できるという仕組み | 例外の宣言（理由節を許す section など） | - ## 判定 — allowlist で書く 悪い文の variation は無限にあるため、匂い狩り（denylist）ではなく**書いてよい文の allowlist** -で判定する。該当しない文は書かない。呼び出し側の allowlist が数種類の文型を列挙するので、 -候補の文をその型に照合し、どれにも当たらなければ落とす。 +で判定する。候補の文を呼び出し側が列挙する文型に照合し、どれにも当たらなければ落とす。 **削除テスト** — 判定に迷ったら: **その文を消したとき、読者の行動・期待・判断が変わるか？** 変わらないなら落とす。変わるなら残す。主体（読者か reviewer か）は呼び出し側が決める。 新規作成と全面再構築の差は **fact の収集経路だけ**。既存 document は文単位で allowlist に照合し、 -section や構成は継承しない。生き残った文だけを候補にする。既存の記載を「正しい記載」として -継承しない。 +生き残った文だけを候補にする。section・構成・記載の正しさは継承しない。 ## 形式 — section 内に置けるのは3形式のみ -- **bullet list** — 1 bullet = 1 fact。句点なし。「〜だが」「〜のため」で理由をぶら下げない - （bullet は接続詞を持てないので、弁明の再侵入を構文で防げる）。fact とは - **document の主題についての事実**。「以下は〜」のような document 自身への言及は - bullet に形を変えた paragraph であり、fact ではない。section の意味は見出しと配置で示す +- **bullet list** — 1 bullet = 1 fact。句点なし。「〜だが」「〜のため」で理由をぶら下げない。 + fact とは **document の主題についての事実**。section の意味は見出しと配置で示す - **table** — 各行が fact で、列の比較に意味があるとき bullet より優先する - （bullet 化すると比較可能性が落ちるもの） - **code block** — コピペして実行できる verbatim 成果物 **paragraph（地の文）は禁止。** ordered list は順序に意味がある手順だけに使う。 nest と理由節は、呼び出し側が section を名指しで例外宣言したときだけ使える。 -**1 fact = 1 home。** 同じ fact を2箇所に書かない。fact はそれが固有に属する場所に1回だけ書き、 -他所からは名前で参照する。手で維持する概要 table・目次は見出しの再述であり、drift の温床。 +**1 fact = 1 home。** fact はそれが固有に属する場所に1回だけ書き、他所からは名前で参照する。 +手で維持する概要 table・目次は見出しの再述であり、drift の温床。 ## 書き換え技法 @@ -81,23 +65,18 @@ nest と理由節は、呼び出し側が section を名指しで例外宣言し ## 落ちる典型 - **session leak** — 会話の文脈への言及・自己弁護 tone・「先ほどの指摘を反映し」型の編集履歴。 - document は成果物であり、それが作られた過程の記録ではない -- **meta-bullet** — 「以下は〜」「この section では〜」。document 自身についての言及は fact ではない - -## 手順への組み込み - -呼び出し側の手順に、次の2点を必ず含める。 - -1. 形式ルールの適用と、**提出前の完了チェックを1項目ずつ機械的に検査する行程** - （grep / 目視走査）。書く行為と検査する行為を分けないと守れない -2. 会話・既存 document 由来の文の session leak 検査を**文単位**で行う + document は成果物であり、それが作られた過程の記録ではない。会話・既存 document 由来の文は + **文単位**で検査する +- **meta-bullet** — 「以下は〜」「この section では〜」。document 自身への言及は + bullet に形を変えた paragraph であり、fact ではない ## 完了チェック（共通） -呼び出し側の document 型固有チェックに、以下を常に足す。 +提出前に、呼び出し側の document 型固有チェックと合わせて **1項目ずつ機械的に検査する** +（grep / 目視走査）。書く行為と検査する行為を分けないと守れない。 - [ ] paragraph（地の文）が1つも無い（呼び出し側が許した lead を除く） -- [ ] 各 bullet が単一の fact で、理由節をぶら下げていない（例外宣言された section を除く） +- [ ] 各 bullet が単一の fact で、nest・理由節が例外宣言された section 以外に無い - [ ] 「以下は〜」型の meta-bullet がない - [ ] 同じ fact が2箇所に書かれていない - [ ] 会話への言及・自己弁護 tone が残っていない