Skill: build-now-adapt-later

WHAT

Purpose và 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).

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

Input và output contract

verified: false

ASSUMPTION

ADAPT-CHECKLIST

verified:true

Rules và 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.

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).

HOW

Main workflow

verified: false

ADAPT-CHECKLIST

1. 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.
2. 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.)
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.

Branches

llmwiki/

llmwiki/

Validation và stopping

verified:true

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.

Reference — Quick template (adapt to the stack)

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)

SemanticCommand

Telemetry

protocol.config

motionsdk-codec

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

Delivery — Output Report (only if the project has an

llmwiki/

)

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

DDMMYY

<ten>

---
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)_

llmwiki/wiki/index.md

llmwiki/wiki/log.md