cognitive-load-minimizer

name	cognitive-load-minimizer
description	コードレビュー・リファクタ・アーキ判断・機能実装において、避けられる認知負荷（不要な頭の負担、浅い抽象、技巧的条件分岐、早すぎるレイヤー化、フレームワーク密結合、誤解を招くドメインモデル）を特定して削る。設計の単純化、レビュー、オンボーディング、保守性評価に使う。パフォーマンス調整、UIコピー編集、削れないドメイン複雑性には使わない。

認知負荷ミニマイザー

ソフトウェアから「避けられる」認知負荷を減らす。ドメイン由来の本質的複雑さは残し、将来の貢献者に不要なメンタルモデルの再構築を強いる表現・構造・アーキの選択だけを取り除く。

手順

ステップ1: タスク境界を決める

1. 変更の種類を特定する: コードレビュー、リファクタ、機能実装、アーキ判断、オンボーディング改善のいずれか。
2. 読み手のペルソナを決める: 新規コントリビュータ、隣チーム、将来の保守担当、QA、現機能オーナーなど。
3. 本質的複雑さと余計な複雑さを分ける:
   • 本質的: ドメインルール、正しさの要件、現実のスケール制約、データモデルの事実。
   • 余計な: 技巧表現、不要な間接化、浅い分割、独自マッピング、フレームワークの魔法、主観的なアーキ用語。
4. 混乱の原因がコード構造ではなくドメイン知識不足なら、コードをいじる前にドメインの事実を文書化する。

ステップ2: 負荷の発生源をスキャンする

1. アーキやリファクタの判断が絡むときは references/antipatterns.md を読む。
2. コードテキストを素早く当たりを付けたいときは python scripts/score-cognitive-load.py --path <ファイルまたはディレクトリ> を実行する。
3. スクリプトの出力はトリアージ用のみ。指摘ごとに周辺コードを読んで検証する。
4. 各指摘にカテゴリを1つ付ける:
   • 制御フロー負荷
   • 抽象化負荷
   • 結合負荷
   • プロトコル／マッピング負荷
   • フレームワーク／言語負荷
   • オンボーディング負荷

ステップ3: 低負荷の変形を優先する

1. 複雑な条件式は、名前のついた中間事実に置き換える。
2. ネストしたハッピーパスは、振る舞いとローカルなスタイルが保てるならガード節にする。
3. 親クラスを読まないと編集できない継承チェーンより、合成と明示的な協調を優先する。
4. インターフェースが実装より難しい浅いモジュールは、統合するかインライン化する。
5. 変化点が安定するまでは抽象を遅らせる。無関係な概念を結びつけるくらいなら小さな重複は残す。
6. 核となる業務ロジックはフレームワークのエントリポイントから独立させる。フレームワークオブジェクトは外側に寄せる。
7. 数値やトランスポート層の対応表を暗記させず、自己説明的なドメインコードを使う。
8. レイヤーは、本当に複雑さを隠すか、実用的な拡張点を守るときだけ足す。
9. DDD、クリーンアーキ、パターン名は、実際のドメイン言語と変更パスに従属させる。

ステップ4: 単純化を検証する

1. references/checklist.md で候補変更を評価する。
2. 既存テスト、絞った新規テスト、または明示的な手動確認計画で振る舞いの保持を確認する。
3. ファイル・スタック・サービス・頭の中の対応表をまたぐジャンプが減ったか確認する。
4. 新規参加者がエッジケースを読む前に主経路を把握できるか確認する。
5. 複雑さを別の場所に押し出しただけの「単純化」は却下する。

ステップ5: 結果を報告する

1. レビューコメントや設計メモには assets/review-template.md を使う。
2. まず具体的な認知負荷の源、次にそれより負荷の小さい置き換えを書く。
3. 好みの話は避け、変更ファイル、実行時振る舞い、オンボーディングコスト、デバッグの深さなど観測可能な根拠に寄せる。
4. リスクの低い削減が無い場合は、複雑さは本質的と見え、その根拠を明示する。

エラー処理

• ヒューリスティックで低信頼の指摘が多いときは、タスクで触ったファイルにスキャンを絞る。
• 提案した単純化が公開挙動を変えるなら止め、テストまたはプロダクト承認を要請する。
• ローカルなプロジェクト慣習とこのスキルが衝突するなら、公開インターフェースは維持し、安全な境界の内側で負荷を減らす。
• 抽象が浅く見えても安定した公開APIの一部なら、削除よりドキュメントや例を優先する。