SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsbuild-now-adapt-later

build-now-adapt-later

General & other

View repository

Updated 10-15 22:32

About this skill

Skill: build-now-adapt-later

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

WHAT

Purpose and context

  • Purpose: when a task is blocked by missing/unverified information, build everything that does NOT depend on the unknown right away and isolate the unknown behind ONE adapter boundary, so adapting later means editing one 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). Also: do not guess and present it as verified; do not abstract what is already certain "just to be safe" (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 and output contract

Field Required? Meaning
In task + spec with a ⚠️ "to be verified" section yes most of the work does not depend on the unknown
In best-guess documentation for each unknown no if missing → the default must still record its source + fail-safe
Out contract (domain types/interface) yes contains no ⚠️ values
Out config + adapter quarantine yes every unknown, verified: false, each value ASSUMPTION has a source
Out core + mock running E2E today yes build + test on the contract
Out ADAPT-CHECKLIST + conformance tests/vectors yes gate before flipping verified:true
Out handoff yes what is built+verified, what is being guessed, the one-file path to finalize each ⚠️

Rules and 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: read available spec/docs; write project code (contract, core, adapter, mock, test); no need for real hardware/prod access.

Failure boundaries

  • The main unknown is the entire task ("don't know what to build") → not applicable this skill, clarify with the user.
  • A cheap unknown to resolve right away → look it up immediately, don't quarantine.
  • A guessed value appears in two places → isolation is already broken → blocked until fixed (step 7).
  • Conformance not yet passed → keep verified:false, default behavior fail-safe (partial, state clearly in the handoff).

HOW

Main workflow

Step Type Inputs Action Outputs/exit Failure/next
W01 judgment spec Enumerate the unknowns, tag ⚠️ + source-of-truth list of unknowns cheaply look-up-able → not an unknown
W02 judgment unknowns Define the stable boundary (contract) contract without ⚠️ contract touched by ⚠️ → redo
W03 effect unknowns Quarantine: 1 config + 1 adapter, best-guess + verified: false config + adapter —
W04 effect contract Build everything above the boundary — fully core tested import of quarantined value → fix
W05 effect contract + adapter Mock/stub with the same contract E2E offline —
W06 effect adapter Ship the Adapt-kit: ADAPT-CHECKLIST + conformance kit —
W07 deterministic codebase Guard the boundary (lint/review note) no leak leak → fix before proceeding

Step-by-step details (source of truth for W01–W07):

  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

ID Kind Guard Behavior Skip / failure Rejoin
B01 recovery W07 sees a guessed value in two places move to adapter/config, delete the second copy — W07
B02 conditional_required project has llmwiki/ write draft report (Delivery section) no llmwiki/ → skip end

Validation and stopping

Deterministic: core tests + mock E2E run green on the contract; conformance tests/vectors are the only gate to flip verified:true. Needs review: the contract does not contain ⚠️, boundaries do not leak (lint rule or review note). Stop when the handoff lists enough built/verified vs guessed/pending.

Examples

  • Positive: lite3-controller-ui — the MotionSDK protocol (command codes, byte offsets, endian, ports) not yet verified against hardware → contract SemanticCommand/Telemetry, quarantine protocol.config + motionsdk-codec, UI/WS/bridge/safety fully built, UDP mock host for offline E2E, the Adapt-kit turns finalizing the protocol into editing a single file.
  • Boundary/failure: user says "don't know what this app does yet, just build it first" → the unknown is the entire task → do not apply the skill, ask for clarification of the requirements. Payment gateway wire format unclear, default verified:false must reject real transactions (fail-safe), do not assume success.

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)

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.

Delivery — Output Report (only if the project has an 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
---

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