prompt-compile

# Prompt Compile Define-do-verify for real tasks. Compile a brief (define), execute it in fresh context where possible (do), check the result against the brief (verify). The brief is the prompt an experienced operator would have hand-written before a big task - now generated in-session, every time. ## When this runs - Fired by the `prompt-compile-gate.sh` hook (medium and high bands), or invoked manually. - Not for bug fixes: your debugging workflow owns those. - Not for trivial one-file one-step edits: if the gate misfired, say "trivial, skipping brief" in one line and just do it. ## Compile the brief Seven sections. All required. Missing section = brief not done. ### 1. TASK + NON-GOALS One paragraph: what changes, and what is explicitly preserved. Non-goals are the highest-value words in the brief ("polish pass, not a rebuild. Preserve data, routing, behavior. Change presentation only."). ### 2. TARGET Concrete environment, not adjectives. "Latest iPhone Pro, ~402pt logical width, Dynamic Island, home-indicator safe area" - never "mobile-friendly". For non-UI work: runtime, versions, load shape, who consumes the output. ### 3. CONSTRAINT SOURCES Files the executor must read before generating anything: design docs, design tokens, schema, project instructions (CLAUDE.md / AGENTS.md), style guides. Hard rule inherited by every brief: if a needed value or source does not exist, stop and flag - never invent one. ### 4. SKILL SEQUENCE Scan available skills; name them in execution order, with register or mode where it matters. Example: `/distill` -> `/adapt` (product register) -> a craft/polish pass. Every stage that has a matching skill names it explicitly - the executor must not rediscover routing. ### 5. CHECKPOINTS Where execution stops for the user's confirm: proposed cuts before restructure, variant pick before writing to source, destructive step before running. Input is just a link or pointer -> diagnostic pass is checkpoint zero. No checkpoint needed? Say "no checkpoints" explicitly. ### 6. VERIFY Observable pass/fail criteria, checkable after execution: no horizontal overflow at target width, tap targets >= 44pt, all states handled (loading/error/empty), typecheck clean, tests green. E2E where the change has a runtime surface. ### 7. OUTPUT CONTRACT The shape of the executor's final response, in order. Example: diagnostic -> proposed cuts -> 3 variants -> craft pass on winner -> diff summary + anything that couldn't be done within constraints. ## Execute - **Medium band:** show the compiled brief, non-blocking - start immediately, the user interrupts if it is wrong. - **High band:** show the compiled brief and WAIT for explicit approval before executing. - **No checkpoints in the brief** -> hand the brief verbatim to one fresh subagent. Verbatim means the brief is the entire prompt; no extra context smuggled in. - **Checkpoints in the brief** -> subagents cannot talk to the user, so either run inline with the brief as the plan, or run one subagent per inter-checkpoint segment, returning to the user at each gate. - **Task depends on conversation state** (builds on the last N minutes of this session) -> run inline. - Subagent runs pay a cold-start tax: the segment must be meaty enough (roughly >5 minutes of work) to amortize it, else run inline. ## Verify - After execution, walk section 6 line by line. Each criterion: pass or fail, stated. - Any deviation from the brief (constraint broken, section skipped, invented value) gets reported, not silently absorbed. - Fail -> fix before reporting done. This is the loop's exit condition, not a formality. ## Worked example The brief below is the reference for register and completeness (a hand-written original, abridged): > Polish [SCREEN] for mobile. Polish pass on existing screen, not a rebuild. Preserve data, routing, behavior. Change presentation only. **(1: task + non-goals)** > Target latest iPhone Pro ~402pt, Dynamic Island, home-indicator safe area; Pixel 9 Pro ~412dp. **(2: target)** > Read DESIGN.md, PRODUCT.md, design tokens before generating. No new colors, radii, shadows, fonts, spacing. Value missing as token -> stop and tell me. **(3: constraint sources)** > Step 1 declutter/distill, step 2 adapt for mobile in product register, step 3 craft pass on the winner. **(4: skill sequence)** > Diagnostic first, I confirm. Show cuts, I confirm. 3 variants, I pick, no auto-accept. **(5: checkpoints)** > Safe areas respected, tap targets >= 44pt, no horizontal overflow, invisible states handled. **(6: verify)** > Diagnostic -> cuts -> variants -> craft pass -> diff summary; flag anything outside tokens. **(7: output contract)** A brief that reads thinner than this is not compiled yet.