humanize

Humanize

以前の review-ai-writing の実行結果から、安全／要確認を自動分類して修正を適用します。

使用方法

/beagle-docs:humanize [--dry-run] [--all] [--category <name>]

フラグ：

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

手順

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.

変更がある場合は、スタッシュを作成します：

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

3. レビュー結果を読み込む

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

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

ファイルがない場合：

• --all フラグが指定されている場合：最初に /beagle-docs:review-ai-writing --all を実行します
• それ以外の場合：次のエラーを表示して終了します："レビュー結果が見つかりません。最初に /beagle-docs:review-ai-writing を実行してください。"

ファイルがある場合は、最新かどうかを検証します：

# 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. スキルを読み込む

Skill(skill: "beagle-docs:humanize")

5. 指摘事項を絞り込む

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

残りの指摘事項を fix_safety によって分類します：

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

• chat_leak - 会話の痕跡を削除
• cutoff_disclaimer - 知識のカットオフに関する記述を削除
• filler_phrase - 埋め草の表現を削除
• heading_restatement - 最初の文を言い換えただけの見出しを削除
• emoji_decoration - 技術的な文章から絵文字を削除
• boldface_overuse - 過剰な太字書式を削除
• ai_vocabulary_high - AI 特有の傾向が強い単語を置き換え
• narrating_obvious - 明白なコードコメントを削除
• synthetic_opener - 「今日の…」で始まる書き出しを削除
• sycophantic_tone - 賞賛表現を削除または中立的な表現に変更
• vague_authority - 出典のない主張を削除
• excessive_hedging - 断定を避ける表現を削除
• generic_conclusion - 内容の薄いまとめを削除
• copula_avoidance - 「is/are」を自然に使用
• rhetorical_device - 修辞疑問文を削除

確認が必要な項目（確認してから適用）：

• promotional_language - 具体的な内容に書き換え
• formulaic_structure - セクション構成を変更
• synonym_cycling - 用語を統一
• commit_inflation - コミットの範囲を修正
• tautological_docstring - docstring を書き換えるか削除
• exhaustive_enumeration - パラメーターの説明を簡潔にする
• this_noun_verbs - docstring の文体を書き換え
• ai_vocabulary_low - 特徴的な単語の集中度を下げる
• apologetic_error - エラーメッセージを書き換え

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

例

# Preview all fixes without applying
/beagle-docs:humanize --dry-run

# Fix only vocabulary issues
/beagle-docs:humanize --category vocabulary

# Full codebase scan and fix
/beagle-docs:humanize --all

# Preview filler fixes only
/beagle-docs:humanize --category filler --dry-run

ルール

• 最初に必ず beagle-docs:humanize スキルを読み込みます
• スタッシュがない場合や、作業ディレクトリがクリーンでない場合は、ファイルを変更しません
• オフセットのずれを避けるため、安全な修正は行番号の降順で適用します
• Git の成果物（コミット、PR）は自動修正せず、手動対応が必要なものとして報告します
• 変更したファイルはすべて、完了とみなす前に検証します
• 検証に失敗したファイルは元に戻します
• 概要を表示する前に、JSON レポートを書き込みます
• すべて成功した場合に限り、JSON レポートを削除します

参考資料

開発者向けテキストのヒューマナイズ

ドキュメント、docstring、コミットメッセージ、PR の説明、コードコメントに含まれる、AI が生成したような文章のパターンを修正します。書き換えより削除を優先します。冗長な表現は削除するのが最善です。

基本原則

1. まず削除し、次に書き換えます。 AI らしい表現の多くは水増しです。削除すれば文章が改善します。
2. 簡単な言葉を使います。 「utilize」は「use」に、「facilitate」は「help」に、「implement」は「add」に置き換えます。
3. 文を短くします。 複文は分割し、1 文につき 1 つの考えを述べます。
4. 意味を保ちます。 内容は変えず、表現だけを変えます。
5. 文体を合わせます。 コミットメッセージは簡潔に、README は親しみやすく、API ドキュメントは正確にします。
6. 過剰に修正しません。 少し形式的な文は問題ありません。明らかに AI らしく見えるパターンだけを修正します。

カテゴリ別の修正方法

内容に関するパターン

種類	方法	リスク
宣伝文句	最上級の表現を具体的な説明に置き換えます	要確認
根拠の曖昧な主張	主張を削除するか、引用を追加します	安全
定型的な構成	前置きや結びの定型文を削除します	要確認
不自然な書き出し	書き出しを削除し、本題から始めます	安全

修正前：

In today's rapidly evolving software landscape, authentication is a crucial
component that plays a pivotal role in securing modern applications.

修正後：

This guide covers authentication setup for the API.

語彙に関するパターン

種類	方法	リスク
AI らしさが強い単語	単語を直接置き換えます	安全
AI らしさが弱い単語の多用	使用頻度を減らし、1～2 個にとどめます	要確認
コピュラの回避	「is／are」を自然に使います	安全
修辞的な表現	質問を削除し、事実を述べます	安全
類義語の使い回し	用語を 1 つに決め、一貫して使います	要確認
コミットメッセージの誇張	実際の変更範囲に合うよう書き換えます	要確認

単語の置き換え例：

