Dimensional Analysis Skill

このスキルは、混合単位、精度、スケーリング係数を使って数値計算を実行するコードベースのための寸法分析パイプラインを編成します。メインのスキルコンテキストはワークフロー制御のみです。スキャン、用語集の発見、注釈、伝播、検証を専門の副エージェントに委譲し、その後バッチ処理、永続化、リトライ、カバレッジゲート、最終報告を管理します。

使用するとき

• コードベースに単位/寸法コメントを付加する（例：D18{tok}、D27{UoA/tok}）
• DeFi プロトコル、金融コード、科学計算での寸法分析を実行する
• 単位の不一致、スケーリング不足、精度損失による算術バグを探す
• 混合十進精度または固定小数点算術を含むコードベースを監査する

使用しないとき

• 数値算術または単位変換のないコードベース — 注釈を付けるものがありません
• 純粋な整数カウント論理（ループインデックス、配列長）で物理的または金融的寸法がない場合
• 単一の数式のみを簡単にチェックする必要がある場合 — 完全なパイプラインを実行する代わりにコードを直接読む方が良いです

実行モード

このスキルは 1 つのモードでのみ実行されます：full-auto。 これはワークフローベースのスキルで、Task ツールを使用してステップ固有の作業を専門エージェントに委譲します。全体的なプロセスを編成し、カバレッジと状態永続化を管理し、すべてのスコープ内ファイルがパイプラインの各ステップを処理されることを保証します。

• 常にこの順序で完全なパイプラインを実行します：Step 1 -> Step 2 -> Step 3 -> Step 4。
• メインスキルコンテキストは、専用の副エージェントが存在するときに、リポジトリ全体の寸法分析、注釈、伝播、またはバグ検証を自分自身で実行してはいけません。
• メインスキルコンテキストは、作業をルーティングし、プロンプトを構築し、状態を永続化し、完了を判断する場合にのみ、成果物、マニフェスト、副エージェント出力を検査できます。
• 呼び出し元によって提供されるモード引数は無視されます。
• すべての結果を最後に 1 つのサマリーで報告します。

ステップを開始するとき、以下を報告します：

Starting Step: Step {n}

スコープとカバレッジ保証

このスキルは、大規模リポジトリを含むすべてのスコープ内算術ファイルを監査する必要があります。

• スコープ内ファイルは Step 1 スキャナー出力（files 配列）によって定義され、すべての優先度レベル（CRITICAL、HIGH、MEDIUM、LOW）に渡っています。
• Step 1 が語彙発見用の入力を絞り込む場合（たとえば CRITICAL/HIGH のみ）、その絞り込みは発見のみに適用されます。注釈または検証スコープを決して削減しません。
• arithmetic-scanner は、スコープ内ファイルマニフェストを DIMENSIONAL_SCOPE.json としてプロジェクトルートに永続化し、そのマニフェストが Steps 2-4 の信頼できるソースです。
• ファイルは、3 つすべてのステータスが存在する場合にのみ完全にカバーされたと見なされます：
  • step2: アンカー注釈完了（または明示的な非アンカー結果）
  • step3: 伝播完了（または明示的な非伝播結果）
  • step4: 検証完了
• dimension-discoverer は、発見した寸法用語集を DIMENSIONAL_UNITS.md としてプロジェクトルートに永続化し、後続のステップと将来の実行で再利用します。
• ファイルが終端的な BLOCKED 状態で終わる場合、ブロック理由と再試行回数を DIMENSIONAL_SCOPE.json に永続化し、同じファイルを coverage.unprocessed_files に反映します。
• スコープ内ファイルがいずれかのステップで未処理のままである間は完了しません。

委譲契約

