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 行

模式： 文档膨胀（高）

反思：

“规划活动明显超前于执行。代码仓库正被自身过度的自我审视淹没。”

行动（HOLD）：

• 暂停新增文档，直至文档数量减少 50%
• 整合内容重叠的文件
• 确立构建与文档之比 ≥ 1.0

示例 2：技能与工具之间的差距

信号： 36 种方法论，3 个实现工具（比例为 12:1）

模式： 执行力不足（严重）

反思：

“这个代码仓库是一座没有双手来执行智慧的图书馆。92% 的能力停留在设想阶段，无法付诸行动。”

行动（HOLD）：

• 暂停创建新方法论
• 构建 6-9 个工具，将差距缩小至 6:1
• 专注于以执行为驱动的开发

示例 3：测试驱动的盲目乐观

信号： 所有测试均通过，但 CLI 中有 TODO 注释，MCP 均为占位内容

模式： 任务与现实脱节（中等）

反思：

“这个代码仓库通过了自己的测试，但未必能满足用户需求。验证能确保内部一致性，却无法确保外部效用。”

行动（REVIEW）：

• 收集用户对实际效用的反馈
• 通过外部用户而非仅靠内部测试进行验证
• 区分结构验证与效用验证

相关技能

• quality-auditor - 技术质量评估
• mvp-builder - 以执行为重点的开发
• product-strategist - 战略一致性
• technical-debt-assessor - 债务识别与优先级排序

成功指标

• 代码仓库一致性指数提高 10 分以上
• 团队报告对方向的认识更加清晰
• 文档整合减少了困惑
• 执行速度相较于规划速度有所提升
• 外部用户确认改进有效

应避免的反模式

❌ 将 Dark Matter Mode 当作武器 - 这是用于反思的工具，而非惩罚手段 ❌ 过度依赖 RCI 分数 - 它用于指引方向，而非作出裁决 ❌ 忽视情绪层面的暗示 - 技术模式揭示人的状态 ❌ 跳过不确定性评分 - 保持诠释上的谦逊 ❌ 未经用户验证就进行更改 - 内部分析 ≠ 外部事实

---

“Dark Matter Mode 始终是一面镜子——它不会预测，只会揭示。”