Dark Matter Analyzer

ダークマターアナライザー

目的

ダークマターモードは、リポジトリやコードベースにおける見えないもの、語られないもの、測定されないものを明らかにします。コード品質の指標にとどまらず、システムの振る舞いを形作る目に見えないアーキテクチャに光を当て、従来のツールでは見逃される戦略のずれ、ドキュメントの肥大化、実行ギャップ、組織の健全性に関するパターンを特定します。

「すべてのリポジトリは、可視化された心の姿です。」

このスキルは、技術的に何が問題なのかだけでなく、リポジトリに違和感を覚える理由の診断に役立ちます。

このスキルを使用する場面

• リポジトリに一貫性がないように感じるものの、従来の指標には問題が見られない
• ドキュメントは充実しているのに、チームの混乱が解消されない
• 表明された目標と、実際に行われている作業が一致していない
• コードベースの構造に見られる組織のパターンを理解する必要がある
• プロジェクトの進捗は速いが、一貫性が低いと感じられる
• 計画が実行を大幅に上回っている
• 同じトピックを扱うドキュメントが複数重複している
• 「リポジトリ一貫性指数」（RCI）を評価する必要がある
• 大規模なリファクタリングや再編成を準備している
• 使用しない場面： 単純なバグ修正、機能追加、標準的なコードレビュー

中核となる方法論

ステップ 1：センシング — シグナルの取り込み

目的： リポジトリから周辺的なシグナルとメタデータを取得します

アクション：

1. コードのシグナルをスキャンする： コミットのパターン、リファクタリングの頻度、lint の抑制、TODO/FIXME マーカー
2. ドキュメントのシグナルをスキャンする： README の乖離、重複する .md ファイル、ドキュメント数とコードの比率
3. 時間的なシグナルをスキャンする： 意思決定から実行までの時間差、機能の進捗速度
4. 環境のシグナルをスキャンする： 依存関係の健全性、ビルドの状態、テストカバレッジの推移

主な判断事項：

• 範囲：リポジトリ全体、または特定のサブシステム？
• 深さ：クイックスキャン（3 階層）、または詳細分析（すべてのファイル）？
• 除外対象：スキップするもの（node_modules、dist、vendor）は？

よくある落とし穴：

• ❌ コード指標だけを見る → ✅ ドキュメントと時間的なパターンも含める
• ❌ パターンを「エラー」と判断する → ✅ システムに現れた表現として捉える
• ❌ 孤立した状態で分析する → ✅ 表明された意図と観察された振る舞いを比較する

使用するツール：

# Count documentation files
find . -name "*.md" -type f | wc -l

# Find technical debt markers
grep -r "TODO\|FIXME\|HACK" --include="*.ts" --include="*.js"

# Check commit patterns
git log --oneline --since="1 month ago" | head -20

# Find documentation inflation
find DOCS -name "*.md" -exec wc -l {} \; | awk '{sum+=$1} END {print sum}'

ステップ 2：パターン検出 — 弱いシグナルのマッピング

目的： 微妙な不整合を、大きな問題になる前に特定します

アクション：

1. パターンを既知のカテゴリ（戦略のずれ、ドキュメントの肥大化、抑制など）にマッピングする
2. パターンの強度（頻度、範囲、直近性）を算出する
3. パターンのクラスター（関連する複数のシグナル）を特定する
4. 感情的な含意（そのパターンがチームの状態について示すこと）を評価する

パターンのカテゴリ：

パターンの種類	シグナルの例	考察に基づく解釈
戦略のずれ	README ≠ コミットの活動状況	ビジョンとの乖離、または早すぎる方針転換
ドキュメントの肥大化	類似した .md ファイルが多数ある	過剰な計画、執筆による回避
抑制パターン	eslint-disable や any が多数ある	時間的なプレッシャーや疲労
依存関係の凍結	数か月間、更新がない	破損への恐れ、または変化への抵抗
コミットの乱高下	急速な取り消し	外部からのプレッシャー、または内部の落ち着かなさ
タスクと現実の乖離	テストは通るが、機能が未完成	有用性ではなく、構造の検証
実行の不足	ドキュメント >> 実装	希望主導の開発

検証：

• 少なくとも 3 つの異なるパターンを特定している
• 各パターンに具体的な証拠がある
• パターンが一貫したストーリーを示している
• 感情的な含意を特定している

ステップ 3：内省 — 意味の抽出

目的： パターンを、実践的な解釈を伴う物語的な洞察へと変換します

アクション：

1. 各パターンについて、技術的な内容と人間的な意味の対応関係を示します
2. 各洞察の内省における確信度（0.0-1.0）を評価します
3. 解釈における謙虚さを示す不確実性指数を算出します
4. 「見えていないもの」（存在しているが、目に見えないもの）を特定します
5. 「語られていないこと」（明示されていないこと）を特定します
6. 「測定されていないこと」（指標のないもの）を特定します