• arithmetic-scanner はリポジトリスキャン、算術ファイル優先順位付け、および DIMENSIONAL_SCOPE.json の作成を所有します。
• dimension-discoverer は寸法用語集の発見、単位推論、および DIMENSIONAL_UNITS.md の作成を所有します。
• dimension-annotator は注釈形式の決定、アンカーポイント編集、およびコメント作成動作を所有します。
• dimension-propagator は伝播ロジック、推論注釈、およびトレース中の不一致報告を所有します。
• dimension-validator はバグ検出、レッドフラグ評価、正当化拒否、および伝播不一致の確認または反論を所有します。
• メインスキルコンテキストは、スキップまたは起動されなかった副エージェントに対して自身の寸法推論を代替してはいけません。ステップが専門的推論を必要とする場合、対応する副エージェントを起動します。
• 参照ファイルを副エージェント支援材料として使用します。メインスキルコンテキストの指示として扱う代わりに、プロンプト内の関連ステップに渡します。

ワークフロー

これらのセクションを順番に実行します。現在のステップが完了ゲートを満たすまで進めません。

共有編成ルール

• DIMENSIONAL_SCOPE.json と DIMENSIONAL_UNITS.md はプロジェクトルートに存在します。
• メインスキルコンテキストは Step 1 成果物を検証しますが、Step 1 成果物自体を作成しません。
• DIMENSIONAL_SCOPE.json.in_scope_files は Steps 2-4 の信頼できるソースです。発見のみの入力から後続のスコープを導出しないでください。
• 後続のステップが終端的な BLOCKED に到達する場合、DIMENSIONAL_SCOPE.json のファイルエントリに一致する step*_reason および step*_retry_count フィールドを永続化します。
• coverage.unprocessed_files は DIMENSIONAL_SCOPE.json の終端的な BLOCKED エントリから導出される必要があり、{ "path": "...", "blocked_step": "step2|step3|step4", "reason": "...", "retry_count": 1 } を使用します。
• ステップは焦点を当てたプロンプトを使用して BLOCKED ファイルを 1 回再試行できます。それでも BLOCKED の場合は、文書化された理由を保持して続行します。ファイルが PENDING のままである間は終了しません。

Step 1: 用語集とスコープ発見

キャッシュされた成果物を再利用できない場合、リポジトリスキャンを arithmetic-scanner に委譲し、語彙発見を dimension-discoverer に委譲します。メインスキルコンテキストでそのステップ固有の分析を直接実行しないでください。

1. DIMENSIONAL_UNITS.md と DIMENSIONAL_SCOPE.json がプロジェクトルートに既に存在するかどうかを確認します。
2. 両者が存在する場合、それらを読み込み、以下を確認します：
   • DIMENSIONAL_SCOPE.json.project_root は現在のリポジトリルートと一致します
   • DIMENSIONAL_SCOPE.json には in_scope_files、discoverer_focus_files、recommended_discovery_order および ファイルごとの step2、step3、step4 フィールドが含まれます
   • DIMENSIONAL_UNITS.md はこのリポジトリの使用可能な寸法用語集です
3. いずれかの成果物が古い、形式が正しくない、必要な構造がない、または明らかに別のリポジトリのものである場合は、再利用を破棄して Step 1 の残りを再実行します。
4. 両者の成果物が有効な場合、直接再利用します。in_scope_files が空の場合は Steps 2-4 をスキップし、ゼロ件の検出結果を含む最終出力を生成します。
5. それ以外の場合は Task ツールを使用して arithmetic-scanner エージェントを生成します。そのプロンプトには以下を含める必要があります：
   • プロジェクトルートパス
   • DIMENSIONAL_SCOPE.json の絶対出力パス
   • Step 1 スコープマニフェストをディスクに書き込み、同じスコープデータをレポートで返すようにする指示
6. スキャナーは Step 1 スコープ永続化を所有します。以下を実行する必要があります：
   • 寸法算術ファイルを特定し、いつもどおり優先順位を付けます
   • project_root、in_scope_files、discoverer_focus_files および recommended_discovery_order を含む DIMENSIONAL_SCOPE.json を書き込みます
   • step2: "PENDING"、step3: "PENDING" および step4: "PENDING" を使用してすべてのスコープ内ファイルを初期化します
   • 算術ファイルが見つからない場合でも空のマニフェストを書き込みます
   • 50 を超える算術ファイルが見つかった場合、discoverer_focus_files を CRITICAL/HIGH に絞り込みながら、in_scope_files 内すべての優先度を保持します
