build-now-adapt-later

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: build-now-adapt-later

Ship the certain part now; isolate the uncertain part so it costs one file to finalize later.

立即交付确定的部分；隔离不确定的部分，使其日后只需修改一个文件即可完成。

WHAT

Purpose và context

Purpose 与 context

Purpose: khi task bị chặn bởi thông tin thiếu/chưa xác minh, build ngay mọi thứ KHÔNG phụ thuộc vào ẩn số và cách ly ẩn số sau MỘT adapter boundary, để adapt sau là sửa một file.
Trigger (when to use): A task contains some facts you cannot pin down yet (undocumented byte layout, unconfirmed port/endian, an external API you can't call yet, a value only real hardware or production reveals) — BUT most of the work doesn't truly depend on those facts. Don't stall the whole project waiting, and don't scatter guessed values across the codebase. Draw one boundary.
Non-goals: Do NOT use when the unknown is the whole task (e.g. "we don't know what to build"), or when the unknown is cheap to resolve right now (then just resolve it). Ngoài ra: không đoán rồi trình bày như đã xác minh; không trừu tượng hoá thứ đã chắc chắn "cho chắc" (over-engineering).

**Purpose：**当 task 因信息缺失或未验证而受阻时，立即构建所有不依赖未知项的部分，并将未知项隔离在单一 adapter 边界之后，使日后适配只需修改一个文件。
**Trigger（何时使用）：**task 中包含一些暂时无法确定的事实（未记录的 byte layout、尚未确认的 port/endian、暂时无法调用的外部 API、只有真实硬件或生产环境才能揭示的值）——但大部分工作实际上并不依赖这些事实。不要让整个项目停摆等待，也不要把猜测值散落在代码库各处。划定一条边界。
**Non-goals：**当未知项就是整个 task 时（例如“我们还不知道要构建什么”），不要使用本 skill；当未知项现在就能低成本解决时，也不要使用本 skill，而应直接解决。此外：不要一边猜测，一边将其表述为已经验证；也不要把已经确定的事物过度抽象，“以防万一”（这属于过度工程化，而不是隔离）。

Mental model

Everything that depends on a stable domain contract is built and tested now. Everything that depends on an unknown lives behind one adapter, defaulted to a documented best-guess, flagged
verified:false
, and swappable in a single edit.

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

所有依赖稳定 domain contract 的内容现在都已构建并测试。所有依赖 unknown 的内容都位于一个 adapter 之后，使用有文档记录的最佳猜测默认值，标记为
verified:false
，并且只需一次编辑即可替换。

unknowns（⚠️ + source-of-truth）→ 稳定 contract（无 ⚠️）→ quarantine（1 config + 1 adapter, verified:false）→ 完整构建 core → 同一 contract 的 mock → Adapt-kit（checklist + conformance）→ guard boundary

。

Input và output contract

输入与输出 contract

	Field	Required?	Ý nghĩa
In	task + spec có mục ⚠️ "to be verified"	có	phần lớn việc không phụ thuộc ẩn số
In	tài liệu best-guess cho từng ẩn số	không	thiếu → default vẫn phải ghi nguồn + fail-safe
Out	contract (domain types/interface)	có	không chứa giá trị ⚠️ nào
Out	config + adapter quarantine	có	mọi ẩn số, `verified: false` , mỗi giá trị `ASSUMPTION` có nguồn
Out	core + mock chạy E2E hôm nay	có	build + test trên contract
Out	`ADAPT-CHECKLIST` + conformance tests/vectors	có	gate trước khi flip `verified:true`
Out	handoff	có	cái đã build+verify, cái đang đoán, đường một-file để chốt từng ⚠️

	Field	Required?	含义
In	task + 包含 ⚠️“待验证”项的 spec	是	大部分工作不依赖未知项
In	每个未知项的最佳猜测文档	否	缺失时，default 仍必须记录来源并采用 fail-safe
Out	contract（domain types/interface）	是	不包含任何 ⚠️ 值
Out	config + adapter quarantine	是	包含所有未知项、 `verified: false` ，每个 `ASSUMPTION` 值都有来源
Out	当天即可运行的 core + mock E2E	是	基于 contract 构建并测试
Out	`ADAPT-CHECKLIST` + conformance tests/vectors	是	在切换 `verified:true` 前设置关卡
Out	handoff	是	已构建并验证的内容、仍在猜测的内容，以及敲定每个 ⚠️ 的单文件路径

Rules và capabilities

Rules 与 capabilities

RULE-01 (MUST): The adapter + its config are the ONLY places an unknown lives. Same guess in two files = a leak.
RULE-02 (MUST): Every guess is flagged AND sourced. NEVER present a guess as verified, in code or in prose.
RULE-03 (MUST): Default behavior under
```
verified:false
```
must be fail-safe, not optimistic — assume the guess is wrong until conformance proves otherwise (especially for anything physical, financial, or destructive).
RULE-04 (MUST): Quarantine only what is genuinely unknown. Don't abstract certain things "just in case" — that's over-engineering, not isolation.
RULE-05 (MUST): The contract is the deliverable downstream work depends on. Keep it stable; widen it deliberately, not per-guess.
RULE-06 (MUST): State plainly in your handoff: what was built and verified, what is guessed and pending, and the one-file path to finalize each ⚠️.
Capabilities: đọc spec/tài liệu sẵn có; ghi code dự án (contract, core, adapter, mock, test); không cần truy cập hardware/prod thật.

RULE-01（MUST）：adapter 及其 config 是未知项唯一允许存在的位置。同一个猜测值出现在两个文件中就意味着边界泄漏。
RULE-02（MUST）：每个猜测都必须同时设置标志并注明来源。绝不能将猜测表述为已验证，无论是在代码还是文字中。
RULE-03（MUST）：
```
verified:false
```
下的默认行为必须是 fail-safe，而不是乐观假设——在 conformance 证明之前，始终假定猜测有误（尤其是涉及实体操作、资金或破坏性操作时）。
RULE-04（MUST）：只隔离真正未知的部分。不要仅仅“以防万一”就抽象已经确定的内容——那是过度工程化，而不是隔离。
RULE-05（MUST）：contract 是下游工作所依赖的交付物。保持它稳定；仅在有明确理由时扩展，而不能根据每个猜测随意改变。
RULE-06（MUST）：在 handoff 中清楚说明：哪些内容已构建并验证，哪些内容仍是猜测且尚待确认，以及敲定每个 ⚠️ 的单文件路径。
Capabilities：读取 spec/现有文档；编写项目代码（contract、core、adapter、mock、test）；无需访问真实硬件/生产环境。

Failure boundaries

Ẩn số chính là toàn bộ task ("chưa biết build gì") → không áp dụng skill này, clarify với user.
Ẩn số rẻ để giải ngay → tra luôn, không quarantine.
Một giá trị đoán xuất hiện ở hai chỗ → isolation đã vỡ → blocked cho tới khi sửa (bước 7).
Conformance chưa qua → giữ
```
verified:false
```
, hành vi mặc định fail-safe (partial, nói rõ trong handoff).

未知项就是整个 task（“还不知道要构建什么”）→ 不适用本 skill，应向 user 澄清需求。
未知项现在就能低成本解决 → 立即解决，不要 quarantine。
同一个猜测值出现在两个位置 → 隔离已经失效 → blocked，直到完成修复（步骤 7）。
Conformance 尚未通过 → 保持
```
verified:false
```
，默认行为必须 fail-safe（工作处于 partial 状态），并在 handoff 中明确说明。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	spec	Enumerate the unknowns, tag ⚠️ + source-of-truth	danh sách ẩn số	tra được rẻ → không phải ẩn số
W02	judgment	ẩn số	Define the stable boundary (contract)	contract không ⚠️	contract dính ⚠️ → làm lại
W03	effect	ẩn số	Quarantine: 1 config + 1 adapter, best-guess + `verified: false`	config + adapter	—
W04	effect	contract	Build everything above the boundary — fully	core đã test	import giá trị quarantine → sửa
W05	effect	contract + adapter	Mock/stub cùng contract	E2E offline	—
W06	effect	adapter	Ship the Adapt-kit: `ADAPT-CHECKLIST` + conformance	kit	—
W07	deterministic	codebase	Guard the boundary (lint/review note)	không rò	rò → sửa trước khi đi tiếp

Chi tiết từng bước (nguồn chân lý cho W01–W07):

Enumerate the unknowns. List every fact you don't have or can't verify. Tag each ⚠️ and note its source-of-truth (real hardware, prod data, a doc you lack, a stakeholder decision). If a "fact" can be looked up cheaply now — look it up; it's not an unknown.
Define the stable boundary (the contract). Write the domain-level interface that everything else speaks — types / function signatures / message schema that describe intent, not the unknown encoding. Rule: the contract must NOT contain any ⚠️ value. (e.g. a
```
SemanticCommand
```
/
```
Telemetry
```
model, not byte offsets; a
```
PaymentRequest
```
, not the gateway's wire format.)
Quarantine the unknowns. Put EVERY unknown-dependent constant in ONE config file and EVERY unknown-dependent logic in ONE adapter module behind the contract. Seed each with a best-guess default from whatever doc you have, mark each
```
// ASSUMPTION (source / not verified)
```
, and add an explicit
```
verified: false
```
flag. The adapter is the only thing that knows the unknown.
Build everything above the boundary — fully. UI, business logic, transport, safety/error handling, validation: all written against the contract, complete and tested. They never import a quarantined value.
Build a mock/stub that speaks the same contract. It lets the whole system run end-to-end today without the real unknown. Make the mock honor the same adapter/config so it doubles as the conformance harness later.
Ship the Adapt-kit. Produce (a) a short
```
ADAPT-CHECKLIST
```
— the exact steps to finalize once the unknown is known (edit config → edit adapter → run conformance → flip
```
verified:true
```
), and (b) conformance tests / vectors that must pass before the guessed values are trusted in production / against real hardware.
Guard the boundary. Add a lint rule or review note: quarantined values must not leak past the adapter. If a guessed constant appears in two places, the isolation is already broken — fix it before moving on.

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	spec	枚举未知项，添加 ⚠️ 标签并注明 source-of-truth	未知项列表	如果能低成本查到，则它不属于未知项
W02	judgment	未知项	定义稳定边界（contract）	不含 ⚠️ 的 contract	如果 contract 包含 ⚠️，则重新定义
W03	effect	未知项	隔离：1 config + 1 adapter、最佳猜测 + `verified: false`	config + adapter	—
W04	effect	contract	完整构建边界之上的所有内容	已测试的 core	如果 import 了隔离值，则进行修复
W05	effect	contract + adapter	构建使用同一 contract 的 mock/stub	离线 E2E	—
W06	effect	adapter	交付 Adapt-kit： `ADAPT-CHECKLIST` + conformance	kit	—
W07	deterministic	codebase	保护边界（lint/review note）	无泄漏	如果存在泄漏，修复后再继续

每个步骤的详细信息（W01–W07 的事实来源）：

**枚举未知项。**列出所有尚未掌握或无法验证的事实。为每项添加 ⚠️ 标签，并注明其 source-of-truth（真实硬件、生产数据、缺失的文档或利益相关者的决定）。如果某个“事实”现在就能低成本查到，就直接查询；它不属于未知项。
**定义稳定边界（contract）。**编写供其他所有部分使用的领域级 interface——用以描述意图而非未知编码的 types / function signatures / message schema。规则：contract 绝不能包含任何 ⚠️ 值。（例如，使用
```
SemanticCommand
```
/
```
Telemetry
```
模型，而不是 byte offsets；使用
```
PaymentRequest
```
，而不是 gateway 的 wire format。）
**隔离未知项。**将每个依赖未知项的常量放在一个 config 文件中，并将每段依赖未知项的逻辑放在 contract 之后的单一 adapter module 中。根据现有文档为每项填入最佳猜测默认值，标记
```
// ASSUMPTION (source / not verified)
```
，并添加明确的
```
verified: false
```
标志。只有 adapter 知道这些未知项。
**完整构建边界之上的所有内容。**UI、业务逻辑、transport、安全/错误处理、验证：全部基于 contract 编写，做到完整且经过测试。它们绝不能 import 被隔离的值。
**构建使用同一 contract 的 mock/stub。**它可以让整个系统今天无需真实未知实现即可端到端运行。让 mock 遵循相同的 adapter/config，使其日后兼作 conformance harness。
**交付 Adapt-kit。**生成：(a) 一份简短的
```
ADAPT-CHECKLIST
```
——列出未知项明确后完成适配所需的确切步骤（编辑 config → 编辑 adapter → 运行 conformance → 切换
```
verified:true
```
）；以及 (b) 在将猜测值用于生产环境或真实硬件之前必须通过的 conformance tests / vectors。
**保护边界。**添加 lint rule 或 review note：被隔离的值不得越过 adapter 泄漏。如果同一个猜测常量出现在两个位置，则隔离已经失效——继续推进前必须先修复。

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	recovery	W07 thấy một giá trị đoán ở hai chỗ	dời về adapter/config, xoá bản thứ hai	—	W07
B02	conditional_required	project có `llmwiki/`	viết draft report (mục Delivery)	không có `llmwiki/` → skip	kết thúc

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	recovery	W07 发现同一个猜测值出现在两个位置	将其移入 adapter/config，并删除另一处	—	W07
B02	conditional_required	project 包含 `llmwiki/`	编写 draft report（见 Delivery）	如果没有 `llmwiki/` ，则跳过	结束

Validation và stopping

Validation 与 stopping

Tất định: test core + mock E2E chạy xanh trên contract; conformance tests/vectors là cổng duy nhất để flip

verified:true

. Cần review: contract không chứa ⚠️, ranh giới không rò (lint rule hoặc review note). Dừng khi handoff liệt kê đủ built/verified vs guessed/pending.

确定性检查：core + mock E2E 在 contract 上测试通过；conformance tests/vectors 是将

verified:false

切换为

verified:true

的唯一关卡。需要 review：contract 不含 ⚠️，边界无泄漏（通过 lint rule 或 review note 检查）。当 handoff 完整列出已构建/已验证与猜测/待处理内容时停止。

Examples

Positive: lite3-controller-ui — protocol MotionSDK (command codes, byte offsets, endian, ports) chưa xác minh với hardware → contract
```
SemanticCommand
```
/
```
Telemetry
```
, quarantine
```
protocol.config
```
+
```
motionsdk-codec
```
, UI/WS/bridge/safety build đủ, UDP mock host cho E2E offline, Adapt-kit biến việc chốt protocol thành sửa một file.
Boundary/failure: user nói "chưa biết app này làm gì, cứ build trước" → ẩn số là toàn bộ task → không áp dụng skill, hỏi làm rõ yêu cầu. Cổng thanh toán chưa rõ wire format, mặc định
```
verified:false
```
phải từ chối giao dịch thật (fail-safe), không giả định thành công.

**正向示例：**lite3-controller-ui——MotionSDK protocol（command codes、byte offsets、endian、ports）尚未针对真实硬件验证 → contract 为
```
SemanticCommand
```
/
```
Telemetry
```
，quarantine 为
```
protocol.config
```
+
```
motionsdk-codec
```
，UI/WS/bridge/safety 基于 contract 完整构建；UDP mock host 提供离线 E2E；Adapt-kit 将敲定 protocol 变成修改一个文件。
**边界/失败示例：**user 说“还不知道这个 app 做什么，先构建” → 未知项就是整个 task → 不适用本 skill，应先向 user 澄清需求。支付 gateway 的 wire format 尚不明确时，默认的
```
verified:false
```
必须拒绝真实交易（fail-safe），不能假定交易成功。

Reference — Quick template (adapt to the stack)

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

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

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

Reference — Worked example (where this was distilled from)

Reference — 实例（该模式的来源）

lite3-controller-ui: the MotionSDK protocol (command codes, byte offsets, endian, ports) was unverified vs real hardware. The contract =

SemanticCommand

Telemetry

; the quarantine =

protocol.config

motionsdk-codec

; UI/WS/bridge/safety built fully on the contract; a UDP mock host gave full E2E offline; an Adapt-kit (checklist + conformance vectors) made finalizing the protocol a one-file edit. See

llmwiki/wiki/draft/orca/150626-lite3-adapter-isolation.md

lite3-controller-ui：MotionSDK protocol（command codes、byte offsets、endian、ports）尚未对照真实硬件验证。contract =

SemanticCommand

Telemetry

；quarantine =

protocol.config

motionsdk-codec

；UI/WS/bridge/safety 基于 contract 完整构建；UDP mock host 提供完整的离线 E2E；Adapt-kit（checklist + conformance vectors）使最终确定 protocol 只需编辑一个文件。参见

llmwiki/wiki/draft/orca/150626-lite3-adapter-isolation.md

。

Delivery — Output Report (only if the project has an

llmwiki/

)

Delivery — Output Report（仅当 project 包含

llmwiki/

时）

After the work completes, write a draft report so the decision is traceable.

1. Filename:

llmwiki/wiki/draft/orca/DDMMYY-<ten>.md

—

DDMMYY

= today,

<ten>

= 2–4 kebab words.

2. Write:

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

工作完成后，编写一份 draft report，使相关决策可以追溯。

1. Filename：

llmwiki/wiki/draft/orca/DDMMYY-<ten>.md

——

DDMMYY

表示当天日期，

<ten>

为 2–4 个 kebab-case 单词。

2. 编写：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [build-now-adapt-later, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

Type: draft Status: proposed Tags: build-now-adapt-later, output-report Proposed: YYYY-MM-DD

What

Boundary

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

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

Unknowns (⚠️) pending verification

Unknown	Best-guess source	Finalize by

Unknown	Best-guess source	Finalize by

Files

File	Action

File	Action

Notes

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

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.** Append a row to `llmwiki/wiki/index.md` and a line to `llmwiki/wiki/log.md`.

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` 追加一条记录。

build-now-adapt-later

Original

Translation

Skill: build-now-adapt-later

Skill: build-now-adapt-later

WHAT

WHAT

Purpose và context

Purpose 与 context

Mental model

Mental model

Input và output contract

输入与输出 contract

Rules và capabilities

Rules 与 capabilities

Failure boundaries

Failure boundaries

HOW

HOW

Main workflow

Main workflow

Branches

Branches

Validation và stopping

Validation 与 stopping

Examples

Examples

Reference — Quick template (adapt to the stack)

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

Reference — Worked example (where this was distilled from)

Reference — 实例（该模式的来源）

Delivery — Output Report (only if the project has an llmwiki/)

Delivery — Output Report（仅当 project 包含 llmwiki/ 时）

DDMMYY-<ten>

DDMMYY-<ten>

What

What

Boundary

Boundary

Unknowns (⚠️) pending verification

Unknowns (⚠️) pending verification

Files

Files

Notes

Notes

Origin

Origin

Delivery — Output Report (only if the project has an
`llmwiki/`
)

Delivery — Output Report（仅当 project 包含
`llmwiki/`
时）