技術的な内容と人間的な意味の対応関係：

技術的な兆候	人間的な意味
ビルドエラーを無視	脆弱さの否認
分岐が急増	進むべき方向への信頼の喪失
コメントが過剰	誤解されることへの恐れ
検証を省略	フィードバックの回避
計画を立てすぎる	不完全さへの不安
リファクタリングを未完了のままにする	疲労、やり遂げる力の低下

重要な原則：

• 判断せず、明らかにするだけにします
• パターンは表現であり、エラーではありません
• 確信度スコアは、解釈における謙虚さを示します
• 何が起きているかだけでなく、なぜ起きているかに焦点を当てます

よくある落とし穴：

• ❌ 指標だけを提示する → ✅ パターンが示す物語を伝えます
• ❌ 指示的になる → ✅ 内省的かつ解釈的になります
• ❌ すべてを知っていると思い込む → ✅ 不確実性スコアを含めます

ステップ 4：アクションの振り分け — 一貫性の回復

目的： 緊急度と影響度に応じた段階的な推奨事項を提示します

アクション：

1. 介入の強さ（OBSERVE、REVIEW、HOLD）に応じて、調査結果を振り分けます
2. 一貫性フィルターを適用します：「これによってシステムの真実性は高まるか？」
3. 具体的で実行可能な次のステップを提示します
4. 重大な問題に対する回復プロトコルを含めます

介入モード：

モード	緊急度	アクションの種類	例
🟢 OBSERVE	低	穏やかな注意喚起	「開発速度は高く、一貫性は低い状態です。乖離がないか監視してください。」
🟡 REVIEW	中	体系的な内省	「同僚と前提を検証してください。外部からのフィードバックを確認してください。」
🔴 HOLD	高	一時停止＋確認	「現実との同期が崩れています。次のビルドの前に整合性を取ってください。」

回復プロトコル（HOLD 項目向け）：

restoration:
  1. pause: Create reflective checkpoint
  2. align: Re-anchor to intent + artifact coherence
  3. integrate: Capture insight in feedback loop
  4. resume: Rebuild context from re-synced rhythm

検証：

• 推奨事項が緊急度順に優先付けされている
• 各項目に明確な次のアクションがある
• 重大な項目に回復プロトコルが含まれている
• 技術的な修正だけでなく、感情面のサポートも含まれている

ステップ 5：リポジトリ一貫性指数（RCI）

目的： リポジトリ全体の健全性スコアを算出します

計算式：

RCI = (Intent Alignment + Task Reality Sync + Technical Health) / 3

スコアの構成要素：

意図との整合性（0-100）：

• 表明された目的が、観察された作業内容と一致している
• README が実際のコードベースの状態を反映している
• 目標が実行内容と一致している

タスクと現実の同期（0-100）：

• テストが構造だけでなく、実際の有用性を検証している
• 「完了」という主張が実態と一致している
• 実装がドキュメントと一致している

技術的な健全性（0-100）：

• ビルドが成功する
• テストが網羅的である
• 依存関係が保守されている
• 技術的負債が管理されている

解釈：

RCI スコア	状態	意味
85-100	✅ 一貫性あり	リズムが整い、システムが健全
70-84	🟡 監視	初期の乖離が見られ、注意深い監視が必要
50-69	🟠 不整合	意図と現実が乖離している
<50	🔴 一貫性なし	コンテキストを再構築するか、リズムをリセットする

主要原則

1. 評価せず、明らかにする Dark Matter Mode はパターンを照らし出しますが、それが「正しい」か「間違っている」かを断定しません。すべてのパターンは、システムの状態を表しています。目標は完璧さではなく、真実に忠実であることです。

2. 診断ではなく、解釈する DMM は結果を予測するのではなく、内省につながる洞察を提供します。不確実性スコアを使って、解釈における謙虚さを保ちましょう。鏡は、自分が夢を見ているときにはそれを認識します。

3. 速度より一貫性 「単に速くなるのではなく、システムがより真実に忠実になるだろうか？」と問いかけてください。意図、成果物、行動の整合性を高めることを最適化しましょう。

4. 感情的な共鳴 技術的なパターンには、人間のパターンが表れます。ドキュメントの肥大化は、不安の表れかもしれません。抑制のパターンは、疲労を示している可能性があります。人間的な側面を認識しましょう。

5. 外部検証 内部整合性 ≠ 外部での有用性です。テストに合格しても、ユーザーが混乱したままのことがあります。解釈を検証するために、外部からのフィードバックを求めましょう。

意思決定フレームワーク

分析の深さを選ぶ場合：

• Quick Scan を使う場合：初期評価、トリアージ、または定期的な健全性チェック
• Deep Analysis を使う場合：重大な問題が疑われる場合、リファクタリングの準備をする場合、または包括的な監査を行う場合