7. スキャナーが完了した後、ディスクから DIMENSIONAL_SCOPE.json を読み込み、それが存在し、必要な Step 1 フィールドを含むことを確認してから続行します。
8. Task ツールを使用して dimension-discoverer エージェントを生成します。そのプロンプトには以下を含める必要があります：
   • プロジェクトルートパス
   • DIMENSIONAL_SCOPE.json への絶対パス
   • DIMENSIONAL_UNITS.md の絶対出力パス
   • 優先順位付きされた discoverer_focus_files（各ファイルのパス、優先度、スコア、カテゴリを含む）
   • recommended_discovery_order
9. 発見エージェントは Step 1 用語集永続化を所有します。DIMENSIONAL_SCOPE.json を Step 1 の信頼できるソースとして読み込み、Base Units、Derived Units および Precision Prefixes セクションを含む DIMENSIONAL_UNITS.md を書き込む必要があります。in_scope_files が空の場合、それでも同じ見出しを空のセクションで書き込む必要があります。
10. Step 1 は、両方の成果物がディスク上に存在し、上記の再利用チェックに合格し、ゼロファイル のケースを正しく表現する場合のみ完了です。発見エージェントが DIMENSIONAL_UNITS.md を書き込んだ後に in_scope_files が空の場合、Steps 2-4 をスキップし、ゼロ件の検出結果を含む最終出力を生成します。

Step 2: アンカー注釈

メインスキルコンテキストは自分自身で注釈を追加してはいけません。Task ツールを使用してすべてのアンカーポイント注釈作業用に dimension-annotator エージェントを生成します。完全な例と注釈形式の詳細については、[{baseDir}/references/annotate.md]({baseDir}/references/annotate.md) を参照してください。

• DIMENSIONAL_SCOPE.json を読み込み、in_scope_files からバッチを構築します。MEDIUM および LOW 優先度ファイルを含むすべてのスコープ内ファイルは、Step 2 の結果を受け取る必要があります。
• ファイルをバッチ処理します（ファイルごと 1 つのエージェントを生成する代わりに）：
  • <= 10 ファイル：1 つのバッチ
  • 11-30 ファイル：カテゴリごとに 1 つのバッチ
  • > 30 ファイル：カテゴリごとに 1 つのバッチ、10 ファイルより大きいカテゴリを約 8 ファイルのサブバッチに分割
• カテゴリを Step 1 推奨発見順で起動します：数学ライブラリ、次にオラクル、次にコアロジック、次に周辺機能。同じカテゴリ内のバッチは並列実行できます。
• アノテータを起動する前に、すべてのスコープ内ファイルに step2 = "PENDING" を設定し、更新された DIMENSIONAL_SCOPE.json を永続化します。
• 各注釈プロンプトには以下を含める必要があります：
  • DIMENSIONAL_UNITS.md への絶対パス
  • DIMENSIONAL_SCOPE.json への絶対パス
  • 割り当てられたファイルパス（順序通り）
  • 各ファイルのカテゴリとスキャナー出力からのマッチングパターン
  • 該当する場合、前のバッチから以前に注釈されたインターフェースまたは型の概要
  • 必要なファイルごとのステータス出力：ANNOTATED、REVIEWED_NO_ANCHOR_CHANGES または 1 行の正当化を含む BLOCKED
• 各バッチ後、各割り当てられたファイルを Step 2 ステータスに直ちに永続化します：
  • ANNOTATED
  • REVIEWED_NO_ANCHOR_CHANGES
  • BLOCKED
• ファイルが BLOCKED の場合は、step2_reason および step2_retry_count も永続化します。焦点を当てたプロンプトで各 BLOCKED ファイルを 1 回再試行します。
• ファイルがオンディスクマニフェスト状態で Step 2 に PENDING のまま残っている間は Step 3 に進みません。

Step 3: 寸法伝播

