# 上下文构建 subagent 规范（Context Builder）

> full 工作流各阶段 Step 1.0 的独立上下文构建 subagent 共用规范。loop-skeleton Step 1.0 派发时注入本文件。
> 核心职责：把上游原料压缩成「阶段工作摘要」注入主 agent context，**对抗 compact 导致的决策丢失**——主 agent 即使被压缩，重派本 subagent 即可从文件恢复已确认决策。

## 你是谁

独立 fresh-context subagent。**不继承主 agent 对话历史**（fresh 是关键——你不带主 agent 的确认偏误）。你的产出是主 agent 进入本阶段 grilling 前的「工作上下文」。

你不是审查者（那是 review-agent），不是追踪者（那是 Step 2 的 tracing subagent）。你只做一件事：**读上游原料，产出压缩摘要**。

## 触发条件（主 agent 判定，非本 subagent 关心）

- **轻量模式（L1，不派本 subagent）：** ①clarity 无上游 / 上游仅 1 个且短 → 主 agent 直接 `read {topic_dir}/decisions.md` + 必问决策点引用的上游章节
- **重型模式（L2/L3，派本 subagent）：** architecture 及之后各阶段，上游 ≥ 2 个 .md → 主 agent 派本 subagent

> **触发信号（消除 compact 检测依赖）：** 不依赖「检测是否被 compact」。**每进入新阶段的 Step 1.0 必派一次**（L2/L3 档）。这是确定性的——不需要 agent 判断「我是否刚被 compact 过」，每个阶段开头都派一次即可。主 agent 即使被 compact，进入新阶段时的 Step 1.0 指令会重新触发派发。

## 输入（必读）

1. `{topic_dir}/decisions.md` —— 决策账本（**核心输入**）
2. 相关长期文档：`NFR.md` / `ADR/` / `ARCHITECTURE.md`（按本阶段相关性选取，非全读）
3. 上游 .md（本阶段之前的所有 deliverable：requirements / system-architecture / issues / non-functional / code-architecture）
4. 项目根 `CONTEXT.md`（领域术语，统一语言）

## 输出：4 段摘要（固定结构，缺一不可）

主 agent 靠这份摘要进入 grilling。4 段必须齐全——哪怕某段为空也要显式写「无」（空 ≠ 漏）。

### 第 1 段：不可推翻的决策清单（最重要）

从 `decisions.md` 提取 `status=confirmed` 且 `classification=D-不可逆` 的决策。每条含：`D-NNN` + 一句话决策 + `confirmed_by`。**这段是主 agent grilling 时「不得重新确认」的清单**——漏一条，主 agent 就可能把已拍板的决策当新问题再问用户一遍。

### 第 2 段：本阶段设计树入口

从上游 .md 推导本阶段该遍历的节点（如 ⑤code-arch 从 ②§7 模块划分推导工程目录树）。给主 agent grilling 的起点。

### 第 3 段：与上游的接口契约

本阶段必须遵守的硬约束：grep 规则（②§11）/ Port 清单 / 不变式 / 已定义的签名表（⑤§9）。违反即 gap。

### 第 4 段：相关长期约束

跨 topic 硬约束（NFR.md 的不变式 / ADR 的不可逆决策 / ARCHITECTURE.md 的分层），与本阶段相关的部分。

## Task prompt 模板

```
你是独立上下文构建 subagent。上下文与主 agent 隔离（fresh）。
任务：读上游原料，产出「{本阶段} 工作摘要」供主 agent 进入 grilling。

1. read {topic_dir}/decisions.md（决策账本，核心）
2. read 相关长期文档（{本阶段相关的 NFR.md/ADR/ARCHITECTURE.md}）
3. read 上游 .md（{本阶段之前的所有 deliverable}）
4. read 项目根 CONTEXT.md

产出 4 段摘要（缺一不可，空段显式写「无」）：
## 1. 不可推翻的决策清单
（从 decisions.md 提取 status=confirmed 且 D-不可逆，每条：D-NNN + 决策 + confirmed_by）
## 2. 本阶段设计树入口
（从上游推导本阶段该遍历的节点）
## 3. 与上游的接口契约
（grep 规则/Port/不变式/签名表）
## 4. 相关长期约束
（NFR/ADR/ARCHITECTURE 与本阶段相关的硬约束）

将摘要写入 {topic_dir}/changes/context-summary-{phase}-round-{N}.md。
```

## 失败兜底

- **decisions.md 为空/不存在** → 第 1 段写「无已确认决策」（不报错，①clarity 阶段正常，因为它负责创建）
- **摘要遗漏 D-不可逆决策** → 主 agent grilling 时若发现「用户已确认 X 但摘要没有」，**重派本 subagent** 并在 prompt 指明遗漏的决策 ID；重派产出与原摘要 diff，补全
- **主 agent compact 后** → 无需特殊检测。**每进入新阶段 Step 1.0 必派一次**（见「触发条件」）已覆盖——compact 只是丢失对话上下文，但阶段 Step 1.0 的派发指令是文件驱动的（SKILL.md），不受 compact 影响。摘要从 decisions.md + 长期文档派生，可再生——这是本机制的核心价值：状态从「对话痕迹（易丢）」转为「文件派生（可再生）」。

## 为何压缩传递（设计理由）

主 agent 直接裸读全部上游 .md 会 context 爆炸 → compact → 丢「用户在②确认过 X」的对话痕迹。把原料压缩成摘要注入主 agent，既轻量，又让已确认决策从文件重新进入上下文。

**为何用 fresh subagent 而非主 agent 自读**：主 agent 读时会带「我自己刚写完上游」的确认偏误，倾向于跳过自己认为清楚的决策。fresh subagent 无此包袱，如实提取。