build-now-adapt-later

技能：build-now-adapt-later

立即交付确定的部分；隔离不确定的部分，让之后只需修改一个文件即可定稿。

内容

目的和背景

• **目的：**当任务因信息缺失或尚未验证而受阻时，立即构建所有不依赖未知因素的内容，并将未知因素隔离在一个适配器边界之后，这样之后只需修改一个文件即可完成适配。
• **触发条件（何时使用）：**任务中有些事实目前无法确定（未记录的字节布局、未经确认的端口／字节序、暂时无法调用的外部 API、只有通过真实硬件或生产环境才能确定的值）——但大部分工作实际上并不依赖这些事实。不要因为等待而拖住整个项目，也不要把猜测的值散布到整个代码库。划定一个边界。
• **非目标：**如果未知因素就是整个任务的核心（例如“我们不知道要构建什么”），或者现在就能轻松解决未知因素，则不要使用（此时直接解决即可）。此外：不要猜测后再把猜测说成已经验证；不要为了“保险起见”抽象已经确定的内容（过度设计）。

思维模型

所有依赖稳定领域契约的内容都应立即构建并测试。 所有依赖未知因素的内容都放在一个适配器之后，默认采用有文档记录的最佳猜测，标记为 verified:false，并且只需修改一处即可替换。

unknowns (⚠️ + source-of-truth) → contract ổn định (không ⚠️) → quarantine (1 config + 1 adapter, verified:false) → core build đủ trên contract → mock cùng contract → Adapt-kit (checklist + conformance) → guard boundary.

输入和输出契约

	字段	必需？	含义
输入	任务 + 规格说明，其中包含标记为 ⚠️“待验证”的项目	是	大部分工作不依赖未知因素
输入	每个未知因素的最佳猜测文档	否	缺少时 → 仍必须为默认值记录来源 + 安全失败
输出	契约（领域类型／接口）	是	不包含任何 ⚠️ 值
输出	隔离区中的配置 + 适配器	是	包含所有未知因素，标记为 verified: false，每个 ASSUMPTION 值都注明来源
输出	今天即可运行的核心代码 + mock，并通过 E2E 测试	是	基于契约构建 + 测试
输出	ADAPT-CHECKLIST + 一致性测试／向量	是	切换 verified:true 前的门禁
输出	交接说明	是	已构建并验证的内容、仍属猜测的内容，以及每个 ⚠️ 的单文件定稿路径

规则和能力

• RULE-01（MUST）：适配器及其配置是未知因素唯一允许存在的位置。同一个猜测出现在两个文件中 = 泄漏。
• RULE-02（MUST）：每个猜测都必须标记并注明来源。绝不要在代码或说明中将猜测说成已经验证。
• RULE-03（MUST）：在 verified:false 时，默认行为必须安全失败，不能乐观处理——在一致性验证证明猜测正确之前，一律假设猜测有误（尤其是涉及实体、财务或破坏性操作的内容）。
• RULE-04（MUST）：只隔离真正未知的内容。不要为了“保险起见”抽象已经确定的内容——那是过度设计，不是隔离。
• RULE-05（MUST）：契约是下游工作所依赖的交付物。保持稳定；有计划地扩展，不要随着每个猜测而扩展。
• RULE-06（MUST）：在交接说明中明确写明：构建并验证了什么、哪些内容仍是猜测且待处理，以及每个 ⚠️ 的单文件定稿路径。
• 能力：阅读现有规格说明／文档；编写项目代码（契约、核心代码、适配器、mock、测试）；无需访问真实硬件／生产环境。

失败边界

• 未知因素就是整个任务的核心（“还不知道要构建什么”）→ 不适用此技能，请向用户澄清。
• 未知因素可以轻松解决 → 立即查明，不要隔离。
• 一个猜测值出现在两个位置 → 隔离已失效 → 在修复之前处于 blocked 状态（第 7 步）。
• 一致性验证未通过 → 保持 verified:false，默认行为采用安全失败（partial，并在交接说明中明确指出）。

用法

工作流概览

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	spec	列出未知项，标记 ⚠️ + 事实来源	未知项列表	能低成本查到 → 不算未知项
W02	judgment	未知项	定义稳定边界（契约）	不含 ⚠️ 的契约	契约含有 ⚠️ → 重做
W03	effect	未知项	隔离：1 个配置 + 1 个适配器，采用最佳猜测 + verified: false	配置 + 适配器	—
W04	effect	contract	完整构建边界之上的所有部分	已测试的核心	导入隔离区的值 → 修复
W05	effect	contract + adapter	使用同一契约创建 Mock/Stub	离线 E2E	—
W06	effect	adapter	交付 Adapt-kit：ADAPT-CHECKLIST + 一致性验证	工具包	—
W07	deterministic	codebase	守护边界（lint/审查说明）	无泄漏	有泄漏 → 修复后再继续

各步骤详情（W01–W07 的事实来源）：

1. 列出未知项。 列出所有你尚不知道或无法验证的事实。为每项标记 ⚠️，并注明其事实来源（真实硬件、生产数据、缺失的文档或利益相关方的决定）。如果某个“事实”现在就能低成本查到——先查清；它不算未知项。

