---
name: imp
description: Unified shipping + TRACE self-review protocol (beads, proof, PR). Explicit-only.
---

# IMP

## Intent
Ship bead-scoped changes end-to-end with proof, then immediately self-review the resulting PR using TRACE and fix what you find.

IMP is a combined *execution + review + closure* protocol:
- Write code with strong invariants and minimal incision.
- Validate with a full check suite.
- Open a PR.
- Review that PR right away and resolve findings.
- Select the next bead (so bead state is committed).
- Update/monitor/merge/cleanup (CL).

## Definition of Done (IMP)
An `imp` run is done when:
- The bead’s acceptance criteria are satisfied.
- The working tree contains only bead-aligned changes.
- Format + lint/typecheck + build + tests have run (or are explicitly recorded as unavailable).
- `$close-the-loop` is invoked and at least one signal is recorded.
- The worked bead is marked `done` before PR creation.
- A PR is opened.
- A TRACE self-review is produced (in chat) and all 🔥 + 🟡 items are resolved.
- `$select` is run once (to pick exactly one next bead), and resulting bead state changes (e.g. `issues.jsonl`) are committed into the PR.
- The PR is updated and squash-merged when either:
  - CI is green, or
  - CI is billing-blocked (`billing` appears in CI failure text), `zig build ci` passes, and the PR is squash-mergeable.
- Local state is cleaned up.
- A bead comment exists with PR link + proof summary.

## Guardrails
- Explicit-only; never auto-trigger.
- Source of truth: `bd` wins.
- Surgeon’s principle: smallest correct change.
- No intentional product/semantic changes without clarifying.
- Don’t split into multiple PRs unless explicitly asked.
- Don’t merge until the final CL step.

## Autonomy gate (conviction)
Proceed without asking only when all are true:
- Local repro (or a tight, credible signal).
- Invariant stated.
- Minimal diff.
- At least one validation signal passes.

Otherwise: clarify before editing.

## Core doctrine (canonical)
This section is the single source of truth for how we write and review code.

### Surgeon’s principle
- Prefer the smallest change that could be correct.
- Make progress legible and reversible.
- Trade breadth for certainty: keep diffs bead-scoped.

### TRACE checklist
- Type: make invalid states unrepresentable.
- Readability: understandable in 30 seconds.
- Atomic: one responsibility; explicit side effects.
- Cognitive: minimize branching/hidden deps/cross-file hops.
- Essential: keep only domain-required complexity.

### Complexity Mitigator (CM)
- Keep essential complexity; vaporize incidental.
- Default sequence: flatten → rename → extract.
- If simplification requires new invariants, strengthen them first.

### Invariant Ace (IA)
- Name the invariant at risk and current protection level.
- Prefer construction-time/compile-time guarantees.
- If that’s not viable, add the tightest test/assertion that locks the invariant.

### Universalist (UN)
- Prefer the smallest algebra that fits: product/coproduct/monoid before higher abstractions.
- Name the laws (identity/associativity/composition) and add a lightweight check when feasible.

## Workflow

### 0) Preflight (don’t skip)
- Confirm the repo uses beads (a `.beads/` directory exists).
- Confirm `imp` was explicitly invoked.
- If anything blocks progress (missing requirements, no bead, unrelated diffs), stop and resolve before coding.

### 1) Identify the active bead (source of truth)
1. Anchor on `bd` (not chat context).
2. Find the in-progress bead.
3. If no bead is in progress: invoke `$select` to pick the next `bd ready` bead, then mark it in progress.
4. Restate what “done” means for this bead (1 sentence + acceptance criteria).

### 2) Clarify until requirements are implementable
- Ask only judgment calls (preferences, tradeoffs, acceptance thresholds).
- Everything else should be discovered in-repo (code, tests, conventions) or in the bead.
- If you encounter ambiguity mid-implementation, stop and re-clarify.

### 3) Audit the working tree (scope containment)
- Audit changes early and often.
- Keep only bead-aligned diffs.
- Do not smuggle in drive-by refactors.

If you find unrelated work:
- Revert/stash it (or split it only if explicitly asked).

### 4) Mandatory TRACE mini-pass (before first incision)
Before changing code, do a small `$fix` pass:
1. Cognitive heat map: note hotspots + surprises.
2. Triage failure modes: crash > corruption > logic.
3. State the invariant: what must remain true after the change?
4. Footgun scan: any misuse-prone surface being touched?
5. Incidental complexity: plan to flatten/rename/extract only if it reduces risk.

### 5) Complexity gate (invoke CPS)
If you identify a *complex problem* (multi-constraint, cross-subsystem, high uncertainty, or multiple viable designs), invoke `$creative-problem-solver`.

CPS autonomy rule:
- If a clear **Advantage Play** or **Moonshot** emerges, pick one and proceed.
- Otherwise, ask for human selection before implementation.

Record (in chat and later in proof): chosen tier + rationale + escape hatch.

### 6) Surgeon loop (implement + re-check)
Use a tight loop so progress stays legible and reversible:
1. Form a hypothesis: what change likely satisfies the bead?
2. Choose the smallest incision: smallest change that could be correct.
3. Make it observable: add/adjust a test, invariant, or log to prove/diagnose.
4. Implement: modify code with minimal collateral.
5. Re-check locally: re-run the closest fast signal (focused test, typecheck, repro script).
6. Repeat until acceptance criteria pass.

