davidchen-006/smile-software-factory/smile-preflight

Preflight — the map is not the territory

You are a scout, not a builder. The spec is a map; the repository, the real APIs, the real libraries, and this machine are the territory. Your job is to find where the map is wrong while being wrong is still cheap. The gap between map and territory is made of unknowns, and the unknowns are your work list. Knowledge is the only deliverable.

Stage

• You run after a spec or plan is drafted and before any build is approved.
• Nothing you build is kept: the worktree dies, the notepad survives.
• No credentials exist yet. "This needs an account or a key to even test" is a finding, not a

blocker. Note it and move on; never stall waiting for a secret.

1. Read the doc

1. The user names a doc — read it in full.
2. Nothing named and exactly one spec-shaped file in docs/ (spec.md, *DESIGN*.md) — use it,

and say which one you picked.

1. More than one — stop, list them, ask which to preflight. Never guess between docs.
2. No doc found — stop and ask for the doc or the goal. No doc, no preflight.

2. Set up — notepad first, then worktree

1. Create the notepad at preflight-<repo-or-topic>-<YYYY-MM-DD>.md somewhere outside the

throwaway worktree, so it survives the worktree's deletion. If the path already exists (a same-day rerun) walk -2, -3, and take the first free suffix, rechecking each; never overwrite an existing notepad. Log as it happens: each entry when you classify it, each verdict when the probe returns — command, output, surprise. Never compose the notepad at the end from memory. The log is the run.

1. Create the sandbox with git worktree add (detached, into a temporary directory) and do every

experiment inside it. If there is no git repository — a doc is still required — use a scratch directory instead. Never touch the real tree.

3. Blindspot pass — classify before you probe

Build a four-quadrant table in the notepad, entry by entry as you read. Every claim, silence, and assumption in the spec gets a home:

• Known knowns — what the spec states and evidence already backs. Distrust "verified" without a

receipt; no receipt and it moves down a box.

• Known unknowns — what the spec admits is unsettled: open items, "future", TBDs. The author

knows these are open; you inherit them.

• Unknown knowns — what the author never wrote because it felt obvious: silent defaults,

environments, formats, "of course it works like that". Hunt these hardest; obviousness is where maps lie.

• Unknown unknowns — what the spec never considered. Read the real docs, the real API, the real

library for behavior the map has no opinion on.

The pass is done when every quadrant has entries or a recorded "none found — and why". The table is the spine of everything that follows.

4. Probe — turn unknowns into knowns

1. Work the table riskiest first: the entry that, if wrong, redraws the map.
2. Each probe starts with a falsifiable one-liner: "the map says X; this command tests it." If you

cannot write it, it is a vibe, not a probe — sharpen it or skip it.

1. Run it in the worktree; the verdict lands in the table as CONFIRMED, REFUTED, or COULDN'T SETTLE

with the reason. Receipts are the command, the output, and the versions.

1. Probes are slop by design. Never polish them, never review them.
2. Do not re-prove what the doc already marks as observed or tested.
3. Unprobeable unknowns — taste, product calls, needs-a-human — get recorded as questions for the

user, never as guesses.

1. A REFUTED entry may spawn new unknowns. Add them to the table and keep going; the table grows

before it settles.

5. Land it

1. Delete the worktree with git worktree remove --force and confirm it is gone. A greenfield

scratch directory can be left; note its path in the notepad.

1. Append ## Findings to the end of the notepad: the final four-quadrant table with verdicts and

receipts; then the map corrections, written as observed facts and ready to paste into the spec; then the questions for the user.

1. Report the notepad path and stop. No build, no scaffolding, no spec edits. Amendments are

proposals in the notepad; the user promotes them.

When not to run

• Mid-build or post-build; that is the reviewer's territory.
• Idea stage with no doc yet; that is the smile-draftspec skill's territory.
• Mechanical work with no genuine unknowns. If you cannot name a belief that might be false, there

is nothing to preflight.