humanize-beagle

Humanize

以前の review-ai-writing の実行結果から、修正を適用します。自動で安全性とリスクを分類します。docs-style のライティング原則に基づいています。

使い方

必要に応じてフラグを指定し、humanize-beagle スキルを呼び出します：humanize-beagle [--dry-run] [--all] [--category <name>]。

フラグ：

• --dry-run - ファイルを変更せず、修正内容を表示します
• --all - コードベース全体を修正します（最初に --all を指定してレビューを実行します）
• --category <name> - 特定のカテゴリのみを修正します：content|vocabulary|formatting|communication|filler|code_docs

手順

必須ゲート

破壊的な手順や証拠が必要な手順に進むのは、各 PASS 条件が満たされている場合に限ります（コマンドと生成物で確認します。「頭の中で確認した」は不可です）。

1. G1 — ファイルを安全に編集できる — PASS： git status --porcelain の出力が空である、または git stash push -u -m "beagle-docs: pre-humanize backup" が終了コード 0 で終了する。
2. G2 — レビュー入力が実際の JSON で、想定される構造である — PASS： .beagle/ai-writing-review.json が存在し、JSON として解析でき、git_head キーと（空の場合もある）配列の findings 値がある。手順 3 の jq -e コマンド、または Python の json.load を使った同等のチェックを実行します。失敗した場合は、解析／検証エラーで停止し、修正を適用しないでください。
3. G3 — 書き換え前に参照資料を確認する — PASS： 編集する各指摘について、そのカテゴリ／タイプに応じて手順 4 で必要となる references/*.md ファイルを、テキストを変更する前にこのセッションで読みます。
4. G4 — ファイルごとの検証 — PASS： 変更したファイルはすべて、タイプに応じた手順 8 のチェックに合格する必要があります。合格しない場合は、そのファイルに対して git checkout -- "$file" を実行し、概要で OK として記載しないでください。
5. G5 — すべて正常に完了した場合のみレビュー ファイルを削除する — PASS： 検証に失敗したファイルを変更せずに残す場合は、すべてのファイルで G4 が成立しているときに限り rm .beagle/ai-writing-review.json を実行します（手順 10 に準拠）。

1. 引数の解析

$ARGUMENTS からフラグを抽出します：

• --dry-run - プレビューのみ
• --all - コードベース全体をスキャン
• --category <name> - 特定のカテゴリに絞り込み

2. 事前安全確認

# Check for uncommitted changes
git status --porcelain

作業ディレクトリに変更がある場合は、警告します：

Warning: You have uncommitted changes. Creating a git stash before proceeding.
Run `git stash pop` to restore if needed.

変更がある場合は、stash を作成します：

git stash push -u -m "beagle-docs: pre-humanize backup"

G1 PASS： 作業ツリーがすでにクリーンであるか、stash コマンドが終了コード 0 で終了していること。

3. レビュー結果の読み込み

既存のレビュー ファイルを確認します：

cat .beagle/ai-writing-review.json 2>/dev/null

ファイルがない場合：

• --all フラグがある場合：最初に --all を指定して review-ai-writing スキルを呼び出します
• それ以外の場合：次のメッセージを表示して失敗とします："レビュー結果が見つかりません。最初に review-ai-writing スキルを呼び出してください。"

ファイルがある場合は、JSON の形式と鮮度を検証します（G2）：

# Required shape: parseable JSON with git_head and findings array (may be empty)
jq -e 'has("git_head") and ((.findings // []) | type == "array")' .beagle/ai-writing-review.json >/dev/null 2>&1 \
  || { echo "Invalid or incompatible ai-writing-review.json"; exit 1; }

# Get stored git HEAD from JSON
stored_head=$(jq -r '.git_head' .beagle/ai-writing-review.json)
current_head=$(git rev-parse HEAD)

if [ "$stored_head" != "$current_head" ]; then
  echo "Warning: Review was run at commit $stored_head, but HEAD is now $current_head"
fi

古い場合は、次のメッセージを表示します："レビュー結果が古くなっています。レビューを再実行しますか？（y/n）"

4. 参照資料の読み込み

修正対象の指摘に応じて、適切な参照ファイルを読みます：

• ai_vocabulary_high または ai_vocabulary_low の修正を適用する場合は、references/vocabulary-swaps.md を読みます
• どのカテゴリでも、戦略の詳細と修正前後の例については references/fix-strategies.md を読みます
• 文章を書き換える場合は、トーンや文体の指針として references/developer-voice.md を読みます

必要なものだけを読み込みます。語彙のみを修正する場合は、文体ガイドを読み飛ばしてください。

5. 指摘事項をフィルタリングする

--category が設定されている場合、そのカテゴリの指摘事項だけに絞り込みます。

残りの指摘事項を fix_safety で分類します。

安全に適用できる修正（自動適用）：

• chat_leak - 会話の痕跡を削除する
• cutoff_disclaimer - 知識のカットオフに関する言及を削除する
• filler_phrase - 埋め草の表現を削除する
• heading_restatement - 最初の文を言い換えた見出しを削除する
• emoji_decoration - 技術文書から絵文字を削除する
• boldface_overuse - 過剰な太字の書式を取り除く
• ai_vocabulary_high - AI を強く連想させる語句を置き換える
• narrating_obvious - 自明なコードコメントを削除する
• synthetic_opener - 「In today's...」で始まる導入文を削除する
• sycophantic_tone - 賞賛を削除するか、中立的な表現にする
• vague_authority - 出典のない主張を削除する
• excessive_hedging - 限定表現を取り除く
• generic_conclusion - 内容のない要約を削除する
• copula_avoidance - 「is/are」を自然に使う
• rhetorical_device - 修辞的な質問を削除する
• em_dash_overuse - 定型的なダッシュをカンマ、丸括弧、コロンに置き換える
• thematic_break - 見出しの前の水平線を削除する
• title_case_heading - AI 風のタイトルケースの見出しを文頭大文字の形式に変換する
• curly_quotes - 曲線引用符やアポストロフィを通常のものに統一する
• negative_parallelism - 「Not just X, but also Y」のような埋め草の構文を削除する
• challenges_and_prospects - 「Despite its... faces challenges...」のような定型的な前置きを削除する

要確認の修正（確認が必要）：

• promotional_language - 具体的な内容を使って書き直す
• formulaic_structure - セクションの構成を変更する
• synonym_cycling - 一貫した用語を選ぶ
• commit_inflation - コミットの範囲を書き直す
• tautological_docstring - docstring を書き直すか削除する
• exhaustive_enumeration - パラメーターの説明を簡潔にする
• this_noun_verbs - docstring の文体を書き直す
• ai_vocabulary_low - AI を連想させる語句の集中を抑える
• apologetic_error - エラーメッセージを書き直す
• rule_of_three - 網羅性を装う埋め草として使われる3項目のリストを簡潔にする
• inline_header_list - 太字のインライン見出しを使った縦並びリストを再構成する
• unnecessary_table - 小さな表を文章に変換する
• regression_to_mean - 曖昧な賞賛に置き換えられた具体的な事実を元に戻す

6. 安全に適用できる修正を適用する

--dry-run の場合：

## Safe Fixes (would apply automatically)

| # | File | Line | Type | Action |
|---|------|------|------|--------|
| 1 | README.md | 3 | synthetic_opener | Delete "In today's rapidly evolving..." |
| 2 | src/auth.py | 15 | narrating_obvious | Delete "# Check if user exists" |
| 3 | README.md | 42 | ai_vocabulary_high | Replace "utilize" with "use" |
...

それ以外の場合は、ファイル I/O を最小限にするため、ファイルごとにまとめて修正を適用します。

1. 指摘事項をファイル名、次に行番号の降順で並べ替えます（オフセットのずれを防ぐため）
2. 各ファイルについて、安全に適用できる修正を行番号の逆順で適用します
3. Git の成果物（git:commit:*、git:pr:*）はスキップします。これらは自動修正できません。手動対応が必要なものとして報告します。

7. 要確認の修正を処理する

--dry-run の場合は、一覧表示します。

## Needs Review Fixes (would prompt interactively)

| # | File | Line | Type | Original | Suggested |
|---|------|------|------|----------|-----------|
| 4 | README.md | 8 | promotional_language | "powerful, enterprise-grade solution" | "authentication library" |
...

それ以外の場合は、修正ごとに対話形式で確認を求めます。

[README.md:8] Promotional language: "powerful, enterprise-grade solution"
Suggested: "authentication library"
(y)es / (n)o / (e)dit / (s)kip all:

ユーザーの選択を記録します。

• y - 提案された修正を適用する
• n - この修正をスキップする
• e - ユーザーが置換内容を指定する
• s - 残りの対話形式の修正をすべてスキップする

8. 結果を検証する

変更した Markdown ファイルごとに、基本的な妥当性を確認します。

# Check for broken markdown (unclosed code blocks, broken links)
# Simple check: matching ``` pairs
grep -c '```' "$file" | awk '{print ($1 % 2 == 0) ? "OK" : "WARNING: odd number of code fences"}'

変更したソースファイルについては、構文が引き続き有効であることを確認します。

Python：

python3 -c "import ast; ast.parse(open('$file').read())"

TypeScript/JavaScript：

npx -y acorn --ecma2020 "$file" > /dev/null 2>&1

いずれかのファイルで検証に失敗した場合、そのファイルを元に戻します。

git checkout -- "$file"
echo "Reverted $file due to validation failure"

9. 結果を報告する

## Humanize Summary

### Applied Fixes
- [x] README.md:3 - Deleted synthetic opener
- [x] README.md:42 - Replaced "utilize" with "use"
- [x] src/auth.py:15 - Deleted obvious comment

### Interactive Fixes
- [x] README.md:8 - Rewrote promotional language (user approved)
- [ ] docs/guide.md:22 - Skipped by user

### Skipped (Git Artifacts)
- [ ] git:commit:abc1234 - Chat leak in commit message (amend manually)

### Validation
- README.md: OK
- src/auth.py: OK

### Diff Summary

git diff --stat

10. クリーンアップ

すべての検証に合格して正常に完了した場合：

rm .beagle/ai-writing-review.json

検証に失敗したものがある場合は、ファイルを残して報告します。

Review file preserved at .beagle/ai-writing-review.json
Fix issues and re-run, or restore with: git stash pop

中核となる原則

1. まず削り、次に書き直します。 AI がよく使う表現の多くは余分です。削ることで文章が改善します。
2. 簡単な言葉を使います。 「utilize」は「use」に、「facilitate」は「help」に、「implement」は「add」に置き換えます。
3. 文は短くします。 複文は分けます。1文につき、考えは1つにします。
4. 意味を保ちます。 文章の内容は変えず、表現だけを変えます。
5. 文体を合わせます。 コミットメッセージは簡潔にします。README は親しみやすくします。API ドキュメントは正確にします。文体ガイドの全文は references/developer-voice.md を参照してください。
6. 過剰に修正しません。 少し堅い文でも問題ありません。明らかに AI が生成したように読めるパターンだけを修正します。
7. 平均への回帰を理解します。 LLM は統計的に最も可能性の高い出力を生成します。具体的で珍しい事実は、一般的で肯定的な説明に置き換えられがちです。人間らしい文章にする際は具体性を取り戻し、曖昧な称賛を具体的な詳細に置き換えます。
8. 個々の単語ではなく、密度を評価します。 AI が使いがちな語彙は、一緒に現れる傾向があります。1～2語なら偶然かもしれませんが、3語以上がまとまって現れるのは、AI 生成の強い兆候です。

例

フラグを指定して humanize-beagle スキルを実行します。

• --dry-run — 適用せずに、すべての修正をプレビューします
• --category vocabulary — 語彙の問題だけを修正します
• --all — コードベース全体をスキャンして修正します
• --category filler --dry-run — 余分な表現の修正だけをプレビューします

ルール

• 修正を適用する前に、必ず参照資料を読み込みます（ステップ 4）。各指摘について G3 を満たしてください
• 作業ツリーがクリーンであるか、stash が正常に完了していない限り、ファイルを変更しないでください（G1）
• オフセットのずれを避けるため、安全な修正は行番号の降順で適用します
• Git の成果物（コミット、PR）は自動修正しないでください。手動対応が必要なものとして報告します
• 修正したすべてのファイルを、完了と見なす前に検証します（G4）
• 検証に失敗したファイルは元に戻します
• 保持するすべてのファイルについてステップ 8 の検証が通るまで、ステップ 9 の要約を「完了」として提示しないでください
• .beagle/ai-writing-review.json は、すべての作業が正常に完了した後にのみ削除します（G5）。途中で検証に失敗した場合はファイルを残し、ステップ 10 に従ってください