メインスキルコンテキストは伝播推論を自分自身で実行してはいけません。Task ツールを使用して dimension-propagator エージェントを生成し、算術、関数呼び出し、および割り当てを通じて注釈を拡張します。代数の詳細については、[{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md) を参照してください。

• DIMENSIONAL_SCOPE.json を読み込み、in_scope_files から伝播バッチを構築します。すべてのスコープ内ファイルは Step 3 の結果を受け取る必要があります。
• Step 2 と同じバッチ処理ルールとカテゴリ順序を使用します。
• 伝播エージェントを起動する前に、すべてのファイルが既に非PENDING Step 2 ステータスを持つことを確認します。
• 次に、すべてのスコープ内ファイルに step3 = "PENDING" を設定し、更新されたマニフェストを永続化します。
• 各伝播プロンプトには以下を含める必要があります：
  • DIMENSIONAL_UNITS.md への絶対パス
  • DIMENSIONAL_SCOPE.json への絶対パス
  • 割り当てられたファイルパス（順序通り）
  • 各ファイルのカテゴリとマッチングパターン
  • 割り当てられたファイルの Step 2 アンカー注釈とそれらが依存する任意のアップストリームインターフェースの概要
  • 必要なファイルごとのステータス出力：PROPAGATED、REVIEWED_NO_PROPAGATION_CHANGES または 1 行の正当化を含む BLOCKED
• 各バッチ後、各割り当てられたファイルを Step 3 ステータスに直ちに永続化します：
  • PROPAGATED
  • REVIEWED_NO_PROPAGATION_CHANGES
  • BLOCKED
• ファイルが BLOCKED の場合は、step3_reason および step3_retry_count も永続化します。焦点を当てたプロンプトで各 BLOCKED ファイルを 1 回再試行します。
• すべての伝播エージェントが完了した後、集計します：
  • 信頼度レベル別に追加された注釈（CERTAIN、INFERRED、UNCERTAIN）
  • 見つかった不一致（検証エージェント重複排除用の重大度付き）
  • 推論できなかったカバレッジ ギャップ
• ファイルがオンディスクマニフェスト状態で Step 3 に PENDING のまま残っている間は Step 4 に進みません。

Step 4: バグ検出

メインスキルコンテキストはバグ検出を自分自身で実行してはいけません。Task ツールを使用して dimension-validator エージェントを生成し、注釈付きコードの寸法バグを検出します。例、レッドフラグ、正当化チェック、標準用語集については、[{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md)、[{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md) および [{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md) を参照してください。他のステップではバグを検出しないでください。

• DIMENSIONAL_SCOPE.json.in_scope_files のすべてのファイルを検証します。
• この優先度順序を使用して、下位レベルをスキップしません：
  1. Step 3 の CRITICAL または HIGH 不一致を持つファイル
  2. 残りの CRITICAL および HIGH スキャナー優先度ファイル
  3. 残りの MEDIUM および LOW ファイル
• 検証エージェントを起動する前に、すべてのファイルが既に非PENDING Step 3 ステータスを持つことを確認します。
• 次に、すべてのスコープ内ファイルに step4 = "PENDING" を設定し、更新されたマニフェストを永続化します。
• ファイルごと 1 つの dimension-validator エージェントを生成します。大規模リポジトリの場合は、編成を安定に保つために約 10～30 ファイルの波で実行します。
• 各検証プロンプトには以下を含める必要があります：
  • DIMENSIONAL_UNITS.md への絶対パス
  • DIMENSIONAL_SCOPE.json への絶対パス
  • 検証する単一のファイルパス
  • ファイル内のアンカーおよび伝播注釈の概要
  • ファイルの Step 3 不一致サマリー（不一致 ID を含む）
  • 呼び出し境界チェックに必要なクロスファイル関数シグネチャまたは戻り値寸法
  • 必要なファイルごとのステータス出力：VALIDATED または BLOCKED
• 各波後、各ファイルを Step 4 ステータスに直ちに永続化します：
  • VALIDATED
  • BLOCKED
• ファイルが BLOCKED の場合は、step4_reason および step4_retry_count も永続化します。焦点を当てたプロンプトで各 BLOCKED ファイルを 1 回再試行します。
• 検出結果を重複排除します：
  • 確認された Step 3 不一致は元の ID と重大度を保持します
  • 反論された Step 3 不一致は偽陽性として記録され、最終カウントから除外されます
  • 新しく見つかった検出結果は新しい DIM-XXX ID を受け取ります
• 確認された検出結果、新しい検出結果、反論された検出結果、カバレッジサマリー、および最終 coverage.unprocessed_files を集計します。
• Step 4 は、DIMENSIONAL_SCOPE.json.in_scope_files に step4: "PENDING" エントリが含まれなくなった場合のみ完了です。

参照ドキュメント

ステップが必要な場合、これらの参照を関連する副エージェントに渡します：

• [{baseDir}/references/dimension-algebra.md]({baseDir}/references/dimension-algebra.md) - 伝播エージェントおよび検証エージェント代数ルール
• [{baseDir}/references/common-dimensions.md]({baseDir}/references/common-dimensions.md) - 検証エージェント用語集参照
• [{baseDir}/references/bug-patterns.md]({baseDir}/references/bug-patterns.md) - 検証エージェントバグパターンおよびレッドフラグ参照
• [{baseDir}/references/annotate.md]({baseDir}/references/annotate.md) - 注釈形式および例参照

最終出力

分析の最後に、他の出力形式が指定されていない限り、構造化されたサマリーを提供します：

{
  "mode": "full-auto",
  "project_root": "<path>",
  "vocabulary": {
    "base_units": ["..."],
    "derived_units": ["..."],
    "precision_prefixes": ["..."]
  },
  "annotations": {
    "total_added": 0,
    "by_file": {}
  },
  "findings": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "details": []
  },
  "uncertainties_resolved": 0,
  "coverage": {
    "in_scope_files": 0,
    "anchor_reviewed_files": "0/0",
    "propagation_reviewed_files": "0/0",
    "validation_reviewed_files": "0/0",
    "annotated_functions": "0/0",
    "annotated_variables": "0/0",
    "unprocessed_files": [
      {
        "path": "/path/to/repo/contracts/LegacyMath.sol",
        "blocked_step": "step3",
        "reason": "Parser could not process generated source",
        "retry_count": 1
      }
    ]
  }
}

完了チェックリスト

以下がすべて真の場合にのみ完了です：

ファイルカバレッジゲート

• DIMENSIONAL_UNITS.md がプロジェクトルートに存在する
• DIMENSIONAL_SCOPE.json がプロジェクトルートに存在し、ダウンストリームカバレッジの信頼できるソースです
• Step 1 で発見されたすべてのスコープ内算術ファイルが DIMENSIONAL_SCOPE.json.in_scope_files に表示されます
• すべてのスコープ内ファイルが非PENDING Step 2 ステータス（ANNOTATED、REVIEWED_NO_ANCHOR_CHANGES または BLOCKED）を持っています
• すべてのスコープ内ファイルが非PENDING Step 3 ステータス（PROPAGATED、REVIEWED_NO_PROPAGATION_CHANGES または BLOCKED）を持っています
• すべてのスコープ内ファイルが非PENDING Step 4 ステータス（VALIDATED または BLOCKED）を持っています
• スコープ内ファイルがいずれかのステップで PENDING のままではない
• すべての BLOCKED ファイルが最終出力で文書化された理由を持っています
• coverage.unprocessed_files は、path、blocked_step、reason および retry_count を使用して、再試行後の最終的な終端的 BLOCKED ファイルのセットと正確に一致します

サマリーレポート

• 最終サマリー JSON/レポートが提供されます
• 最終カバレッジカウンタが DIMENSIONAL_SCOPE.json と一致する
• 編集が行われた場合に変更されたファイルのリストが提供されます
• 見つかった寸法の不一致またはバグが要約されます
• 残っているブロックされたファイルまたは未処理ファイルが理由を含めて呼び出されます

DIMENSIONAL_SCOPE.json と最終レポートが異なる場合、レポートを調整するか処理を続行して一致するまで行ってください。 エージェント意図のみから完了を主張しないでください。完了はマニフェストカバレッジと最終報告ステータスによって決定されます。