AI らしい単語	置き換え
utilize	use
leverage（「use」の意味で使う場合）	use
delve	look at、explore、examine
facilitate	help、enable、let
endeavor	try、work、effort
harnessing	using
paradigm	approach、model、pattern
whilst	while
furthermore	also、and
moreover	also、and
robust（技術的でない意味の場合）	reliable、solid、strong
seamless	smooth、easy
cutting-edge	modern、latest、new
pivotal	important、key
elevate	improve
empower	let、enable
revolutionize	change、improve
unleash	release、enable
synergy	（削除。意味を持つことはほとんどありません）
embark	start、begin

修正前：

feat: Leverage robust caching paradigm to facilitate seamless data retrieval

修正後：

feat: add response caching for faster reads

書式に関するパターン

種類	方法	リスク
太字の過剰使用	重要でない用語の太字を解除します	安全
絵文字による装飾	技術的な文章から絵文字を削除します	安全
見出しの言い換え	見出しを繰り返す文を削除します	安全

修正前：

## Error Handling

**Error handling** is a **critical** aspect of building **reliable** applications.
The `handleError` function **catches** and **processes** all **runtime errors**.

修正後：

## Error Handling

The `handleError` function catches runtime errors and logs them with context.

コミュニケーションに関するパターン

種類	方法	リスク
チャット由来の文言	すべて削除します	安全
文章の打ち切りに関する免責	すべて削除します	安全
迎合的な表現	削除するか、中立的な表現にします	安全
謝罪を含むエラーメッセージ	直接的なエラーメッセージに書き換えます	要確認

修正前：

# Great implementation! This elegantly handles the edge case.
# As of my last update, this API endpoint supports JSON.

修正後：

# Handles the re-entrant edge case from issue #42.
# This endpoint accepts JSON.

冗長な表現に関するパターン

種類	方法	リスク
冗長なフレーズ	そのフレーズを削除します	安全
過度な婉曲表現	限定的な表現を削除し、直接述べます	安全
ありきたりな結論	結論の段落を削除します	安全

修正前：

It's worth noting that the configuration file might potentially need to be
updated. Going forward, this could possibly affect performance.

修正後：

Update the configuration file. This affects performance.

コードドキュメントのパターン

種類	方針	リスク
トートロジーになっている docstring	削除するか、実質的な情報を追加する	要確認
明白なコードの説明	コメントを削除する	安全
「この名詞は動詞する」	能動態または直接的な表現に書き換える	安全
網羅的な列挙	明白でないパラメーターだけ残す	要確認

修正前：

def get_user(user_id: int) -> User:
    """Get a user.

    This method retrieves a user from the database by their ID.

    Args:
        user_id: The ID of the user to get.

    Returns:
        User: The user object.

    Raises:
        ValueError: If the user ID is invalid.
    """
    return db.query(User).get(user_id)

修正後：

def get_user(user_id: int) -> User:
    """Raises UserNotFound if ID doesn't exist in the database."""
    return db.query(User).get(user_id)

開発者向けの文体ガイドライン

優れた開発者向けの文章は、次のような特徴があります。

• 会話調でありながら正確です。 同僚に説明するように書きつつ、細部を正しく記述します。
• 直接的です。 意見を明確に述べます。「X を使う」と書き、「X の使用を検討してもよいでしょう」とは書きません。
• 必要に応じて簡潔です。 コミットメッセージとコードコメントは短くします。余計な言葉を加えません。
• 具体的です。 あいまいな主張を、具体的な詳細、数値、例に置き換えます。
• 一貫性があります。 用語を一つ選び、使い続けます。同義語を次々と使いません。

文体のガイド

成果物	トーン	長さ	例
コミットメッセージ	簡潔、命令形	50～72 文字	fix: prevent nil panic in auth middleware
コードコメント	簡潔、理由を説明	1～2 行	// retry once — transient DNS failures are common in k8s
Docstring	正確で、有用な情報を追加	名前だけでは分からない内容	"""Raises ConnectionError after 3 retries."""
PR の説明	構造的、事実に基づく	背景＋変更内容＋テスト方法	段落ではなく箇条書き
README	会話調で、読み取りやすい	できるだけ短く	まず機能を説明し、次に使い方を説明する
エラーメッセージ	具体的で、対処方法が分かる	発生したこと＋対応方法	Config file not found at ~/.app/config.yml. Run 'app init' to create one.

修正の適用

安全な修正（自動適用）

これらは機械的に適用でき、人による確認は不要です。

• チャット由来の不要な表現を削除する（「もちろんです！」「良い質問ですね！」）
• 期限を設ける免責文を削除する（「私の最終更新時点では」）
• 埋め草の表現を削除する（「注目すべき点として」）
• 見出しの内容を繰り返す記述を削除する
• 技術文書から絵文字を削除する
• 過剰な太字を削除する
• 意味が曖昧な AI 用語を、意味が明確な語に置き換える（utilize → use）
• 「ご覧のとおり」や「見てみましょう」を削除する
• 明白なコードを説明するコメントを削除する

要確認の修正（対話形式）

これらは、置き換え後も意図が保たれているか、人による確認が必要です。

• 宣伝文句を書き換える（ドメイン知識が必要な場合があります）
• 同義語の使い分けを修正する（適切な用語を選ぶ必要があります）
• トートロジーになっている docstring を書き換える（何を記録する価値があるか判断する必要があります）
• 網羅的なパラメーターの説明を簡潔にする（どのパラメーターが明白でないか判断する必要があります）
• コミットメッセージを書き換える（変更範囲を判断する必要があります）
• 定型的なセクションを再構成する（文書の流れが変わる場合があります）
• 謝罪を含むエラーメッセージを修正する（UX に影響する表現です）