介入モードを選ぶ場合：

If RCI < 50: HOLD (pause and reconcile)
If 50 ≤ RCI < 70: REVIEW (structured reflection)
If 70 ≤ RCI < 85: OBSERVE (gentle monitoring)
If RCI ≥ 85: MAINTAIN (celebrate and sustain)

外部検証を推奨する場合：

If user discovered gap before internal analysis: HIGH PRIORITY
If documentation significantly exceeds implementation: RECOMMENDED
If team feels confused despite extensive docs: REQUIRED
Otherwise: NICE TO HAVE

出力形式

Dark Matter レポートの構成

# Dark Matter Mode Analysis

**Date:** [timestamp]
**Repository:** [name]
**RCI Score:** [score]/100 — [STATUS]

## Executive Summary

[3-5 sentence overview of key findings]

## Layer 1: Sensing — What Was Observed

[Code, documentation, temporal, environmental signals]

## Layer 2: Pattern Detection — The Weak Signals

[Identified patterns with evidence and intensity]

## Layer 3: Reflection — The Unseen, Unsaid, Unmeasured

[Narrative insights and interpretations]

## Layer 4: Action — Recommendations by Urgency

### 🔴 HOLD — Stop Before Proceeding

[Critical actions]

### 🟡 REVIEW — Reflection Requested

[Medium priority actions]

### 🟢 OBSERVE — Gentle Nudges

[Low priority awareness items]

## Repository Coherence Index

[Detailed scoring breakdown]

## Closing Reflection

[Supportive conclusion with path forward]

MCP 統合

このスキルは dark-matter-analyzer-mcp と統合され、自動スキャンを実行します：

// Run repository scan
await mcp.call('scan_repository', {
  path: './my-project',
  depth: 'deep',
  include_patterns: ['*.md', '*.ts', '*.js'],
  exclude_patterns: ['node_modules', 'dist']
})

// Calculate RCI
await mcp.call('calculate_rci', {
  repository_path: './my-project'
})

// Generate report
await mcp.call('generate_report', {
  format: 'markdown',
  output_path: './dark_matter_report.md'
})

例

例 1：ドキュメントの肥大化

シグナル： ドキュメントファイルが 30 個あり、各ファイルの平均行数は 543 行

パターン： ドキュメントの肥大化（HIGH）

内省：

「計画の活動が実行を大幅に上回っています。リポジトリは、自らの自己認識に溺れています。」

アクション（HOLD）：

• ドキュメント数が 50% 減るまで、新規ドキュメントの作成を凍結する
• 重複するファイルを統合する
• ビルドとドキュメントの比率を 1.0 以上にする

例 2：スキルとツールのギャップ

シグナル： 手法が 36 個、実装ツールが 3 個（比率 12:1）

パターン： 実行不足（CRITICAL）

内省：

「このリポジトリは、実行する手段を持たない知恵のライブラリです。能力の 92% は、実行可能ではなく願望にとどまっています。」

アクション（HOLD）：

• 新しい手法の作成を凍結する
• ギャップを比率 6:1 まで縮めるため、ツールを 6～9 個構築する
• 実行主導の開発に注力する

例 3：テスト駆動の希望的観測

シグナル： すべてのテストに合格している一方、CLI には TODO コメントがあり、MCP はプレースホルダーです

パターン： タスクと現実の非同期（MODERATE）

内省：

「リポジトリは自らのテストには合格していますが、ユーザーの役に立つとは限りません。検証によって確認できるのは内部整合性であり、外部での有用性ではありません。」

アクション（REVIEW）：

• 実際の有用性について、ユーザーからフィードバックを集める
• 社内テストだけでなく、外部のユーザーによって検証する
• 構造の検証と有用性の検証を区別する

関連スキル

• quality-auditor - 技術品質の評価
• mvp-builder - 実行重視の開発
• product-strategist - 戦略的な整合性
• technical-debt-assessor - 技術的負債の特定と優先順位付け

成功指標

• Repository Coherence Index が 10 ポイント以上向上する
• チームが、進むべき方向性について明確になったと報告する
• ドキュメントの統合によって混乱が減る
• 計画の速度に対する実行の速度が向上する
• 外部ユーザーが改善を検証する

避けるべきアンチパターン

❌ Dark Matter Mode を武器として使う - これは内省のためのものであり、罰を与えるためのものではありません ❌ RCI スコアに過度に依存する - これは方向を示すものであり、判決ではありません ❌ 感情的な含意を無視する - 技術的なパターンには、人間の状態が表れます ❌ 不確実性スコアを省略する - 解釈における謙虚さを保ちましょう ❌ ユーザーによる検証なしに変更を加える - 内部分析 ≠ 外部の真実

---

「Dark Matter Mode は鏡であり続けます — 予測するのではなく、照らし出します。」