2. 定义稳定边界（契约）。 编写领域层接口，供其他所有部分使用——类型、函数签名或消息架构，描述的是意图，而不是未知的编码方式。规则：契约中不得包含任何 ⚠️ 值。（例如，使用 SemanticCommand/Telemetry 模型，而不是字节偏移量；使用 PaymentRequest，而不是网关的线格式。）

3. 隔离未知项。 将每个依赖未知项的常量都放入同一个配置文件，并将每段依赖未知项的逻辑都放入契约后的同一个适配器模块。根据现有文档为每项设置一个最佳猜测默认值，标记为 // ASSUMPTION (source / not verified)，并添加明确的 verified: false 标记。只有适配器了解未知项。

4. 完整构建边界之上的所有部分。 UI、业务逻辑、传输、安全/错误处理、验证：全部基于契约编写，完整实现并经过测试。它们绝不导入隔离区中的值。

5. 构建使用同一契约的 Mock/Stub。 这样无需真实的未知项，整个系统今天就能端到端运行。让 Mock 遵循同一适配器/配置，以便之后也能用作一致性验证工具。

6. 交付 Adapt-kit。 提供 (a) 简短的 ADAPT-CHECKLIST——确定未知项后完成适配的具体步骤（编辑配置 → 编辑适配器 → 运行一致性验证 → 将 verified:true 设为 true），以及 (b) 一致性测试/测试向量；在生产环境或真实硬件上信任猜测值之前，必须通过这些测试。

7. 守护边界。 添加 lint 规则或审查说明：隔离的值不得泄漏到适配器之外。如果某个猜测常量出现在两个地方，就说明隔离已被破坏——继续之前先修复。

分支

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	recovery	W07 发现某个猜测值出现在两个地方	移至 adapter/config，删除第二处副本	—	W07
B02	conditional_required	项目中存在 llmwiki/	编写 draft report（Delivery 部分）	不存在 llmwiki/ → 跳过	结束

验证与停止

必须满足：核心测试 + Mock E2E 基于契约运行并全部通过；一致性测试/测试向量是将 verified:true 设为 true 的唯一关卡。需要审查：契约不含 ⚠️，边界没有泄漏（lint 规则或审查说明）。交接内容完整列出已构建/已验证与猜测/待处理项后，即可停止。

示例

• 正面： lite3-controller-ui — MotionSDK 协议（命令代码、字节偏移、字节序、端口）尚未通过硬件验证 → 定义 SemanticCommand/Telemetry 契约，将 protocol.config + motionsdk-codec 隔离，基于契约完整构建 UI/WS/bridge/safety，使用 UDP mock host 实现离线 E2E 测试，Adapt-kit 将敲定协议变成只需修改一个文件。
• 边界/失败： 用户说“还不知道这个应用是做什么的，先构建再说” → 未知因素涵盖整个任务 → 不应用此技能，应先澄清需求。支付网关的 wire format 尚不明确时，默认 verified:false 必须拒绝真实交易（故障安全），不能假定交易成功。

参考 — 快速模板（根据技术栈调整）

contract/         # stable domain types — NO unknown values        (built now, tested now)
  └ model.*       #   intent-level: commands, telemetry, requests
core/             # UI / logic / transport / safety on the contract (built now, tested now)
adapter/
  ├ config.*      # ⚠️ ALL unknown constants + verified:false       (quarantine)
  └ codec.*       # ⚠️ encode/decode against the unknown            (quarantine, swap 1 file)
mock/             # speaks the same adapter → E2E offline + conformance harness
ADAPT-CHECKLIST.* # 5-step finalize procedure when the unknown is known
conformance.*     # vectors that gate verified:true

参考 — 完整示例（本指南的提炼来源）

lite3-controller-ui：MotionSDK 协议（命令代码、字节偏移、字节序、端口）未经真实硬件验证。契约 = SemanticCommand/Telemetry；隔离区 = protocol.config + motionsdk-codec；完全基于契约构建 UI/WS/bridge/safety；通过 UDP mock host 实现完整的离线 E2E 测试；Adapt-kit（检查清单 + 一致性测试向量）让最终敲定协议只需修改一个文件。参见 llmwiki/wiki/draft/orca/150626-lite3-adapter-isolation.md。

交付 — 输出报告（仅当项目中存在 llmwiki/ 时）

工作完成后，撰写一份草稿报告，以便追溯决策。

1. 文件名： llmwiki/wiki/draft/orca/DDMMYY-<ten>.md — DDMMYY = 今天，<ten> = 2–4 个 kebab 格式单词。

2. 撰写：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

# DDMMYY-<ten>
**Type:** draft
**Status:** proposed
**Tags:** build-now-adapt-later, output-report
**Proposed:** YYYY-MM-DD

## What
<One sentence — what was built now vs what was quarantined>

## Boundary
- Contract: <the stable domain types/interface>
- Quarantine: <config + adapter files holding the ⚠️ unknowns>

## Unknowns (⚠️) pending verification
| Unknown | Best-guess source | Finalize by |
|---------|-------------------|-------------|

## Files
| File | Action |
|------|--------|

## Notes
- Invoked via: `/build-now-adapt-later` skill

## Origin
- **Draft:** `wiki/draft/orca/DDMMYY-<ten>.md`
- **Commit:** _(filled by verify-before-commit)_
- **Date promoted:** _(filled by verify-before-commit)_

3. 在 llmwiki/wiki/index.md 中追加一行，并在 llmwiki/wiki/log.md 中追加一行。