writing-prose

散文の執筆

ルールは rules/ にあり、それぞれ1文で、IDとティアが付いています。

• F（完全）：check.sh が判定し、指摘は確定です。
• H（ヒューリスティック）：check.sh が候補を出力し、確認するか却下します。
• M（モデル）：ルールを読んで判断します。

対象

まず対象を指定します。chat、ticket、tracker（プルリクエストの本文とコメント）、markdown、skill、primed（すべてのセッションで読み込まれるファイル）、comment（コードコメントとヘルプテキスト）、または commit です。 check.sh --rules <surface> で、その対象が読み込むルールファイルを確認できます。

手順

1. 対象のルールファイルを読みます。
2. 下書きを作成します。 書き直す場合は、古いブロックを読み、ルールに基づいて新たに下書きしてから、古い文章を削除します。 古い文を部分的に修正してはいけません。
3. check.sh <surface> <file> を実行します。 書き直しの場合は --before <old-file> を追加します。ファイルに - を指定すると、標準入力から読み込みます。 F の指摘をすべて修正します。 H の候補をすべて確認するか却下し、確認したものを修正します。
4. 実行の最後に表示される M の各ルールを判断します。
5. 手順3と4を繰り返します。 2回目以降は、指摘箇所をその場で修正します。
6. レイアウト規則を読み込む対象では、最後にレイアウトを整えます。 内容が合格したら、意味のまとまりに沿って改行を入れ、手順3をもう一度実行します。 内容の作業で変更されなかった行の折り返し直しはリフローです。独立したスタイルコミットに含め、--style を指定して確認します。 依頼で内容のレビューより先にレイアウト調整を求められた場合は、この手順に反することを責任者に伝え、開始前に確認を求めます。

check.sh が終了コード0を返し、すべての H 候補に決着がつき、M のルールに違反していなければ、そのテキストは合格です。 2回目の実行後も未解決の M の指摘は、3回目の実行に進めず、報告として責任者に伝えます。

レビュー担当者

• F と H のルール：執筆のたびに、すべての対象で check.sh が確認します。
• チケット、トラッカーのテキスト、プルリクエストの本文に適用される M のルール：投稿前にサブエージェントがレビューします。 サブエージェントに渡されるのは、テキスト、対象、ルールだけです。 自分の文脈では、対象読者のずれを見逃し、コンプライアンスに関する主張を鵜呑みにしがちです。 サブエージェントを利用できない場合は、自分でレビューし、その旨を伝えます。
• プルリクエスト内のリポジトリファイルに適用される M のルール：プロジェクトの文章レビューで確認します。 それがない場合は、サブエージェントがレビューします。

チャットではサブエージェントを使いません。 執筆しながらルールを適用します。