Heuristics by bead type:
- Bug: reproduce if possible; otherwise create a characterization test or diagnostic signal, then fix.
- Feature: implement the smallest end-to-end slice that users can exercise (vertical slice > layered scaffolding).
- Refactor: preserve behavior; add a characterization test/invariant first.

### 7) Validation (all musts)
Run these categories every time:
- Formatters (autoformat).
- Lint/typecheck (static analysis).
- Build (compile/package).
- Tests (unit/integration as available).

Order (fastest-first):
- Run the fastest local checks first (formatter + lint/typecheck + focused tests).
- Then run the slower checks (build + full test suites).

Entry points:
- Prefer the repo’s canonical entrypoints (`make`, `just`, `task`, `npm run`, `cargo`, `go test`, etc.).
- If multiple relevant entrypoints exist for a category, run all of them (or explicitly justify why one is skipped).

If a category genuinely doesn’t exist, record it as **N/A** in proof with a 1-line reason and run the nearest substitute.

Billing-only CI substitute (Zig):
- Trigger: hosted CI is blocked (CI failure text contains `billing`).
- Run `zig build ci` before opening the PR.
- If CI is still not green at merge time, run `zig build ci` again immediately before squash-merge.
- If `zig build ci` is unavailable, record **N/A**.

### 8) Invoke `$close-the-loop` (required)
`$close-the-loop` is the forcing function: record at least one signal after you’ve made the change and run validations.

### 9) Close the worked bead (required)
Before creating the PR:
- Mark the worked bead as `done`.

Note: this typically updates bead state files (e.g. `issues.jsonl`). Those changes are part of the workflow and must be included in the PR.

### 10) Open a PR (do not merge yet)
- Open a single PR.
- Do not merge yet.

### 11) Immediate TRACE self-review (required, post-PR)
Review the PR output immediately and resolve findings.

Rules:
- Findings must be in severity order.
- Include `file:line` references.
- Include violated TRACE letters.
- Resolve all 🔥 + 🟡 items (no deferrals).

If fixes are required:
- Apply smallest sound fixes.
- Re-run validations (Step 7).
- Re-invoke `$close-the-loop` (Step 8).
- Repeat review until no 🔥 or 🟡 remain.

### 12) Select the next bead (required, post-review)
Run the `$select` workflow once to choose exactly one next bead.

Intent:
- Pick the next `bd ready` bead via risk-first heuristics.
- Verify dependency/readiness.
- Add missing deps and restart selection when needed.
- Mark the chosen bead `in_progress` and leave a short rationale comment.

Critical requirement:
- The bead state changes produced here (commonly `issues.jsonl` updates) must be committed and included in the current PR.

### 13) CL: update PR → check CI + mergeability → squash → cleanup
Follow `codex/prompts/CL.md`, with a billing-only CI bypass:

1. Update the PR.
2. Confirm the PR is squash-mergeable (no merge conflict). If conflicting, merge/rebase the base branch and resolve conflicts.
3. Check CI status (e.g., `gh pr checks`).
4. If CI is green: squash-merge.
5. If CI is not green:
   - If CI failure text contains `billing`: run `zig build ci` (again, immediately before merge). If it passes and the PR is squash-mergeable, squash-merge.
   - Otherwise: keep fixes minimal, and iterate until CI is green.
6. Cleanup local state.

CI policy:
- Default: treat non-`billing` CI failures as real (fix → re-run validations + `$close-the-loop`).
- Bypass: only skip “wait for green” when CI failure text contains `billing`.

### 14) Record proof (make results auditable)
Record proof in both places:
- PR description: full command list + outcomes.
- Bead comment: short proof summary + PR link.

Proof should include:
- Signals: commands run and outcomes.
- Decision: if CPS was used, record tier + rationale + escape hatch.
- Notes: any N/A validations, known limitations.

## Deliverable format (chat)

### A) Work summary
- Bead: `<id>` + 1-sentence “done means”.
- Change summary: what and why.

### B) TRACE self-review (severity order)
For each finding:
- `file:line` — issue — violated TRACE letters — fix applied.

### C) Proof
- Format: `<cmd>` → `<ok/fail>`
- Lint/typecheck: `<cmd>` → `<ok/fail>`
- Build: `<cmd>` → `<ok/fail>`
- Tests: `<cmd>` → `<ok/fail>`
- CI substitute (if `billing`): `zig build ci` (pre-PR; pre-merge if needed) → `<ok/fail>`
- `$close-the-loop`: `<signal>`
- PR: `<url>`
- Merge: `<squash ok/fail>`
- Bead comment: `<posted/blocked>`

## Failure paths
- No in-progress bead: invoke `$select`, mark chosen bead in progress, then proceed.
- Unclear requirements: stop and ask; do not guess.
- Unrelated diffs: ignore; don't touch or stage; continue. If the requested change would touch the same lines/hunks, stop and ask.
- Validation fails: fix and re-run before opening the PR.
- CI is not green:
  - If CI failure text contains `billing`, run `zig build ci` and treat “squash-mergeable + `zig build ci` ok” as green.
  - Otherwise, keep fixing until CI is green.
- PR is not squash-mergeable (merge conflict): merge/rebase the base branch, resolve conflicts, then re-run validations (Step 7) and retry merge.
- Bug can’t be reproduced: add instrumentation or a characterization test; clearly state limits in proof.

## Activation cues
- "imp"
- "ship this bead"
- "implement then review"
- "PR-ready with proof"