/engineering-mission-playbook

name: engineering-mission-playbook
description: "Use when planning or replanning engineering missions that create, change, port, migrate, integrate, or preserve durable codebase behavior across UI, API, CLI, background jobs, data/migrations, libraries, or operator workflows. Defines investigation, scope inventory, coherent VAL-* contracts, evidence floors, multi-target task topology, engineering validation, root-cause patching, and durable guidance. For pure metric search, use optimization-mission-playbook instead."

Engineering Mission Playbook

1. Engineering Success Invariants

Engineering success means the accepted user, caller, operator, or consumer-visible behavior is implemented, preserved, and independently proven on the real surface. Code motion, file diffs, worker claims, green commands, or task completion are not success by themselves.

Success requires:

• accepted scope is preserved through `mission.md` or the current scope charter, the scope/capability inventory, live `VAL-*` assertions, or explicit accepted non-goal/risk decisions;
• every user-mentioned engineering requirement is represented in the inventory and contract unless explicitly removed by the user or a recorded decision;
• contract assertions define the mission's done criteria; task bodies and skills may explain how to work, but they must not hide acceptance promises;
• real user/caller/operator surfaces are tested whenever they exist: browser/UI behavior through an actual browser, APIs through real requests, CLI/TUI behavior through real commands or terminal interaction, background jobs through real triggers and outputs, generated artifacts through real generation and consumption, migrations/data behavior through actual before/after state, and public libraries through real imports/calls;
• validation covers the full requested behavior surface, including common paths, edge cases, error paths, empty states, retries, persistence, compatibility, permissions, unusual but plausible cases, and narrow or low-frequency behaviors that are still part of the accepted scope;
• automated test coverage must include relevant unit, integration, regression, fixture/golden, end-to-end, and system-level checks when those layers exist or are needed to prove the assertion;
• for porting, parity, compatibility, or drop-in replacement missions, the target must pass the relevant original/source test suite, golden corpus, differential command/API checks, and compatibility examples for the accepted source version, unless a specific divergence is explicitly accepted and recorded;
• task topology groups implementation effort without changing assertion granularity, ownership clarity, evidence requirements, or verdict clarity;
• many atomic assertions may map to fewer coherent work tasks when implementation boundaries are shared;
• every live assertion has exactly one active owning `work` task that completes it, not merely contributes to it;
• validators prove assertions independently through the surface and evidence required by each assertion;
• `Needs` and `Evidence` fields are binding: unmet prerequisites, missing evidence, skipped assigned targets, wrong validation surface, or incomplete source-suite parity means blocked or failed, not passed;
• automated tests, source inspection, worker-authored specs, and green commands are supporting evidence unless the assertion names them as the oracle;
• gates and closure claims seal only evidence-backed assertions or explicit accepted-risk/scope decisions.

Do not accept a mission as successful when only happy paths pass, only worker-authored tests pass, only source inspection looks correct, or only a small manually chosen subset was exercised while requested real surfaces, rare cases, compatibility behavior, or source-suite parity remain unproven.

Honest failure is allowed. Do not convert missing setup, weak oracle, broad contract, bad task topology, unavailable evidence, incomplete test coverage, repeated worker miss, or changed scope into a speculative pass, weaker validator method, vague assertion, or late scope shrink.

2. Operating Order

Use this playbook in order. Do not write contract files, task lists, project skills, or durable guidance until investigation has produced an evidence-backed engineering mission model.

On a planning wake, follow this order:

1. **Confirm engineering boundary**: identify which parts of the request are durable engineering behavior, which parts belong to another playbook, and where mixed-domain boundaries sit. 2. **Investigate**: gather evidence for requirements, codebase structure, real user/caller/operator surfaces, environment, setup, existing tests, source baselines, oracles, and fake-pass risks. 3. **Prove validation readiness**: confirm that the intended validation surfaces can actually run. For UI, verify browser access; for API, verify real request paths; for CLI/TUI, verify real commands; for data/migrations/jobs/artifacts, verify setup and observable outputs; for porting/parity, verify access to the source/original suite, golden corpus, or differential oracle. 4. **Write or update the mission scope charter**: capture accepted scope, strategy, expected functionality, setup, infrastructure, validation approach, non-functional requirements, risks, and accepted scope cuts. 5. **Build the scope/capability inventory**: enumerate every requested behavior, workflow, command, endpoint, page, public API, job, artifact, data state, compatibility surface, edge case family, and non-functional promise that must be covered or explicitly decided out of scope. 6. **Author `VAL-*` contract assertions**: convert the inventory into compact, falsifiable validation targets with `Surface`, `Needs`, `Behavior`, and `Evidence`. 7. **Review the contract adversarially**: use `contract-review` before task planning. Fix missing coverage, broad buckets, unverifiable evidence, shortcut paths, and inventory-to-contract mapping gaps before continuing. 8. **Define t