ara-research-manager

用途

ara-research-manager 是一个“后任务研究记录器”（Live PM）。它的职责是在一次编码或研究会话结束、用户请求已被完整处理之后，回顾整段对话，并把其中具有研究意义的内容写入 ara/ 目录，形成研究过程档案。

运行时机

该技能有严格的运行约束：

绝不在任务进行中运行；处理用户请求期间不读取也不写入 ara/。
仅在任务完成后运行：当用户请求已完全得到回应，再回顾整段对话并更新 ara/。
在写后记阶段之前，不应把 ara/ 目录载入工作上下文，以免污染工作上下文。

主要能力

它会扫描整段会话，提取并分类以下事件类型，并写入对应文件：

决策（Decision）：用户在备选方案间做出选择，写入 trace/exploration_tree.yaml。
实验（Experiment）：测试运行、基准完成、出现定量结果，写入探索树并关联 evidence/。
死路（Dead End）：方案被放弃、判断“不work”、被回退，写入探索树。
方向转变（Pivot）：基于证据的重大方向调整，写入探索树。
论断（Claim）：关于系统的断言或提出的假设，写入 logic/claims.md。
启发式（Heuristic）：实现技巧、变通办法、“诀窍在于”，写入 logic/solution/heuristics.md。
AI 动作（AI Action）：智能体写代码、运行命令、创建文件，仅记入会话记录。
观察（Observation）：有趣但尚未分类的内容，写入 staging/observations.yaml。

明确跳过不记录的内容包括：常规文件读取、拼写修正、格式调整、Git 操作、依赖安装，以及澄清性提问（除非其答案构成一项决策）。

来源标记

每条记录都必须携带来源标记：

user：用户明确陈述或确认。
ai-suggested：AI 推断，用户未确认。
ai-executed：AI 执行了该动作。
user-revised：AI 建议，用户修正。

不确定时默认使用 ai-suggested；绝不把推断标为 user。

使用方式

技能被调用（任务完成后）时执行以下流程：

读取现有 ara/ 文件，获取当前状态（ID、已有论断、树的当前状态）。若 ara/ 不存在则自动创建。
扫描完整对话中的研究相关事件。
对每个事件分类并标注来源。
把新条目追加到正确文件；若状态变化则更新已有条目。
在 ara/trace/sessions/YYYY-MM-DD_NNN.yaml 创建会话记录。
把该会话追加到 ara/trace/sessions/session_index.yaml。
对暂存区运行成熟度跟踪器。
输出一行摘要，例如：“[PM] Session captured: {N} decisions, {N} experiments, {N} claims.”

初始化时（ara/ 不存在）自动创建目录结构，无需询问：

mkdir -p ara/{logic/solution,src/{configs,kernel},trace/sessions,evidence/{tables,figures},staging}

并写入 PAPER.md、session_index.yaml（sessions: []）、exploration_tree.yaml（tree: []）、observations.yaml（observations: []）、claims.md、problem.md、heuristics.md、evidence/README.md 等种子文件。

ara/ 目录结构

ara/
  PAPER.md                          # Root manifest + layer index
  logic/                            # What & Why
    problem.md                      #   Problem definition + gaps
    claims.md                       #   Falsifiable assertions + proof refs
    concepts.md                     #   Term definitions
    experiments.md                  #   Experiment plans (declarative)
    solution/
      architecture.md               #   System design
      algorithm.md                  #   Math + pseudocode
      constraints.md                #   Boundary conditions
      heuristics.md                 #   Tricks + rationale + sensitivity
    related_work.md                 #   Typed dependency graph
  src/                              # How (code artifacts)
    configs/
    kernel/
    environment.md
  trace/                            # Journey
    exploration_tree.yaml           #   Research DAG
    sessions/
      session_index.yaml            #   Master session index
      YYYY-MM-DD_NNN.yaml          #   Individual session records
  evidence/                         # Raw Proof
    README.md
    tables/
    figures/
  staging/                          # Unclassified observations
    observations.yaml

写入格式

探索树使用嵌套 YAML 结构，父子关系通过 children: 键表达，形成研究 DAG，展示决策如何引出实验、进而引出更多决策或死路。根节点位于 tree: 下，节点可含 children: 嵌套子节点，跨边使用 also_depends_on: [N{XX}]，叶节点没有 children: 键。节点类型包括 question、decision、experiment、dead_end、pivot，各有必填字段，例如 decision 需要 choice、alternatives、evidence，experiment 需要 result、evidence，dead_end 需要 hypothesis、failure_mode、lesson，pivot 需要 from、to、trigger。

论断写入 logic/claims.md，格式为 C{XX}: 标题，包含 Statement、Status（hypothesis/untested/testing/supported/weakened/refuted/revised）、Provenance、Falsification criteria、Proof、Dependencies、Tags。

启发式写入 logic/solution/heuristics.md，格式为 H{XX}: 标题，包含 Rationale、Provenance、Sensitivity（low/medium/high）、Code ref。

观察写入 staging/observations.yaml，包含 id、timestamp、provenance、content、context、potential_type、promoted。

会话记录写入 trace/sessions/YYYY-MM-DD_NNN.yaml，包含 session（id、timestamp、summary）、events_logged、ai_actions、claims_touched、open_threads、ai_suggestions_pending。

成熟度跟踪器

在后记阶段回顾 staging/observations.yaml 时：同一主题累计 3 条以上观察则提升到合适层级（标为 ai-suggested）；带实验证据的观察提升到 evidence/；与某论断冲突的观察加标记 ；超过 3 个会话未处理的陈旧观察加 stale: true 标记。

规则

绝不在任务进行中运行，只作为任务完成后的一次后记。
绝不编造事件，只记录实际发生或讨论过的内容。
绝不升级来源标记，ai-suggested 保持到用户明确确认为止。
始终先读取现有文件，获取正确的下一个 ID，避免重复。
建立取证绑定：论断到证明、启发式到代码、决策到证据。
只追加不覆盖，新增条目而不替换已有内容。
保持 YAML 有效，写入后校验结构。

参考文件

按需加载的详细协议与分类规范：

references/event-taxonomy.md
references/provenance-tags.md
references/session-protocol.md