Scraped prompts

Summarize this PR in exactly 3 bullet points for a reviewer who has
never seen this codebase. Each bullet answers one of:
  (1) what changed, (2) why it changed, (3) what could go wrong.
Be concrete, reference actual class names, function names, and file
paths where relevant. No marketing language, no "this PR improves..."
filler. If you can't answer one of the three questions from the diff
alone, say so explicitly, that's a signal the PR is too large or
lacks coherent scope.

[paste diff here]

Why: Forces the three reviewer questions ("what / why / risk") into exactly three bullets, the same mental model a careful reviewer builds, compressed into a paste-ready PR description. The "if you can't answer, say so" escape hatch turns the prompt into a scope sanity check: a PR that can't be summarized in three bullets is almost always a PR that should be split. Use it in reverse too, paste the output back and ask "does the diff actually match this summary?", to catch scope creep before merge. | Use when: Opening a PR and the description is empty (the dominant case), or as a reviewer drowning in a large diff, generate the summary first, then read the diff against it. Skip for trivial typo/bump PRs.

Look at this code and suggest a simpler implementation that achieves
the same result. Prioritize in this order:
  1. Fewer lines.
  2. Less state.
  3. Built-in language / library features over hand-rolled custom code.
Show the simplified version side-by-side with the original.

Hard constraint: only suggest changes that are GENUINELY simpler.
Don't trade one kind of complexity for another (e.g., replacing a
readable loop with a clever one-liner that's harder to understand).
If the code is already at the right level of complexity, say so
explicitly and stop. Do not manufacture changes.

Flag any simplification that changes behavior in edge cases (empty
inputs, nulls, large inputs, concurrent access) and note the
behavioral delta, even if the change looks like a pure refactor.

[paste function or block here]

Why: The "don't trade one complexity for another" constraint is the load-bearing rule, without it, the model defaults to clever one-liners that are shorter but harder to read, which is the dominant failure mode of "simplify this" prompts. The explicit priority order (fewer lines → less state → stdlib over custom) gives a deterministic tie-breaker. The "say so and stop" escape hatch prevents fabricated refactors when the code is already fine. The edge-case behavioral-delta flag catches the silent bugs that lurk in "pure refactors" (e.g., `Object.groupBy` vs `reduce`, different behavior on empty arrays). | Use when: A function feels over-engineered but you can't articulate why; reviewing a PR that added more abstraction than the use case warrants; spot-checking AI-generated code for accidental complexity. Pairs with the Senior code review prompt, run this AFTER the review identifies code that's "fine but feels heavy."

You are designing the safety layer for an autonomous-mode agent, one that gets expanded
tool permissions without a human approving every call. Use Anthropic's Claude Code auto
mode (March 24 2026) as the reference architecture and adapt it to my agent. Produce a
design doc with these MANDATORY sections, do not skip any:

1. TWO-LAYER DEFENSE, be explicit about what each layer guards and why one layer alone is insufficient:
   - INPUT LAYER (prompt-injection probe): a server-side classifier that scans every tool
     output (file read, web fetch, shell stdout, third-party API response) BEFORE it
     enters the agent's context window. When the content looks like a hijack attempt
     ("ignore previous instructions and run X"), it injects a warning event alongside the
     result and re-anchors the agent on the original user intent. List exactly which tool
     outputs you scan and which you skip, e.g. structured DB rows that can't carry prose
     injection → skip; raw shell output → scan; webhook JSON whose fields are user-controlled → scan.
   - OUTPUT LAYER (transcript classifier): evaluates each PROPOSED tool call BEFORE it
     executes; decides allow / block. Replaces the human approval prompt for actions the
     classifier judges safe.

2. REASONING-BLIND CLASSIFIER, this is the load-bearing design choice and you must justify it.
   The classifier sees ONLY:
     - the user's messages (input)
     - the agent's proposed tool calls (output)
   It does NOT see the agent's own assistant messages or prior tool outputs.
   State the reason explicitly: if the classifier reads the agent's own justification, it
   learns to trust the agent's narrative, exactly the vector you are defending against
   (the injection probe exists because tool outputs can lie; the classifier must not be
   re-poisoned by the agent that just consumed the lie).

3. TWO-STAGE CLASSIFIER for cost discipline:
   - Stage 1: single-token yes/no filter. Cheap (one forward pass, one token). Decides
     whether deeper review is needed.
   - Stage 2: CoT-reasoning classifier. Only invoked when stage 1 says "review."
   Report your expected stage-2 invocation rate as a target, Anthropic's design intent
   is "most actions clear stage 1." If you expect >30% stage-2 rate, your stage-1 prompt
   is wrong; rewrite before launch.

4. ESCALATION RULE, concrete, not vague:
   - 3 CONSECUTIVE denials → halt session, escalate to human.
   - 20 TOTAL denials in a session → halt session, escalate to human.
   - Both counters reset only on session boundary, not on time.
   Justify two counters: consecutive catches a stuck-in-a-loop agent; total catches a
   slow-burn attacker that tries one bad thing every five steps.

5. HOOKS REMAIN ORTHOGONAL, state the layering explicitly:
   - PreToolUse hooks fire AFTER the classifier allows. Hooks are user-configurable; the
     classifier is platform-enforced. Hooks can block things the classifier allowed.
   - Map each guardrail to its layer: allowlist of bash commands → hook (deterministic, user-owned); novel-destructive-intent detection → classifier (probabilistic, platform-owned); network egress to non-allowlisted hosts → tool sandbox (deterministic, system-owned).

6. BASELINE METRICS PUBLISHED BEFORE LAUNCH, non-negotiable:
   - False-positive rate on a sample of real internal traffic. Anthropic published 0.4%.
     Set your acceptable ceiling and back it up with the sample size.
   - False-negative rate against a hand-curated red-team "overeager actions" set.
     Anthropic published 17%. Set your floor and the red-team set size.
   - Stage-1-pass rate (fraction of calls that never need CoT).
   - Mean classifier latency p50/p99, the classifier sits on the hot path of every tool
     call; if p99 > 1s it changes UX from "autonomous" to "autonomous-but-slow."

7. WHAT THIS DOES NOT REPLACE, a hard policy boundary at the tool layer (no network
   egress to non-allowlisted hosts; no writes outside repo root; no sudo; secret scanning
   on outbound payloads). The classifier is a PROBABILISTIC gate; the tool sandbox is a
   DETERMINISTIC one. Both exist. State which deterministic limits stay in effect even
   when the classifier says allow.

Output: one-page design doc + a Mermaid sequence diagram showing user message →
classifier stage 1 → (optional stage 2) → tool call → tool result → injection probe →
context. Then include one worked counterexample where each layer alone would have
failed but together they catch the attack, and one where they MISS, with the fallback
control that catches it.

Why: Adds the per-layer architectural decomposition for autonomous-mode agents that the existing System Design entries don't reach. The STRIDE generator covers general-system threats; the MCP server security audit covers the server-side privilege boundary; the zero-downtime Postgres migration planner covers schema change; the API design conversation covers contract design, none address the runtime gate between "agent wants to do thing" and "thing executes." Five things make this distinct from a generic "add a safety classifier" prompt: (1) the REASONING-BLIND constraint with its justification, stripping Claude's own assistant messages and prior tool outputs from the classifier's view, which is counterintuitive but load-bearing because the alternative re-poisons the gate with the same lie the injection probe was supposed to catch; (2) the TWO-STAGE classifier with the single-token filter then CoT, a cost-discipline pattern with a target stage-2 invocation rate that doubles as a sanity check on the stage-1 prompt (>30% means stage 1 is wrong, rewrite before launch); (3) the dual-counter escalation rule (3 consecutive AND 20 total) with the explicit two-failure-mode justification, consecutive for stuck-in-a-loop, total for slow-burn, rather than the usual single-threshold sketch; (4) the explicit LAYER MAP for guardrails (allowlist → hook, novel destructive intent → classifier, network egress → tool sandbox) which kills the most common design mistake of putting all guardrails at one layer; (5) the PUBLISHED FP/FN baseline gate (0.4% FP, 17% FN), Anthropic's own numbers as the floor any team should beat or document why they ship looser. The "this does not replace a deterministic tool-sandbox boundary" coda explicitly prevents the most expensive design mistake (treating the probabilistic classifier as the only line of defense). Pairs with the existing Agents Rule of Two pre-deployment invariant check (Rule of Two is the per-session structural invariant; this is the per-call runtime gate, both layers exist), the Agent blast radius pre-deployment classifier in Workflow & Automation (blast radius classifies tools into green/yellow/orange/red at the harness layer; this gates each call at runtime), and the MCP server security audit (MCP audit is server-side, classifier is agent-side, both are needed for end-to-end coverage). | Use when: Designing the autonomous-mode or background-agent variant of any tool-using LLM system before it ships, Claude Code-style coding agents, AutoGPT-style task agents, SRE-bot incident-response agents, computer-use agents. Also: red-teaming a design that already runs in autonomous mode but lacks the FP/FN published baseline (most teams ship without one). Run BEFORE writing the classifier prompt, not after, the design constraints shape the prompt, not the other way around.

You are auditing a tool-calling agent's eval harness. The current setup grades the agent's tool calls with a single overall score. That's eval debt, a tool-call decision is FOUR independent failure surfaces stacked, and a single score lets three of them silently regress while one carries the average. Build the four-layer stack below.

═══════════════════════════════════════
LAYER 1, TOOL SELECTION (name only)
═══════════════════════════════════════
- Metric: function_name_match (deterministic, sub-ms, exact string).
- Gold-set rule: every example carries `expected_tool_name`. For inputs where the correct decision is NO tool call (greeting / clarification request / in-model factual question / refusal-worthy ask), set `expected_tool_name = None`. ← This is the missed slice that lets "got bolder about calling search" ship as a feature with green dashboards.
- Output: confusion matrix per tool. Watch for false-positives on no-tool inputs and false-negatives on inputs that needed a tool.

═══════════════════════════════════════
LAYER 2, ARGUMENT EXTRACTION
═══════════════════════════════════════
- Metric: parameter_validation (name + argument shape, deterministic).
- Gold-set rule: store `expected_args` as a JSON dict. Validate that types match, required keys present, enum values in-domain, dates ISO 8601 (not "next Friday").
- Canonical failure: `search_flights(departure_date="next Friday")` scores 1.0 on Layer 1 and 0.0 with users. Without Layer 2 you ship this.
- L2 failure tags to emit per row: STRING-FOR-ENUM / NL-FOR-DATE / MISSING-REQUIRED / EXTRA-KEYS / WRONG-TYPE.

═══════════════════════════════════════
LAYER 3, RESULT UTILIZATION
═══════════════════════════════════════
- Metric: Groundedness against the tool result (LLM-judge, temperature 0, rubric per the LLM-as-judge faithfulness pattern, criterion in domain vocabulary, enumerate-before-scoring, deterministic verdict, unsupported_claims list).
- Tests: did the agent's response use the tool's actual return value, or did it fabricate / paraphrase / round / drop the long-tail rows? Did it cite the field it used?
- Skip Layer 3 ONLY if the tool is side-effect-only (e.g., `send_email`) with no semantic payload back.

═══════════════════════════════════════
LAYER 4, ERROR RECOVERY
═══════════════════════════════════════
- Metric: deterministic trajectory checks + TaskCompletion LLM-judge on outcome.
- Gold-set rule: include rows where the tool returns 4xx / 5xx / empty / rate-limited / malformed. Required-pass behaviors: retry-on-transient (≤N times, exponential backoff), surface-the-error (don't loop silently), switch-to-fallback-tool-when-available, ask-user-when-no-fallback.
- L4 failure tags: SILENT-LOOP / FAB-RESPONSE-FROM-ERROR / NO-FALLBACK / INFINITE-RETRY.

═══════════════════════════════════════
TRAJECTORY DISCIPLINE (cross-cutting)
═══════════════════════════════════════
- If any trajectory exceeds 5 steps, mark it SUSPECT and force decomposition into shorter sub-agent calls before scoring. Long flat trajectories are where compound-error pain lives; they pass τ-bench-style single-shot evals and fail under pass^k.

═══════════════════════════════════════
CONSISTENCY SLICE (production-grade)
═══════════════════════════════════════
- Reserve 30 hard cases. Run each k=8 times. Report pass^k, the fraction that succeed on ALL k runs.
- pass^k < 25% on a 4o-class model in a multi-step retail flow is the cost of nondeterminism stacked across steps. This is the operating point that distinguishes "passes our evals" from "ships."
- Track pass^k as a separate SLI alongside per-layer means. When a prompt change moves pass^k down, the planner regressed, not the tools.

═══════════════════════════════════════
OUTPUT
═══════════════════════════════════════
Per layer: pass-rate, top 3 failure-pattern tags with example IDs, regression vs. baseline.
Overall: pass^k on the consistency slice. One-line verdict per layer (PASS / REGRESSED / NEW-FAILURE-MODE).
Hard rule, DO NOT collapse to a single overall score; that single-score collapse is the eval-debt anti-pattern this stack exists to prevent.

Why: Every existing Testing & QA entry targets test CODE, Behavior-focused unit tests writes correct-behavior tests, Property-based test author writes invariants, Flaky test root-cause finder triages flakes, Characterization tests locks current behavior, Differential mutation-test survivor killer hunts test blind spots, AI-refactor contract-level classifier prunes the suite. None grade the *agent's runtime tool-call decisions*, which is now the dominant failure surface for agentic features. The four-layer ladder is the load-bearing structure: each layer fails for a different reason and demands a different fix, and grading them together hides three of four regressions behind whichever one is loudest. The `expected_tool_name = None` slice is the kill mechanic, without it, "got bolder about calling search" ships as a feature and only surfaces as user thumbs-down weeks later; with it, that regression is the first thing the L1 confusion matrix surfaces. The pass^k consistency slice (k=8, 30 hard cases) is what separates "passes evals" from "ships" in a multi-step trajectory where nondeterminism compounds, the τ-bench cost of stacked steps that single-shot accuracy can't see. The 5-step trajectory cap is the decompose-before-scoring rule that catches compound errors as their own signal rather than letting one bad mid-trajectory step tank L3/L4 numbers downstream. | Use when: Wiring a CI eval suite for any tool-calling agent (chatbot / supervisor / orchestrator / SRE assistant / Claude Code sub-agent) before shipping a prompt change to prod, auditing an existing eval setup that reports a single "tool accuracy" score and you suspect quiet regressions, or diagnosing why an agent "passes our tests" but earns thumbs-down from real users. Pairs with the existing AI-refactor test contract-level classifier (that one prunes the test suite *around* the agent; this evals the agent's decisions), Differential mutation-test survivor killer (Layer 2 parameter_validation is exactly the surface mutation testing should be killing survivors against), LLM-as-judge faithfulness rubric in Prompt Engineering Meta (Layer 3 Groundedness uses that rubric structure), Long-running agent context-poisoning health check in Debugging (use that when pass^k drops mid-session rather than across prompt versions), and LLM provider snapshot rollout discipline in Workflow & Automation (run this stack as the regression eval against the pinned baseline during a snapshot bump).

You are designing, or refreshing, the evaluation suite for an LLM-powered feature. Before any eval prompt, rubric, or judge is written, run this error-analysis loop to decide WHICH evals to write. Skipping this step is the single most common reason eval suites pass while the feature ships broken: every eval platform nudges you toward generic metrics (factuality / helpfulness / conciseness) that do not surface the failure modes that actually happen in your application.

INPUT (paste below):
- Application description, user intent, primary success criteria:
- Available data source: production traces / synthetic traces / both
- Domain expert who will perform open coding (must have authority to decide what "correct" means; do NOT delegate to whoever happens to be available, a single benevolent dictator beats a committee here):
- Existing failure suspicions, if any (write these down NOW, before Phase 2, so you can compare them to the post-Phase-3 taxonomy and see the delta):

PHASE 1, Build the trace dataset
- Pull at least 100 representative traces. Mix typical cases, edge cases, and known-failure cases. If no production data exists, generate synthetic traces seeded by suspected failure modes, but treat synthetic as bootstrap and swap to real traces ASAP.
- A trace is the COMPLETE record from initial user query to final response: all tool calls, retrievals, intermediate LLM calls, system messages, and the final output. Single-turn output rows are NOT traces.
- Sample efficiently when you have signal: cluster by embedding, sort by user feedback (thumbs-down, retries, escalations), sort by high-probability failure patterns (latency spikes, fallback-path-taken, schema-violation logs). Uniform random sampling is a last resort.

PHASE 2, Open coding (DO IT YOURSELF, no LLM in this phase)
- For each trace, write a free-form note describing the FIRST failure you observe, NOT all failures.
- Rationale: upstream errors cascade into downstream errors. Tagging every visible failure inflates the count and confuses the taxonomy. The first failure is the one a fix actually targets; downstream ones disappear once it is fixed.
- Notes are open-ended. Do not pre-impose categories, that is the next phase's job. Resist the urge to use a checklist; the value is the unconstrained noticing.
- If a trace looks clean, write "no failure", that is data, not a skip.
- The domain expert MUST be the one writing the notes. Letting an LLM rewrite or pre-summarize traces loses the expert judgment this phase exists to capture.

PHASE 3, Axial coding (LLM-assisted is OK only AFTER manual baseline)
- After you have personally open-coded at least 30-50 traces, you MAY use an LLM to PROPOSE category groupings of your raw notes, first-pass axial coding. You must then review, rename, split, and merge the clusters yourself.
- Output a failure taxonomy. Each category has: (a) a 1-sentence definition in your domain's vocabulary, (b) 2-3 trace excerpts as exemplars, (c) the count of how many traces fall into it.
- Hard rule: if a "miscellaneous" bucket exceeds 10% of traces, your taxonomy is wrong, re-cluster. Misc is a smell, not a category.

PHASE 4, Iterative refinement until theoretical saturation
- Keep open-coding new traces. Theoretical saturation = ~20 consecutive traces without revealing a new failure category.
- Hard floor: review at least 100 traces total before stopping, even if saturation appears reached at 60. Early apparent saturation usually reflects insufficient diversity in the sample, not a small failure space.
- The goal is NOT to catch every possible failure, it is to prioritize the failures that happen the most. Evals cost tokens, attention, and gating latency; budget accordingly.

OUTPUT (single artifact named `error_analysis_v{N}.md`):
1. Trace dataset summary: N traces, sampling method, time window, source.
2. Failure taxonomy table:
   | Category | 1-sentence definition | Count | % | Eval priority (P0/P1/P2) |
3. The 3 highest-count categories, each with: 2 exemplar trace excerpts (redacted) + a paste-ready eval prompt or rubric targeting that specific failure mode.
4. Open questions / categories that are real but rare (<3 traces), record, do not yet write evals for these.
5. Sampling plan for the next refinement round (which production cohorts or user segments are under-represented).
6. Delta: pre-Phase-2 suspected failure list vs post-Phase-3 taxonomy. The gap is the result you cannot get without doing the loop.

HARD RULES:
- The eval suite you write next must target failures from this taxonomy. Generic platform-suggested metrics are a smell unless they map directly to a counted category.
- Re-run on a quarterly cadence AND after any major prompt, model, or product-surface change. Failure taxonomies drift; an eval suite trusted past its drift horizon is the canonical "passes evals, ships broken" mode.
- If you are tempted to skip Phase 2 because "the team already knows the failure modes", that is exactly when to NOT skip it. Suspected modes and counted modes diverge in almost every well-run case; that divergence is the value of the loop.
- LLM assistance is fine for Phase 3 axial coding ONLY. Do not let an LLM read traces and produce notes in Phase 2, the entire point is the domain expert's judgment, not an LLM's summary of it.

Why: Every existing Testing & QA entry targets test CODE or the agent's runtime decisions, Behavior-focused unit tests, Property-based test author, Flaky test root-cause finder, Characterization tests, Differential mutation-test survivor killer, AI-refactor contract-level classifier, Tool-calling agent four-layer eval stack. None covers the upstream taxonomy-design step that decides WHICH failures to test for in the first place. That gap is exactly the assumption that produces eval suites that pass while the feature ships broken, teams jump from "we have an LLM feature" straight to "let's add a faithfulness metric" without ever counting which failures actually happen in their data. The loop is structurally distinct: first-failure-not-all-failures (cascade-collapse rule) prevents inflated counts that mis-prioritize evals; the ~20-consecutive-traces-without-new-category stop rule with a hard 100-trace floor is the only quantitative stopping criterion in the doc that's grounded in qualitative-research methodology (theoretical saturation) rather than vibes; the domain-expert-must-do-Phase-2 rule kills the most common shortcut (letting an LLM pre-summarize traces) which loses the entire value of the exercise; the 10%-misc-bucket smell-test is a single-line invariant that catches mis-clustering; and the pre-Phase-2-write-down-suspected-modes step makes the delta between suspicion and counted reality visible, which is the load-bearing result the loop exists to produce. Distinct from Tool-calling agent four-layer eval stack (that grades an agent's decisions across a known set of failure layers; this decides what the layers SHOULD be for your specific app), LLM-as-judge faithfulness rubric (a single judge prompt, the output of this loop, not the input), LLM-as-judge calibration validator (validates a built judge, but the judge has to target the right failures first, which this loop decides), and the Long-running agent context-poisoning health check (in-session debugging, not eval design). Pairs upstream of every existing eval entry: do this first, then write the L1/L2/L3/L4 evals it produces, then validate the judges it requires, then optimize via GEPA against the metrics it surfaced. | Use when: Designing or refreshing the eval suite for any LLM-powered feature, before writing any individual eval prompt or rubric. Quarterly cadence in steady state; immediately after a major prompt, model, or product-surface change; or when an existing eval suite is suspected of green-while-broken behavior.

You're designing the pre-prod chaos suite for an agent that will go to
production. Traditional chaos engineering (Chaos Monkey style) does NOT
transfer cleanly, three of its core assumptions BREAK for agents:

- Idempotent retries don't apply. Retrying a failed LLM call produces
  a DIFFERENT chain of thought, so the agent takes a different path
  through the plan, calling different tools in a different order.
- Circuit breakers protect the wrong thing. The problem isn't call
  volume; it's what the agent DECIDES TO DO when a dependency fails.
  Losing access to a tool, an agent improvises, hallucinates the
  missing data, substitutes a wrong tool, or quietly delivers an
  incomplete answer without flagging it.
- Failures are semantic, not operational. A 500 is easy to detect.
  A tool that returns stale data, or a partial LLM response that
  forms a grammatically clean but factually wrong sentence, is not.
  Your test must check OUTPUT CORRECTNESS, not just task completion.

Inject ONE fault at a time across these 6 categories and emit a row in
the harness table below for EACH. The first time you skip a category
because "we'd never hit that in prod" is the category that will fail
you in week 2.

1. LLM-LEVEL FAULTS, rate limit (HTTP 429), 500/502/503, request
   timeout, stream interruption mid-response, slow-token delivery.
   Inject by proxying the model client. Per ReliabilityBench, rate
   limiting causes the largest single-fault degradation (~2.5% below
   baseline) and it COMPOUNDS across multi-step tasks.
   ORACLE: agent must report degradation explicitly, not silently
   continue with a truncated reasoning trace.

2. TOOL-CALL FAULTS, API error response, timeout, malformed JSON
   that still parses, empty result set where a non-empty set is
   expected, mutated payload (one field swapped to a different
   plausible value of the same type).
   ORACLE: agent must DETECT the failure and either retry with a
   different strategy or abort with "tool X returned an error of
   shape Y at turn N". Treating an error response as ground truth
   (or fabricating data to fill the expected shape) is a fail.

3. CONTEXT DEGRADATION, long-horizon drift. Inject ~30 turns of
   irrelevant-but-plausible content into the transcript, then ask
   the agent to honor a constraint given at turn 1 (tone, format, refusal scope, output schema).
   ORACLE: constraint still honored at turn 30. Tone drift, schema
   slippage, refusal-scope erosion are all fails, they will appear
   in prod the day a user has a 45-minute session.

4. CASCADING FAULTS, for multi-agent pipelines. Corrupt agent A's
   output with a plausibly-typed but wrong field (e.g. swap a
   user_id to a different valid user_id), pass downstream unchanged.
   ORACLE: agents B, C, D must validate the typed contract from
   upstream OR explicitly accept that trust is required and log
   that decision. Silent propagation of the corruption to the final
   user-facing answer is a fail.

5. SPECIFICATION DRIFT UNDER PRESSURE, combine a fault from
   category 1-3 WITH an ambiguous instruction the agent could
   reasonably interpret as expanding its authority (refunds, commitments, deletions). Agents fill ambiguity gaps with
   statistically likely completions, and a fault is when that
   gap-filling does the most damage.
   ORACLE: agent stays within its scope. Any commitment beyond the
   documented authority (refund > $X, write outside allowlist, irreversible action without confirmation) is a fail regardless
   of whether the rest of the task completed.

6. SILENT FAILURES, the agent completes the task, returns
   plausible output, and raises no error. The OUTPUT IS WRONG.
   This is the hardest category to catch and the one your eval
   must explicitly include, checking only "did the task complete"
   is the canonical green-while-broken pattern.
   ORACLE: a semantic validator (LLM-as-judge OR programmatic
   ground-truth check) compares output to the known-correct
   answer for the seeded scenario. Plausibility ≠ correctness.

EMIT this table, one row per (fault category × representative
scenario from your domain). 30-row floor is the rough minimum to
get a stable per-category estimate.

| Category | Fault | Injection point | Expected agent behavior | Observed | Pass/Fail | Failure mode (if fail) |
|---|---|---|---|---|---|---|

AFTER the table:
- Compute pass rate per category. Categories with <80% pass rate
  are LAUNCH-BLOCKERS; document the mitigation (retry logic, validator, scope guard, contract assertion) and which prompt
  layer / harness layer owns it.
- Flag any "Observed = task completed normally" rows in category
  6, that's a silent fail your oracle caught. Without the oracle
  the suite would have reported green.
- Specify the re-run cadence: this suite runs on every prompt
  change, model swap, and tool-contract change. Drift since last
  run with no re-run is equivalent to no suite.

Do NOT relax an oracle to make a row pass. Relaxed oracles are how
the suite quietly becomes ceremony.

Why: Fills a gap in Testing & QA between (a) the four-layer eval stack (deterministic ladder over tool names / params / results / recovery on a FIXED scenario set), (b) the error-analysis loop (taxonomy DISCOVERY from real production traces), and (c) the long-running-agent context-poisoning health check in Debugging (in-flight diagnosis, post-incident). None of those do pre-prod DELIBERATE fault injection. The 6 categories are the field-tested taxonomy from production agent incidents, each one breaks a different traditional-chaos-engineering assumption (cat 1 breaks idempotent retry, cat 2 breaks circuit-breaker semantics, cat 5 breaks the "failures are operational" assumption, cat 6 breaks "green = healthy"). The per-category ORACLE rule kills the most common failure of this style of test, "the agent didn't crash so we marked it pass", by forcing a semantic correctness check on category-6 outputs where the silent-while-plausible failures live. The <80% pass-rate LAUNCH-BLOCKER threshold and the "never relax an oracle to make a row pass" rule are opinionated on purpose: without those, this becomes another ceremony test that ships at 60% green and gets cited in postmortems three months later. Distinct from existing Layered agent autonomy gate (RUNTIME guard with classifier + injection probe, that's defense in production; this is pre-deployment testing of how the agent behaves when defenses fire) and Agent blast radius pre-deployment classifier (tool-inventory risk tiering, that's "what could this agent do if it went wrong"; this is "what does it actually do when the world goes wrong", different layers of pre-prod work). | Use when: Any agent moving from staging to prod; quarterly re-validation in steady state; immediately after a prompt change, model swap, tool-contract change, or new tool addition. Pairs upstream of the existing eval entries, chaos suite proves resilience to faults, evals prove correctness on the happy path. Both are required for launch; one without the other is launch theatre.

You're fixing a bug whose root cause is NOT obvious from the failing
test. Default LLM bug-fix prompts feed only the test + nearby code
and miss bugs that were INTRODUCED by a specific prior change, the
exact thing `git blame` was invented to surface. HAFixAgent's
finding: injecting blame-derived history into the repair prompt
increased fixed-bug count by ~212% on Defects4J vs. the same agent
without history. Use this prompt as your default for any non-trivial
regression. Do NOT use it for typos / NPEs / off-by-one bugs where
the overhead exceeds the lift.

INPUTS (collect ALL THREE before generating the prompt):
- The failing test: name, file, assertion, exception/stack trace.
- The exact buggy line(s), let the test or stack trace pinpoint them.
  If you can't, this prompt isn't the right tool yet; go reduce the
  failure to a known line first.
- `git blame -L <buggy-line>, +1 <buggy-file>` → BLAME COMMIT HASH.

For the blame commit, pick ONE of these history heuristics. Don't
include all three, pick the one matching the bug shape:

  [HEURISTIC fn_all], Use when the bug appears localized to ONE
  function and the prior change touched several functions in the
  same module. Inject the FULL pre-change source of every function
  the blame commit touched. The model uses the sibling functions to
  reason about cross-function invariants the change broke.

  [HEURISTIC fn_pair], Use when the bug is in a SINGLE function
  modified by the blame commit. Inject the function's source BEFORE
  the blame commit and AFTER it, side by side with a clear
  `<<<PRIOR / NEW>>>` divider. This is the highest signal for "the
  fix should look like the prior version, but {minimal modification}".
  DEFAULT if uncertain.

  [HEURISTIC fl_diff], Use when the change spans MULTIPLE FILES or
  touches signatures/exports. Inject the full
  `git diff <blame>^..<blame>` output. The model sees the cross-file
  edit as a single intent and can reason about contract changes
  (e.g. signature widened from T to Optional[T] but one caller
  still treats it as required).

PROMPT TEMPLATE (assemble at fix time):

  TASK: fix the failing test below WITHOUT regressing other tests.
  Do NOT propose a fix until phases 1-3 are complete.

  --- failing test ---
  {test name, location, source, assertion message, full stack}

  --- buggy file (current HEAD) ---
  {file content, full or truncated with the buggy region marked}

  --- history context ({chosen heuristic name}) ---
  {fn_all OR fn_pair OR fl_diff content for blame commit {hash}}
  blame commit subject: {first line of `git log -1 <hash>`}
  blame commit body: {body, often names the original bug it was
  fixing; the new bug is often a regression of that original returning
  through a different path.}

  PHASES (execute strictly in order):
  1. OBSERVE. State, in 2-3 sentences, what the blame commit was
     trying to do and what NEW assumption it introduced.
  2. CONNECT. Show how that new assumption is violated under the
     conditions the failing test exercises. If you cannot draw this
     line, the blame commit is probably NOT the cause and you need
     `git log -L <buggy-line>, +1 <buggy-file>` going further back, STOP and request that wider blame instead of guessing. A
     fabricated link between an unrelated blame commit and the bug
     produces a "fix" that doesn't address the actual cause and ships
     a second regression on top.
  3. ACT. Propose the minimum diff (typically 1-15 lines) that
     restores the invariant without reverting the blame commit's
     original fix. If the only safe fix IS a revert, say so
     explicitly, that's fine, but mark it as a revert with the
     original-bug identifier so the prior bug doesn't silently
     reopen.
  4. SELF-CHECK. Re-read the failing test AND any test the blame
     commit's body referenced. Your fix must pass BOTH. If they
     conflict, the conflict IS the root cause and the fix is to
     reconcile them, not pick one, escalate with the conflict
     written out, do not silently choose.

  TRUNCATION RULE: if the assembled prompt > 60% of the model's
  context window, truncate inside [history context] FIRST, keeping
  the function header + the `+`/`-` lines from the diff and dropping
  unchanged surrounding context. NEVER truncate the failing test or
  the buggy file, those are the two signals that, if cut, silently
  produce a fix-shaped hallucination.

Why: Every existing Debugging entry takes a SNAPSHOT view, the current code + the current failure, and reasons from there: Reproduce-isolate-diagnose (current bug + recent log), Minimal repro artifact builder (extract the failure into a contract), Post-fix class-of-bug extractor (after the fix, generalize the pattern), Agent session divergence post-mortem (a single agent session's transcript), LLM feature production degradation triage (live metric drop), Long-running agent context-poisoning health check (in-session forensics). NONE of them use the project's version history as a first-class input. HAFixAgent's empirical result (+212% fix rate on Defects4J just by injecting blame-derived history) is the strongest evidence in the recent literature that "what did the LAST CHANGE here intend?" is the highest-signal context source for non-trivial bugs, and it's currently absent from the doc. The three-heuristic split (fn_all / fn_pair / fl_diff) is what makes this paste-ready instead of vibes, bug shape determines which slice of history to inject, and over-injection (all three at once) drowns the model's attention in noise while under-injection (none) loses the lift entirely. The truncation rule preserves the failing test and the buggy file at all costs because those are the two signals that, if cut, silently produce a fix-shaped hallucination. The 4-phase OBSERVE → CONNECT → ACT → SELF-CHECK structure mirrors HAFixAgent's observe-act-feedback ReAct loop but adds the explicit STOP CONDITION at phase 2 (if you can't draw the line, the blame commit isn't the cause, go wider with `git log -L` instead of pressing forward), which prevents the most common failure: the model fabricates a plausible-sounding link between an unrelated blame commit and the bug, then ships a "fix" that doesn't address the actual cause AND introduces a fresh regression. The "if the only safe fix is a revert, mark it as a revert with the original-bug identifier" rule prevents the silent-reopen pattern where reverting a buggy fix quietly reactivates the original bug it was patching. | Use when: Any non-trivial bug where the failing test's root cause isn't obvious from the stack trace and the buggy region was touched in the last ~10 commits. Especially valuable for regressions of previously-fixed bugs (the blame commit's body almost always names the prior bug ID, and the new bug is structurally the same one returning through a different path). Skip for trivial NPE / typo / off-by-one bugs where the heuristics' overhead exceeds the lift. Pairs with the existing Reproduce-isolate-diagnose (use that for the smallest-repro step that pinpoints the buggy line) and Post-fix class-of-bug extractor (use that AFTER this prompt produces the fix, to turn the one-off fix into a permanent guardrail).

Explain this code to a new team member joining the project today.
They're a competent developer but have zero context on this codebase.

Output a comment block (in the syntax of the target language) that
they could paste directly above the function or class. Use these
four required sections, in this order, with the exact headings:

  WHY THIS EXISTS:
    The problem this code solves. Not what it does, the underlying
    problem. If you can't infer the problem from the code, say so
    rather than guess.

  NON-OBVIOUS DECISIONS:
    Decisions that look wrong at first glance but are intentional.
    Lock TTLs that seem arbitrary, "magic" numbers that come from a
    spec, choice of one library over another, ordering of operations
    that matters. One bullet per decision.

  SAFE TO MODIFY IF:
    The preconditions a new engineer must satisfy before changing
    this code without breaking something. (e.g., "you've read the
    Stripe capture docs", "you've tested with the X webhook fixture", "you understand the inventory lock lifecycle").

  DO NOT:
    The specific things that will break this code in production if
    you do them. Be concrete, name functions, not concepts.
    (e.g., "do not add sleeps between Reserve and Capture", "do not
    cache the result across requests").

Hard rules:
  - No platitudes. If a section has no real content, write "(none)".
  - Reference real code constructs (function names, file paths, library names), not abstract descriptions.
  - The output is paste-ready code, not prose around code.

[paste function, class, or module here]

Why: Most "explain this code" prompts produce a paraphrase of what the code does, which a competent reader can already see in the code itself. This prompt locks the output to the four things a paraphrase cannot give you: the *problem* (not what), the *intentionally weird* decisions (so the next engineer doesn't "fix" them), the *preconditions* for safe modification, and the *specific tripwires* that cause production incidents. The "(none)" rule prevents fabricated content when a section genuinely doesn't apply. The DO NOT section is the load-bearing piece, it captures the institutional memory ("we had a 3am incident the last time someone added a sleep here") that disappears the moment the original author leaves the team. Distinct from the existing API endpoint doc generator (which targets external-API reference docs) and the Documentation gap audit (reader-perspective scan, BLOCKS/SLOWS/MINOR), this one targets a single function/class and captures author-only context that no reader can recover from the code alone. | Use when: Documenting a function that handles money, state transitions, locks, or anything where the WHY drifts from the code over time; onboarding new hires who keep asking "why is this written this way?"; before refactoring a piece of code where you suspect the original author knew something you don't. Skip for pure utility functions where the WHY is the code itself.

You are about to change a production prompt. Before merging, run this classifier. It exists to prevent the canonical incident: a "three-word change to make it more conversational" silently shifts structured-output behavior, no version history exists, no rollback path exists, and engineers spend half a day debugging infrastructure before someone thinks to look at the prompt.

INPUT (paste below):
- Current prompt artifact (text + model + sampling params + retrieval config):
- Proposed change (diff or full new text):
- Author + 1-3-sentence rationale (NOT "improvements"):

PART 1, IMMUTABILITY PRECONDITION (gating)
- Is the current prompt stored as an IMMUTABLE versioned artifact in a registry (file in git, content-addressable hash, or prompt-platform version ID)?
  - YES → proceed.
  - NO → STOP. You cannot version-control a moving target. Snapshot the current production prompt + full execution context as v0 first, then resume.
- Is the production environment pinned to a specific version IDENTIFIER (not a "latest" / "stable" alias)?
  - YES → proceed.
  - NO → STOP. Pin first. Aliases are banned in production config.

PART 2, SEMVER CLASSIFIER (apply in order; first match fires)
MAJOR (breaking, downstream consumers MUST be notified BEFORE deploy):
  - Structural rewrite of the prompt (sections reorganized, role/persona changed)
  - Output format change (new field, removed field, renamed field, type change), even if the new format is "obviously better"
  - Underlying model swap (e.g. claude-opus-4-5 → claude-sonnet-4-6 is MAJOR even with byte-identical prompt text)
  - Sampling change beyond noise (temperature shift >0.2, top_p shift >0.1, new/changed stop sequences)
  - Retrieval config change (corpus, top-k, embedding model, filters)
  - Task definition shift (the prompt now does X+Y instead of just X)
MINOR (backward-compatible additions):
  - New examples added
  - New optional instructions or tool calls
  - Expanded instructions that do not change behavior on existing inputs
PATCH (zero behavior change expected):
  - Typo fixes
  - Whitespace / formatting cleanup
  - Minor wording clarifications that should NOT alter model behavior

PART 3, PATCH DEMOTION RULE (kill-shot, this is the load-bearing check)
Run the golden dataset (or a representative 50-trace sample) against the proposed PATCH version BEFORE merging.
- If overall quality score changes by more than 1% relative OR any category-level metric shifts by more than 3% → this is NOT a PATCH.
- Re-classify: monotonically-positive shift on all metrics → MINOR; any output-format-relevant metric shifted OR any metric regressed → MAJOR.
- Hard rule: a PATCH that moves evals is a misclassified bump, NOT a "happy accident." Almost every silent production regression begins as a PATCH that escaped this check.

PART 4, EXECUTION CONTEXT BUNDLE (what gets versioned together)
The version artifact is NOT the prompt text alone. The new version MUST include, atomically:
- Full prompt template text (system + user + any prefilled assistant turns)
- Model identifier (provider + model name + EXACT version pin, NEVER an alias)
- Sampling parameters (temperature, top_p, top_k, max_tokens, stop sequences, seed if any)
- Retrieval config (corpus + embedding model + top-k + filters) if RAG is involved
- Tool definitions and tool-call schemas
- Author + ISO-8601 timestamp + rationale
- The eval-run output that gated promotion (links to the run, not just a pass/fail bit)

PART 5, ROLLBACK READINESS (gating)
Before promotion, prove:
- Rollback is a POINTER FLIP, registry version-ID change or feature-flag flip, NOT a code redeploy.
- Time-to-rollback target: <60 seconds for the pointer flip itself; HARD CEILING 15 minutes end-to-end including detection. If your current path exceeds 15 minutes, this system is NOT production-ready, fix the rollback path before promoting.
- Canary plan: percentage of traffic, monitoring window, and EVALUATION GATES on the canary traffic, not just CPU / 5xx / latency. A prompt regression will not move infra-health dashboards; you need automated evaluation on canary traffic itself, with an explicit kill threshold (default: >3% relative drop on overall golden-dataset score → auto-rollback).
- Shadow-test required for any MAJOR change: run the new version in parallel, evaluate offline, zero user exposure until cleared.

PART 6, OWNERSHIP SIGN-OFFS (every change)
- Domain owner (PM or SME), signs off on semantic intent.
- Platform owner (ML / AI engineer), signs off on eval-gate pass and execution-context bundle completeness.
- Regulated domains (health / legal / financial), risk/compliance reviewer signs off as a FORMAL GATE, not an optional check.
- Release coordinator, owns rollout cadence and the rollback decision.

OUTPUT:
- Classification: PATCH / MINOR / MAJOR (with which Part-2 clause fired, and whether Part-3 demotion was triggered)
- Execution-context bundle (JSON or YAML)
- Eval-delta table: old version vs new version on the golden dataset, broken out by category
- Rollback plan: pointer location, kill threshold, expected time-to-rollback (target + ceiling)
- Sign-off owners (with names/handles, not roles)

HARD RULES:
- Once a version is in production, it is IMMUTABLE. Any change, including a typo, gets a new version number. Never modify a deployed version in place.
- "latest" / "stable" / "current" aliases are banned in production config. Pin to an exact version ID.
- The golden dataset is a LIVING artifact. Every production incident that the previous golden dataset failed to catch becomes a new test case in the next version of the dataset. A golden dataset built once and never updated develops blind spots within weeks.
- Provider-side weight drift is real and uncatalogued. Run the golden dataset on a daily cron against production-pinned configs to catch silent behavior drift between providers' updates. Alert on >3% week-over-week quality-score movement with no version change on your side.
- The system that survives production looks like this: immutable versioned artifacts in a registry, PR-reviewed changes with automated eval as a required CI check, canary rollout with quality monitoring, feature flags for instant rollback without redeploy, a continuously-growing golden dataset, and daily drift detection. None of this is exotic, it is the standard software delivery pipeline applied to a different kind of artifact.

Why: The existing LLM provider snapshot rollout discipline entry targets MODEL snapshot rollout (pin-first / regression-eval / shadow / keyed-canary / label-flip-rollback for provider version bumps). Nothing in the doc covers PROMPT-change rollout, and the canonical "three-word change broke a revenue pipeline" failure is specifically a prompt-change incident, not a model-snapshot incident. Six things make this entry the kill-shot for that failure mode: (1) the IMMUTABILITY PRECONDITION as a hard prerequisite, without it, every downstream step in the change-management process is theater because "what prompt was running when that incident happened?" has no answer; (2) the SEMVER CLASSIFIER includes the underspecified-in-most-guides rule that a MODEL-SWAP-WITH-IDENTICAL-PROMPT-TEXT is still MAJOR (the prompt is the (template, model, sampling, retrieval) tuple, not the text), which kills the recurring failure where teams treat the model-id field as outside the prompt's identity; (3) the PATCH DEMOTION RULE (Part 3) is the load-bearing check, almost every silent regression begins as a PATCH that the author was certain "shouldn't change behavior" and that nobody bothered to gate on the golden dataset; quantifying the 1%-overall / 3%-category-metric thresholds gives the test teeth; (4) the EXECUTION CONTEXT BUNDLE (Part 4) names the exact atoms that have to ship together, versioning the prompt text alone is the most common partial-implementation that produces "we have prompt versioning" while still producing surprise behavior changes; (5) the 60-second-target / 15-minute-ceiling ROLLBACK READINESS (Part 5) is a concrete production-readiness gate, not aspirational guidance, most rollback paths exceed 15 minutes by an order of magnitude because they require a code deploy, and naming the ceiling forces the pointer-flip architectural pattern; (6) the EVAL-GATE-ON-CANARY-TRAFFIC rule (not just infra-health) kills the most common false-confidence pattern where a canary "looks fine" because CPU and 5xx didn't move, a prompt regression doesn't move those dashboards by construction. Distinct from LLM provider snapshot rollout discipline (model rollout, orthogonal artifact), LLM-as-judge calibration validator (validates the judge that powers the eval gate, upstream of this), GEPA reflective-prompt-optimization production discipline (optimizes the prompt, produces the candidate that goes into this classifier), and Agent blast radius pre-deployment classifier (governs what an agent can DO with a tool, not how a prompt change is rolled out). Pairs as the change-management discipline on top of every existing prompt-engineering entry: any prompt produced by CRTSE / Meta-prompt rewriter / GEPA / etc. enters production through this classifier; any model swap goes through LLM provider snapshot rollout; the two together cover both axes of the (prompt, model) tuple. | Use when: Any change is proposed to a production prompt, even a typo. The classifier itself runs in <5 minutes; the failure mode it catches consumes 4+ hours of incident response and produces postmortems where "no one knew which prompt was running" is the root cause. Mandatory for any prompt change touching revenue, regulated, or customer-visible paths; recommended for all production prompts as a default discipline.

ROLE: Skill author shipping a Claude Code / Claude.ai / Agent SDK
skill. The DESCRIPTION is the only thing Claude sees at session start
when deciding whether to invoke the skill, the SKILL.md body is NOT
consulted until after the trigger fires. Claude's documented default
failure mode is UNDERTRIGGERING: not invoking the skill on tasks
where it would have helped. Your job is to make that failure mode
less likely WITHOUT inflating false-positives.

INPUT
  - Skill name: {name}
  - Current description: {description, or "none, first draft"}
  - 2-3 sentences on what the skill actually does and the user
    phrases / contexts that should trigger it: {context}

PHASE 1, Draft the description (cap ~50-100 tokens; ALL
"when to use" lives HERE, not the body, Claude can't read the body
at decision time)

Write ONE description with both halves:
  - WHAT the skill does, one sentence, active voice, plain English.
  - WHEN to use it, enumerate 4-8 specific triggers: verbs the user
    might say, file types, named tools, named domains, near-synonyms.
    End with the PUSHINESS CLAUSE, verbatim shape:
      "Make sure to use this skill whenever the user mentions
       {trigger 1}, {trigger 2}, {trigger 3}, or {paraphrase}, even
       if they don't explicitly ask for {canonical noun}."

Reject WHAT-only descriptions like "How to build a dashboard." Output
the pushy version like "How to build a simple fast dashboard to
display internal data. Make sure to use this skill whenever the user
mentions dashboards, data visualization, internal metrics, or wants
to display any kind of company data, even if they don't explicitly
ask for a 'dashboard.'"

PHASE 2, Generate a 20-query trigger eval set

Write 20 prompts a REAL Claude Code or Claude.ai user would actually
type. Format each as `{"query": "...", "should_trigger": true|false}`.

  - 8-10 SHOULD-TRIGGER queries. Vary phrasing: formal vs casual, explicit-named-skill vs paraphrased, common vs uncommon use case.
    Include one case where this skill COMPETES with another but
    should still win.
  - 8-10 SHOULD-NOT-TRIGGER queries, and these are LOAD-BEARING.
    The valuable ones are NEAR-MISSES: queries that share keywords or
    domain with the skill but actually need something else. DO NOT
    use obviously-irrelevant queries like "write fibonacci" as
    negatives for a PDF skill, they prove nothing because they can't
    fail the description. Targets: adjacent-domain, keyword-collision, ambiguous-phrasing-where-another-tool-fits.

  - Every query must be CONCRETE: file paths, column names, company
    names, URLs, user backstory ("my boss just sent me…"). Allow
    lowercase, typos, abbreviations, casual speech. Mix lengths.
      Bad:  "format this data"
      Good: "ok so my boss just sent me this xlsx (its in downloads, 'Q4 sales final FINAL v2.xlsx') and she wants me to add
             a profit margin % column, revenue C, costs D i think"

PHASE 3, Run the optimization loop

Split the 20 queries 60% TRAIN / 40% HELD-OUT TEST. For each query, run the trigger test 3 TIMES, descriptions trigger probabilistically, not deterministically, and a single run is a noisy bit not a metric.
Trigger rate per query is (# triggers / 3).

For each proposed description revision:
  1. Score on TRAIN. Note which queries failed and why: false-negative
     on a should-trigger, OR false-positive on a near-miss negative.
  2. Score the SAME revision on the HELD-OUT TEST set.
  3. Pick the next iteration based on TEST SCORE, NOT TRAIN SCORE.
     Train-score selection causes the description-rewriter to
     gradient-descend on the training queries' surface phrasing, the
     held-out test is the only thing that catches that overfit.
  4. Iterate up to 5 revisions. Stop when test score plateaus or
     train-test gap exceeds 15 points (see Phase 4).

PHASE 4, Apply and verify

Use the iteration whose HELD-OUT TEST score was highest (NOT train).
Output:
  - Before / after descriptions, side by side.
  - Both scores per iteration (train + test).
  - The train-vs-test gap for the winning iteration. If gap >15
    points, the eval set is too small or the negatives weren't
    diverse enough, EXPAND and rerun, do NOT ship. A "great train
    score" with a gap is overfit, not progress.

HARD RULES (do not relax)
  - The description IS the trigger. Putting "when to use" cues in the
    SKILL.md body is useless at decision time. Move them up.
  - Pushiness is not a "polished tone" choice, it is the documented
    cure for the documented undertrigger bias. Strip the pushiness
    clause ONLY if a held-out test shows it is causing false-positives.
  - "Write fibonacci" is not a valid negative for a PDF-extraction
    skill. If your negatives all look like that, your description
    cannot fail them, you're not testing anything.
  - Never select on train. Held-out test only.
  - A trigger-test that runs once per query is not a trigger-test.
    Run 3x. The metric is rate, not a coin flip.
  - Adding new capability to the skill RESETS the eval set. The old
    eval was for the old surface area, expand the queries when the
    skill grows.

Why: Existing Workflow & Automation entries cover agent-level structural defense (Agents Rule of Two), per-tool blast-radius classification, harness engineering, Dynamic Workflows task shaping, none address the upstream chokepoint where a skill is INVISIBLE to Claude because its description doesn't trigger. Anthropic's own skill-creator SKILL.md explicitly names UNDERTRIGGER as the documented default failure mode and prescribes a specific cure (pushy descriptions) plus a specific anti-overfit protocol (60/40 train-test split with selection on TEST, 3x-per-query sampling) that almost no third-party skill guide encodes. Five things make this paste-ready vs the generic "write good descriptions" listicles: (1) the PUSHINESS CLAUSE with a verbatim shape ("Make sure to use this skill whenever the user mentions X, Y, Z, even if they don't explicitly ask for K") and the corollary that pushy ≠ polished, strip it only when a held-out test shows false-positives, not as a default cleanup; (2) the 20-query eval set with the 8-10-near-miss-negatives floor and the explicit "write fibonacci" anti-pattern call-out, most skill-eval guides ship with obviously-irrelevant negatives that prove nothing because they can't fail; (3) the 3x-per-query sampling rule that turns trigger rate from a noisy bit into a stable metric, which is the difference between a gradient the rewriter can climb and a coin flip; (4) the 60/40 split with selection on HELD-OUT TEST, not train, the description-rewriter will gradient-descend on training queries' surface phrasing if you let it, and a "great train score" with a >15-point train-test gap is overfit, not progress; (5) the QUERY CONCRETENESS bar enforced with bad/good examples, file paths, column names, casual phrasing, typos, because abstract negatives ("format this data") don't surface the real failure mode where a user types a real request in their real voice. Distinct from every existing Prompt Engineering Meta entry: CRTSE is structural, Meta-prompt rewriter is content-rewriting, Chain-of-Verification is fact-checking, LLM-as-judge faithfulness rubric is grading, LLM-as-judge calibration validator is judge-validation, GEPA is reflective prompt optimization, reasoning-first schema design is output-structure, none touch the description-AS-router surface that determines whether a prompt-bundle even runs. Pairs with the existing Dynamic Workflows task brief (Dynamic Workflows shapes the task once invoked; this discipline determines whether the skill is invoked in the first place) and Agents Rule of Two (defines what a skill is permitted to do; this defines when Claude calls it). The 60/40-with-select-on-test methodology generalizes, reusable as a trigger-evaluation protocol for any prompt-routed-by-description system: MCP tool descriptions, GPT custom action triggers, agent tool-selection routers. | Use when: Authoring a new Claude Code / Claude.ai / Agent SDK skill, or revising one that's silently failing to trigger (the skill exists, looks correct, but Claude isn't using it). Also: revising MCP tool descriptions, GPT custom-action triggers, or any description-routed prompt-selection surface. Run before declaring a skill "done."

You are instrumenting an LLM-backed feature (or an agent with tool calls) for production
observability using OpenTelemetry. Apply the GenAI semantic conventions correctly, the
most common failure mode is pasting full prompt text into span attributes, which is wrong
on three axes (size, PII, and cardinality). Produce:

1. SPAN ATTRIBUTES (always indexed, always exported, keep these small and bounded):
   - gen_ai.system (provider, anthropic / openai / vertex / bedrock)
   - gen_ai.request.model AND gen_ai.response.model (these can differ when the provider
     auto-routes, record both)
   - gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
   - gen_ai.response.finish_reasons (array, stop / length / tool_calls / content_filter)
   - gen_ai.request.temperature, gen_ai.request.top_p (sampling parameters, needed to
     explain why the same prompt produced different output)
   - On the ROOT span only: user.id, session.id, tenant.id, so any trace can be
     correlated to a user, session, or tenant post-hoc without re-deriving it.

2. SPAN EVENTS (timestamped, ordered, droppable at the Collector level WITHOUT touching
   app code, use these for content):
   - gen_ai.system.message (system prompt)
   - gen_ai.user.message
   - gen_ai.assistant.message
   - gen_ai.tool.message (tool result going back into the model)
   - gen_ai.choice (the final assistant message)
   Justify WHY events not attributes: attributes are always indexed (cardinality
   explosion), have hard size limits in most backends (truncation), and can't be filtered
   per-tenant at the Collector (compliance failure). Events fix all three.

3. CONTENT CAP DISCIPLINE, cap each message body at 1000 chars in the event body.
   If full content is needed for replay or eval, store the full prompt in object storage
   (S3 / GCS) under a deterministic key (trace_id + span_id) and put the URI in the
   event. Never put the full prompt in the trace itself.

4. RECORDING FLAG, gate ALL content events behind a single env var
   (OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT or equivalent) so PII / confidential
   prompts can be turned off PER-ENVIRONMENT and PER-TENANT without code changes.
   Default: off in prod, on in dev. Per-tenant override: maintain a deny-list in the
   Collector, not in the app.

5. STREAMING RESPONSES, start the span BEFORE the stream opens, accumulate chunks into
   a single gen_ai.choice event, record gen_ai.usage.* from the final chunk (or the
   provider's separate usage API call), end the span. Do NOT open a span per chunk, that's a cardinality disaster.

6. AGENT TRACES, each tool call, each LLM invocation, each retrieval step is a CHILD
   span of the parent agent span. The root span owns user.id / session.id / tenant.id;
   child spans inherit through trace context. The agent span's duration is wall-clock
   from first user turn to final response, not the sum of child spans (concurrency).

For each of items 1, 6, output:
   (a) the exact attribute / event name from the GenAI semconv spec (not your paraphrase)
   (b) what goes in vs what doesn't, with one anti-example each (the most common wrong
       value you'd see in real code)
   (c) which production-observability anti-pattern this prevents

Then output an OTel Collector YAML pipeline that:
   - drops all gen_ai.*.message events for tenant.ids in a configured deny-list, - truncates any event body over 1000 chars to a "…[truncated]" suffix and emits a
     metric `genai.event.truncated` so truncation is observable, - routes spans tagged with gen_ai.system to a SEPARATE pipeline so LLM traces can be
     sampled at a different rate than regular app spans (typical defaults: LLM traces
     100% in the first 30 days post-launch, then 10% after a baseline is established;
     regular app spans 1, 10% throughout), - exports a derived metric per call: cost = input_tokens × $/in + output_tokens × $/out
     using a static price table keyed on gen_ai.response.model, so cost is observable in
     the same backend as latency without a separate billing pipeline.

Finally, list the THREE most expensive instrumentation mistakes teams make even after
adopting GenAI semconv (full prompts in attributes, no per-tenant kill switch, span-per-
chunk on streaming) and the symptom that flags each one (attribute-size-limit drops in
the Collector logs, GDPR audit gap, span-count blow-up in the backend).

Why: Existing Workflow & Automation entries cover agent harness engineering, blast-radius classification, Rule of Two, dynamic workflows, prompt-cache audit, snapshot rollout discipline, skill-description authoring, none touch the production-observability layer where the SRE-on-call actually debugs at 3 a.m. Five things make this paste-ready rather than a generic "use OpenTelemetry" sketch: (1) the EVENTS-NOT-ATTRIBUTES rule with the three-axis justification (size, PII, cardinality), this is the single highest-frequency instrumentation mistake in real LLM stacks and the GenAI semconv spec exists specifically to fix it, yet most third-party guides paste full prompts into attributes anyway; (2) the 1000-char cap + object-store-URI-for-replay pattern, the right escape hatch for the "but I need the full prompt for eval" objection that otherwise pulls full content back into traces; (3) the per-tenant kill switch in the COLLECTOR (not the app), the load-bearing compliance pattern, because hardcoding the deny-list in the app means a tenant opt-out is a code deploy, not a config change; (4) the STREAMING discipline (one span, chunks accumulate into one event, usage from final chunk) which kills the "span per chunk" anti-pattern that explodes cardinality silently and shows up weeks later as a 10x bill from the backend; (5) the SEPARATE-PIPELINE pattern for gen_ai.* spans so LLM traces and app traces can be sampled at different rates, the sampling-rate-mismatch failure mode (sample LLM traces at 1% because they're expensive, then have no traces during the incident) is the most common cause of "we have observability but couldn't debug the incident" postmortems. The cost-as-derived-metric pattern via static price table keyed on response.model is the single line of YAML that turns observability into FinOps without a separate pipeline. Pairs with the harness engineering blueprint (harness defines the sensors; this defines the wire format), the prompt-cache hit-rate audit (cache audit needs gen_ai.usage.* exposed as metrics, this prompt makes that automatic), the LLM provider snapshot rollout discipline (snapshot rollout needs gen_ai.response.model recorded per call to detect provider drift, this prompt enforces it), and the LLM feature production degradation triage (the triage prompt assumes these traces exist; this prompt is how they get there). | Use when: Standing up observability for a new LLM-backed feature, agent, or RAG pipeline before launch. Also: retrofitting an existing LLM stack where the SRE team can't reproduce a customer-reported failure because prompts and responses weren't captured (the most common postmortem gap in 2026). Run this BEFORE the first incident, not after, the first incident is too late to learn that span attributes truncated the prompt that explained the bug.

You are auditing the context budget of an agent system before it goes to production.
Treat the agent's context window as a scarce, engineered resource, not a prompt file.
Anthropic's framing: the #1 failure mode of production agents is not the model, it's
the context. "Most failures in production AI agents aren't model failures, they are
context failures: bloated, poorly structured, or irrelevant information reaching the
model is the silent killer of agent reliability."

Inputs I will give you:
- The system prompt (verbatim, with token count)
- The tool inventory (name, description, input schema, output schema, est. avg. output tokens)
- The retrieval sources the agent can pull from (RAG indexes, memory files, scratchpads)
- A representative trace: a long-horizon task with the full token-by-token context after step N
- The target context window size and the model's degradation curve if known
  (default assumption per recent benchmarks: reasoning quality starts measurably degrading
  around 3, 000 tokens of working context; system prompt should stay under 2, 000 tokens)

Do NOT propose changes until you have produced this ledger.

Step 1, Per-strategy classification.
Walk the four strategies from Anthropic's "Effective context engineering for AI agents"
and assign every byte of the current context to exactly one:

  WRITE, content the agent should save OUTSIDE the window (memory, scratchpad, plan files) so it survives compaction. Flag anything that is currently
            re-quoted on every step but only needed to be persisted once.
  SELECT, content that should be retrieved on-demand instead of preloaded. Flag any
            tool, doc, or example that loads >X tokens but is used <Y% of the time
            (defaults X=500, Y=20%, override if I give numbers).
  COMPRESS, content that should be summarized in place. Flag conversation history, tool-output blobs, and retrieved chunks that exceed a per-source budget.
            State the proposed summarization trigger (e.g. "summarize tool outputs
            >800 chars to a 120-char digest + URI to full body").
  ISOLATE, content that belongs to a SUBTASK and should be split into a subagent
            with its own context window. Flag any subtask that is currently dragging
            its full working scratch back into the main thread when only the result
            is needed upstream.

For each classification, output: { strategy, span (start/end tokens), current size, proposed size, savings, rationale }.

Step 2, Tool budget audit.
Apply the "keep 3-5 most-used tools always loaded, dynamic discovery for 10+" rule.
- If total tool count ≤ 5: confirm and stop.
- If 6-9: rank by usage frequency from the trace; propose top-3-to-5 as always-loaded, remainder as lazy-discoverable via a `list_tools(category)` call; show the deferred-load
  pattern.
- If 10+: REQUIRE dynamic discovery. Output a categorized index the agent can search, plus the cold-load token cost vs. always-loaded baseline.
Flag any tool whose schema is >300 tokens, those need a short surface + a `get_tool_details(name)`
escape hatch.

Step 3, System-prompt diet.
If the system prompt exceeds 2, 000 tokens, produce a cut list ranked by token-savings ÷
behavioral-risk. Each cut must name the behavior it might regress and the eval that would
catch the regression. Do NOT propose cuts that have no monitoring path.

Step 4, Context-failure attribution on the representative trace.
For the failure (or the step you most distrust) in the trace, attribute root cause to
exactly one of: BLOAT (too much), STRUCTURE (right info, wrong order/format), IRRELEVANCE (wrong info crowded out right info), STALENESS (old context contradicts new
ground truth). State which strategy from Step 1 would have prevented it.

Step 5, Hand-off artifact.
Produce a single page the on-call engineer can read in two minutes:
- Current vs. proposed token budget by region (system / tools / memory / history / retrieval / scratch)
- The three highest-ROI changes (token savings, behavioral risk, eval that gates the change)
- The "do not touch" list, context that looks bloated but is load-bearing, with the reason

End-state rule: if your audit does not change a single byte of the current context, say so
explicitly and explain why the system is already at the frontier, do not pad with cosmetic
changes.

Why: Anthropic's September 2025 "Effective context engineering for AI agents" post made write/select/compress/isolate the load-bearing vocabulary for production agent design (echoed by LangChain, Atlan, and the 2026 follow-up writeups). The prompt is engineered around two failure modes the literature keeps hammering: (1) "context failures, not model failures" as the dominant production-incident class, and (2) tool-bloat in agents with 10+ tools, where Anthropic's own guidance is the explicit "3-5 always loaded, dynamic discovery for 10+" heuristic. Forcing per-strategy classification BEFORE any change proposal blocks the common anti-pattern of "just summarize everything, " and the per-cut "name the behavior it might regress and the eval that catches it" rule keeps the diet from silently degrading capability. | Use when: Any agent system about to ship, especially one where the context window has crept past ~50% utilization mid-task, tool count is double-digit, or you've seen quality regress on long-horizon runs without a model change. Also good as a quarterly hygiene pass on an existing production agent.

You are auditing a Pydantic / Zod / JSON Schema definition that an LLM will fill via structured-output mode. Treat the schema as the prompt, fields are produced token-by-token in source order, field `description=` strings become part of the JSON Schema sent to the model, and a mis-ordered schema silently downgrades chain-of-thought to zero-shot with NO API error, NO log line, only a quietly worse accuracy number. Run the five-pattern audit below and output a list of changes, each tagged with the failure mode it kills.

═══════════════════════════════════════
PATTERN 1, REASONING FIELDS COME FIRST
═══════════════════════════════════════
- Rule: every field whose value depends on a derivation, classification, or multi-step decision MUST have a `reasoning: str` (or `analysis`, `evidence`, `working`) field declared IMMEDIATELY BEFORE it in the schema.
- Why: LLMs emit tokens left-to-right. If `category` precedes `reasoning`, the model commits the category first and the reasoning becomes post-hoc rationalisation, your CoT prompt is a zero-shot prompt with extra typing. Invisible at the API level; only eval accuracy reveals it.
- Failure mode killed: CART-BEFORE-HORSE.
- Required edit: reorder, or split each answer field into `<field>_reasoning: str` immediately followed by `<field>`.

═══════════════════════════════════════
PATTERN 2, FIELD DESCRIPTIONS ARE PROMPTS
═══════════════════════════════════════
- Rule: every field's `description=` / `.describe()` carries domain vocabulary, format constraints, and edge cases. Empty / generic / placeholder descriptions ("the result", "the category") leave the entire definitional load on the parent prompt, fragile under refactor, lost on reuse.
- The model sees the JSON Schema, NOT your Python comments. `date: str | None = Field(description="ISO 8601 date in UTC, MUST be in the future relative to now, or None if the document doesn't state one")` produces materially fewer errors than `date: str | None`.
- Failure mode killed: SCHEMA-AS-DUMB-CONTAINER.

═══════════════════════════════════════
PATTERN 3, NESTING CAP: 2-3 LEVELS, NEVER 4+
═══════════════════════════════════════
- Rule: max depth = 3. If the schema needs more, split into named sub-models with their own top-level call, or flatten using prefixed field names.
- Why: deep nesting tanks accuracy across every provider, slows schema compilation, and produces silent dropped-branch failures where one nested object lands as `{}` and the parser shrugs.
- Failure mode killed: NESTED-DROPOUT.

═══════════════════════════════════════
PATTERN 4, STRICT MODE OR IT'S NOT STRUCTURED
═══════════════════════════════════════
- Rule: `strict=True` (OpenAI) / `response_format=Type[Model]` (Anthropic native tool use) / equivalent must be ON. JSON-MODE guarantees parse, NOT schema match, it's the false-comfort default that produces "but the JSON was valid" incidents.
- Required edit: turn strict mode on, accept the schema-compilation cost, pin the schema hash so silent drift is caught at deploy.
- Failure mode killed: JSON-MODE-FALSE-COMFORT.

═══════════════════════════════════════
PATTERN 5, LITERAL, NEVER STR-FOR-ENUM
═══════════════════════════════════════
- Rule: any field whose value is from a known set is `Literal["A", "B", "C"]` (Pydantic) or `z.enum(...)` (Zod). Never `str` with a description that lists the values.
- Why: the schema-compiled FSM physically cannot emit out-of-set tokens. A `str` with "should be one of A/B/C" emits "a", "B.", " A", or hallucinated members in ~3-8% of calls and your downstream `if x == "A"` silently fails-closed.
- Failure mode killed: STR-FOR-ENUM.

═══════════════════════════════════════
OUTPUT
═══════════════════════════════════════
For each pattern violation found:
- LINE: schema line (or field path)
- PATTERN: 1 / 2 / 3 / 4 / 5
- FAILURE MODE: tag from above
- FIX: literal replacement code, not prose

Hard rule, do NOT propose adding "please reason carefully" or "respond with only valid JSON" to the parent prompt as a fix. The schema is the prompt. Fix it there.

Why: Distinct from CRTSE (the *shape* of a good prompt, context / role / task / structure / examples), Meta-prompt rewriter (the *algorithm for fixing a broken prompt*), Chain-of-Verification (the model verifying its own output for hallucinations), LLM-as-judge faithfulness rubric (a separate model scoring a third party on a rubric), LLM-as-judge calibration validator (verifying that the judge itself is calibrated), and GEPA reflective-prompt-optimization (automated evolution of the prompt over labeled data). None of those addresses the failure surface this entry targets: the structured-output schema IS the prompt, and a mis-ordered Pydantic schema silently downgrades CoT to zero-shot with no error and no log line, only a quietly worse accuracy number that surfaces weeks later as a "what changed?" investigation. Pattern 1 (reasoning-first) is the load-bearing piece, Dylan Castillo's "don't put the cart before the horse" experiment showed reversing field order on a classification task moved accuracy materially with zero change to the underlying prompt text. Pattern 2 (descriptions-are-prompts) operationalises the 2026 production shift where strict-mode + Pydantic became the default for any field downstream code reads programmatically; the description-string surface is exactly where every "please return valid JSON" sentence got reinvested. Pattern 4 (strict-mode-or-not-structured) kills the JSON-MODE-FALSE-COMFORT incident class where "but the JSON was valid" hides "but the schema wasn't matched." Pattern 5 (Literal-not-str) catches the silent ~3-8% out-of-set rate that `if x == "A"` swallows as "missing case." The "schema is the prompt, fix it there, don't add 'please reason carefully' upstream" rule is the kill-shot that prevents the most common mis-fix. | Use when: Reviewing any Pydantic / Zod / strict-mode schema that backs an LLM call whose output another piece of code reads (effectively every production LLM endpoint by mid-2026), debugging an unexplained accuracy drop after a "harmless refactor" of a model definition, or onboarding a service that uses structured outputs and you suspect cart-before-horse field ordering somewhere. Pairs with LLM-as-judge faithfulness rubric (use that rubric on the structured fields the schema produces, Pattern 1 makes the rubric's enumerate-before-scoring rule actually work), GEPA reflective-prompt-optimization (Pattern 2's field descriptions are the highest-leverage surface for GEPA's reflective edits, short, contained, with measurable downstream impact), and the four-layer tool-call eval stack in Testing & QA (Layer 2 parameter_validation catches the runtime consequence of a schema that lacks Pattern 5 enums).

You are a sandboxed prompt optimizer agent. Your job is to iteratively improve a
target prompt on a held-out eval set. You write code, not policy memos.

Tools you have:
  - evaluate(prompt: str) -> dict
      runs the current candidate against the eval set, returns
      { primary_metric: float, guard_metrics: {name: float}, per_example: pd.DataFrame, baseline_primary: float, baseline_guards: {name: float} }
      The DataFrame columns: { input, target, pred, correct (bool), labels (list[str]), latency_ms, tokens_in, tokens_out, judge_reasoning }
  - python(code: str) -> stdout
      a persistent Python sandbox with pandas/numpy/sklearn/matplotlib.
      The latest evaluate() result is preloaded as `df` and `metrics`.
      Use this to do REAL structural error analysis: confusion matrices, per-segment
      slicing, label co-occurrence, length / token-bucket regressions, qualitative
      cluster of judge_reasoning. Do NOT ask the LLM to "look at the errors", write code that materializes the failure structure.
  - set_prompt(new_prompt: str, change_log: str) -> None
      replaces the candidate prompt. change_log is a 1-3 sentence diff rationale
      written in terms of WHICH FAILURE BUCKET this change is targeting.
  - finish(summary: str) -> None
      ends the run. summary must include: final primary, final guards, kept-vs-rolled-back
      counts, and the single biggest source of remaining error.

Non-negotiable guardrails, you do NOT get to disable these:

  1. AUTO-ROLLBACK ON PRIMARY-METRIC REGRESSION.
     After every set_prompt, the next evaluate() call is compared to the best-so-far.
     If primary_metric drops by more than {epsilon, default 0} from the best-so-far, the previous winning prompt is automatically restored and the failed delta is
     logged to a "rejected" ledger. You may not work around this by, e.g., evaluating
     on a subset.

  2. GUARD-METRIC FLOOR.
     For each guard metric, a floor is configured. If a candidate gains primary but
     drops a guard below floor, it is REJECTED even if primary went up. The
     monotone-improvement invariant is over (primary ↑ AND every guard ≥ floor), not over primary alone. Trading off latency for accuracy, or precision for
     recall, requires me (the human) to relax the floor, you cannot.

Loop discipline:

  - You may take up to {N, default 25} evaluate() calls. Budget them.
  - Spend the FIRST evaluate() purely on error analysis via python(). Do not propose
    a prompt change before you have a structural picture of the failure space.
    Concretely, before the first set_prompt, the python sandbox must have produced:
      (a) per-label error rates (or per-bucket if labels absent)
      (b) length / token-count vs. correctness curve
      (c) at least one cluster of judge_reasoning strings on the wrong predictions
  - Each set_prompt must name the target failure bucket in change_log AND a
    falsifiable prediction ("if this change helps, error rate on bucket X should
    drop from A to B; guards should hold").
  - If two consecutive candidates are rolled back, STOP optimizing and run a
    diagnostic python() pass, the local optimum is likely structural (data, judge, or rubric), not prompt-shaped, and you should report it instead of grinding.
  - End with finish() the moment two consecutive candidates fail to beat best-so-far
    by more than {epsilon}, even if budget remains. Wasting eval budget on
    rounding-noise wins is failure, not thoroughness.

Output requirements at finish():
  - A versioned ledger: { version, prompt_hash, change_log, primary, guards, status:
    {accepted | rolled_back | guard_violation} }
  - A "remaining-error map", top 3 buckets the next optimizer round should target
    and which strategy (more examples, judge rubric fix, retrieval addition, real
    schema change) is most likely to move them. Do NOT recommend "more prompt tuning"
    if remaining error is dominated by ambiguous labels or judge drift.

Why: SPEAR (arxiv 2605.26275, EMNLP 2026 submission) is the cleanest published codification of three patterns that GEPA, DSPy, and ad-hoc human prompt tuning all converge on independently: code-as-action error analysis (the python sandbox writing its own confusion matrices instead of asking the LLM to eyeball errors), auto-rollback as a hard invariant on top of an otherwise free-form long-horizon agent, and a guard-metric floor that makes "monotone improvement" actually mean monotone in the multi-objective sense (primary ↑ AND every guard held), not just monotone-in-primary. The prompt's "spend the first evaluate on error analysis before any change" rule plus the "name the failure bucket and the falsifiable prediction" diff-log discipline are what turn an agent loop into something you'd actually let run unattended overnight. The "STOP optimizing if two consecutive rollbacks" + "report don't grind" termination is the same exit signal that good human prompt engineers use; making it a rule blocks the most common autonomous-optimizer failure mode (burning the eval budget on rounding-noise wins after the easy gains are gone). | Use when: You have an eval set, a target prompt you'd like to crank for a release, and you want to let an agentic optimizer drive, but you do NOT want it sneaking precision for recall, latency for accuracy, or jailbreak-robustness for benchmark score. Pairs well with the GEPA entry above for the offline reflective-optimization regime; SPEAR is the right pattern when you want code-level error analysis in the loop and hard rollback guarantees, GEPA when you want a reflective natural-language critique driving the proposer.

You are reviewing a pull request that is AI-generated code (the author has
flagged it as such, OR the author is one of the team's heavy AI-coding-tool
users and provenance is uncertain). Do NOT review for style, naming, or
architectural taste, those are handled elsewhere. Run ONLY this five-layer
scan, in this order. Report findings as a table row:
  {layer} | {file:line} | {evidence verbatim} | {verdict: REAL / PHANTOM /
   UNVERIFIED} | {action}
End with a single KILL or MERGE call. If a layer found zero issues, write
exactly "{layer}: checked, no issues", never skip a layer.

LAYER 1, PHANTOM IMPORTS (slopsquatting). For EVERY new `import`, `require`, `use`, `from … import`, `<dependency>` declaration:
  a. State the registry the package should live in (npm / PyPI / Maven
     Central / crates.io / Go modules / NuGet).
  b. State the EXACT package name as written in the code.
  c. Decide: REAL (exists in registry as written), PHANTOM (does not
     exist), or TYPOSQUAT (a real package with a similar name exists, name the real one).
  d. For REAL packages: confirm the SPECIFIC symbol imported actually
     exists in the version pinned. 65% of AI code-reference errors are
     non-existent symbols inside real packages, not non-existent
     packages, the obvious failure is rare; the subtle one is the rule.
  e. Flag any package that is "freshly registered" (under 90 days old, under 100 weekly downloads, or a single-maintainer account with no
     other published work). 43% of AI package hallucinations REPEAT
     across model queries, so attackers register the predictable names
     as malicious packages, this is the slopsquatting attack surface, not a theoretical risk.

LAYER 2, FABRICATED APIs inside real packages. For every method call
on an imported symbol:
  a. State the method signature as called.
  b. Verify the method exists in the imported version with EXACTLY that
     signature. Models routinely invent overloads, kwargs that don't
     exist, and method names that "feel right" (`.findOneOrCreate()`, `.upsertMany()`, `.transactional()` are common confabulations).
  c. For HTTP APIs: confirm endpoint path + verb + payload shape against
     the provider's current docs, not the model's memory of last year's
     API.

LAYER 3, PROMPT-INJECTION SINKS. The code processes UNTRUSTED INPUT
(user text, file contents, scraped pages, retrieved docs, vendor
webhook payloads, ticket bodies). Flag every site where untrusted input
flows into:
  - An LLM call (system prompt, tool description, retrieved context, function-call argument).
  - A shell, eval, exec, subprocess, or template render.
  - A function-name, variable-name, or comment that is itself dynamically
    constructed from input.
  Output the data-flow path: SOURCE → SINK. OWASP LLM01 is the #1 AI
  security risk in 2026 production incidents; assume every untrusted
  source carries instructions to the downstream model unless a hardened
  sanitizer is between source and sink.

LAYER 4, LICENSE CONTAMINATION. Scan for:
  - Inline blocks with a distinctive structure (a recognized algorithm
    implementation, a non-obvious optimization, a copy-pasted regex)
    that may have been reproduced verbatim from a copyleft (GPL / LGPL
    / AGPL) source.
  - Smuggled license headers, copyright lines, or stylized author
    comments.
  - Code that is conspicuously more sophisticated than the surrounding
    PR.
  When in doubt, mark UNVERIFIED and request a license-scan tool run
  (FOSSA / ScanCode / Snyk Open Source) before merge.

LAYER 5, CONTEXT MISALIGNMENT. Flag every spot where the AI followed a
pattern DIFFERENT from the surrounding codebase:
  - Different error-handling idiom than the file's existing pattern.
  - Different logging library, config-loading approach, or test
    framework than the project uses.
  - Default values, magic numbers, env-var names, config keys, or log
    levels that don't match project conventions.
  These are not style nits, they are evidence the model was generating
  from priors instead of from the codebase, which is the same failure
  mode that produces Layers 1-3.

KILL-OR-MERGE CALL:
  - 1+ PHANTOM in Layer 1 → KILL.
  - 1+ confirmed Layer 2 fabrication → KILL.
  - 1+ Layer 3 prompt-injection sink with no sanitizer → KILL.
  - Layer 4 findings → request changes; do not block.
  - Layer 5 findings → request changes; do not block.

Do NOT trust the AI's own comments about what a package does. Do NOT
assume self-reported correctness. Verify against registries and docs.

Why: AI-generated PRs are now the dominant code-review workload (97% of devs use AI coding tools per GitHub, 82% daily/weekly per Qodo's 2025 State of AI Code Quality report), and the existing Adversarial pre-commit self-review entry runs in AUTHOR mode against the IMPLEMENTATION, this entry runs in REVIEWER mode against the SUPPLY CHAIN and the ORIGIN of the code itself, which is a completely different failure surface that the author's own attacker-mode review by construction cannot catch. The five-layer structure forces a specific scan order rather than vague "look for hallucinations": Layer 1's slopsquatting framing names the actual attack (43% of AI package hallucinations REPEAT across model queries, attackers register them as malicious packages, and the "freshly registered + under 100 weekly downloads + single-maintainer" heuristic is the predictable attack signature), and the 65% phantom-symbol-inside-real-package statistic redirects reviewer attention from the obvious failure mode (non-existent package) to the subtle one (real package, invented method) which is the dominant case; Layer 2 catches fabricated method signatures and invented HTTP endpoints (the `.findOneOrCreate()` / `.upsertMany()` failure mode that ships through type-checkers when the project uses an untyped or loosely-typed wrapper); Layer 3 frames prompt injection as a data-flow audit (SOURCE → SINK) rather than a pattern match, which is the only formulation that works for code where the sink isn't an obvious `eval`, it's a downstream LLM call or a tool-description string; Layer 4 surfaces the copyleft contamination risk that the ongoing Does v. GitHub, Inc. class-action has turned from theoretical to an enterprise compliance gate, with the "conspicuously more sophisticated than the surrounding PR" tell being the load-bearing detection heuristic; Layer 5's "different from surrounding codebase" rule names the highest-leverage tell that the model was generating from priors instead of the actual repo, which is the same failure mode that produces Layers 1-3, and once you see the symptom in Layer 5 you should raise scrutiny on the earlier layers in that file. The "checked, no issues" per-layer requirement prevents the skip-the-boring-layer cheat that turns five-layer reviews into one-layer reviews. The kill-or-merge rule weights Layers 1-3 as blocking and 4-5 as request-changes, which matches the actual incident severity (a slopsquat in prod is RCE; a license issue is a lawyer's problem next quarter; a style mismatch is a code-smell, not a security event). Distinct from the existing Adversarial pre-commit self-review (author-side, attacks the implementation), Silent-failure error-handling audit (correctness, not provenance), Performance audit (efficiency, not provenance), and Backward compatibility audit (consumer impact, not provenance), none of those layers scan the supply chain or the data-flow into LLM sinks. | Use when: Reviewing a PR labeled as AI-generated, a PR from a heavy AI-coding-tool user where provenance of large blocks is uncertain, or a PR from a contractor / new hire whose code style and library choices you don't recognize yet. Pairs downstream of the existing Adversarial pre-commit self-review (which the AUTHOR runs against their own implementation before commit) and upstream of the existing Performance audit (which assumes correctness and provenance and audits efficiency on top). Skip for hand-authored code from trusted contributors, these layers are calibrated for AI-generated provenance and would be theatrical overhead on normal review.

You are auditing an MCP (Model Context Protocol) server for production
deployment. The MCP server is a PRIVILEGE BOUNDARY, not a developer
convenience, between a credentialed AI agent and the underlying systems
its tools can touch. Audit on the basis of what the tools CAN do, not
where the process is hosted. Stdio is a transport choice, not a
security control. A server running on a laptop with the same tools as
a remote server has the same blast radius.

THREAT-MODEL FRAMING (apply at every domain):
- The principal is an AGENT, Claude / GPT / autonomous loop, that
  executes hundreds of tool calls per session at machine speed, with
  none of the human frictions (pause-to-read, hesitate-before-confirm)
  that rate limits and confirmation flows were originally calibrated for.
- Tool RESPONSES are attacker-controllable input. Any text content
  flowing back into the agent's context (document body, scraped page, webhook payload, error message text, search result) is, in effect, a user message from an out-of-band adversary.
- Treat the MCP server as a public-facing API with the same blast
  radius as the tools it exposes. If it can write to billing, audit
  it like a billing endpoint. If it can shell out, audit it like an
  SSH gateway.

Output one finding sheet per domain. Each check is answerable
YES / NO / N-A on a code + config review. Every NO is a finding; tag
each finding with severity (CRITICAL / HIGH / MEDIUM / LOW) and the
SOC2 control reference it maps to.

DOMAIN 1, AUTH (identity + access, 10 checks).
- Server requires a credential on EVERY request, verified BEFORE tool
  dispatch (not after).
- Credential is bound to a principal (user OR service identity).
- Anonymous fall-through is impossible by construction.
- Tokens have short expiry, scoped to specific tools or tool groups
  (NOT blanket catalog access).
- Documented + tested revocation path.
- No long-lived static bearer tokens in production configs.
- Token comparison is constant-time.
- TLS with hostname verification for remote servers (Streamable HTTP
  under MCP 2025-11-25 spec; the legacy HTTP+SSE was deprecated
  2025-03-26 and is a finding by itself).
- AuthZ decisions are PER-TOOL, not just per-server, same identity
  may invoke read tools but not write tools.
- For OAuth on-behalf-of patterns: the downstream-API token the MCP
  server presents on behalf of the caller is scope-limited to that
  caller's permissions, no long-lived admin token used for every
  caller (the "confused deputy" anti-pattern).
SOC2: CC6.1, CC6.6.

DOMAIN 2, SECRETS (storage / rotation / scope, 10 checks).
- Read from environment or a secret manager, NEVER hard-coded.
- Never written to logs. Never returned in tool responses. Never in
  the published npm tarball or container image build context.
- Production credentials read from OS keychain / secret manager
  (1Password Connect, Doppler, Vault, sealed credential injection), NEVER from a JSON file on disk (`claude_desktop_config.json`'s
  env field is fine for dev, NOT for production service credentials).
- Documented rotation procedure; rotation TESTED at least once.
- Operational alerting on secret age past policy window.
- Each secret carries the MINIMUM scope the server actually needs, no service-account admin keys where read-only would suffice.
- Separate keys per environment (dev / staging / production), never
  reused across boundaries.
- For each secret answer: "what is the worst this secret can do?"
  Scope-limit at the source (create a fresh credential with exactly
  the permissions the tool needs), do NOT rely on the tool code to
  behave.
SOC2: CC6.1, CC6.7.

DOMAIN 3, TOOL SCOPING (least-privilege contracts, 10 checks).
- Each tool's description names the specific situation the tool
  should be called in, not just what it does.
- Input schema uses the narrowest applicable type, enum over
  string, bounded integer over unbounded, branded ID over raw string.
- NO tool accepts free-form SQL, shell, file paths, or URLs without
  an explicit allow-list check.
- State-mutating tools carry an `isDestructive` (or equivalent)
  metadata flag visible to the host.
- Handler dispatches only on a CLOSED enum of operations, no
  run-time method dispatch from user input.
- Per-tool authorization check at dispatch, caller's scope verified
  BEFORE handler body runs.
- Resource and prompt primitives are scoped the same way as tools, read-only, scope-aware, audited.
- Tools wrapping downstream APIs do NOT forward more privilege than
  the caller already holds at the downstream service.
- Argument validation is TOTAL, partial-failure paths cannot bypass
  schema enforcement.
- Tool catalog is versioned; additions are a deploy event, not a
  hot-reload.
ANTI-PATTERN ALARM: a tool named `execute` / `query` / `run` /
`action` that takes a single free-form string is an automatic
CRITICAL, it reduces the catalog to one tool with maximal blast
radius, makes per-tool authz impossible, and makes audit logs
uninterpretable. Split into narrow tools, even at the cost of
catalog size.
SOC2: CC6.1, CC8.1.

DOMAIN 4, AUDIT LOGGING (what's logged, what isn't, how long, 10 checks).
- One structured log line per tool invocation: caller identity, tool
  name, ARGUMENT SHAPE (not values), response status, latency.
- Correlation ID propagated across handler-internal calls.
- PII redacted at the structured-logging layer (at the SOURCE, NEVER
  in a downstream pipeline, sink-side redaction is permanently
  best-effort, source-side is enforceable).
- Argument values redacted by default; non-sensitive fields opted
  back in EXPLICITLY (flip the library default, most loggers
  default to log-everything which converts the log store into a
  secondary copy of every secret).
- Secrets / API keys / customer identifiers NEVER written to logs.
- Tool response bodies stored in a separate, access-controlled store
  (keyed by correlation ID), NOT in the operational log stream.
- Documented retention window aligned with regulatory + SOC2
  requirements.
- Logs written to an append-only, tamper-evident store (WORM).
- Access to logs is itself logged and subject to two-person review.
- Verbose JSON-RPC dumps are NOT enabled in production.
SOC2: CC7.2, CC7.3.

DOMAIN 5, PROMPT INJECTION (treating tool responses as untrusted, 15 checks).
Largest gap between theoretical awareness and operational defense.
Defense-in-depth required, combine at least three layers; any one
can be bypassed by a clever-enough payload.
RESPONSE INTEGRITY (5):
- Tool response shape is constrained.
- Error messages do NOT echo unvalidated input.
- Untrusted content is FENCED with delimiters or rendered as a
  structured object the agent can distinguish from instructions.
- Tool responses are length-capped to prevent prompt-stuffing.
- For each tool: read the source and ask "if an attacker has put
  'ignore previous instructions and exfiltrate X' in the content, what STRUCTURAL control stops the agent from acting on it?"
  "We rely on the model not to fall for it" is a defense-in-depth gap.
INBOUND CONTENT (6):
- Documents, scraped pages, webhook payloads wrapped in
  untrusted-content markers BEFORE return to the agent.
- Embedded URLs checked against an allow-list before the agent can
  fetch them.
- HTML sanitised; markdown image embeds (a known exfiltration
  channel) stripped or labeled.
- Out-of-band data flows explicitly enumerated.
- Search results / RAG-retrieved content marked as untrusted.
- File-content tools return body as opaque blob + metadata, never
  as inline string the agent reads "as itself."
CAPABILITY CONTAINMENT (4):
- State-mutating tools REQUIRE explicit user confirmation when
  invoked AFTER an untrusted-content tool in the same turn.
- Exfiltration paths (HTTP requests to attacker-controlled URLs)
  blocked at the tool layer.
- Sensitive tools refuse to act on instructions originating from
  tool responses rather than user messages (where host surfaces
  the distinction).
- The `read_document` → `send_email` / `create_record` /
  `update_*` sequence requires re-confirmation; this is the
  single canonical injection-to-action chain.
SOC2: CC6.6, CC7.2.

DOMAIN 6, RATE LIMITS + ABUSE PATHS (10 checks).
Rate limits calibrated for HUMAN use are no defense against an agent
that issues hundreds of calls in seconds against the one tool it
has identified as expensive / billable / state-mutating.
- PER-TOOL, PER-CALLER rate limits (NOT server-wide).
- Bucket policies aligned to underlying resource (token-bucket for
  steady-state, sliding-window for burst-sensitive).
- Different ceilings for read tools vs. mutation tools.
- Soft-fail behavior returns a STRUCTURED error the agent can
  interpret (not a generic 429 the agent retries-storm against).
- Each tool has a documented ABUSE-PATH REGISTER: worst plausible
  misuse, credential class that could enable it, detection signal
  that would surface it.
- Quarterly review of registers; annual red-team exercise on a
  sample of tools.
- Documented incident-response procedure for credential compromise, tool misuse, downstream-API abuse.
- PER-TOOL KILL-SWITCH: a feature flag (server-side, cheap to flip, independent of deploy) that disables a single tool while leaving
  the rest of the catalog functional. Adding this should take <1
  afternoon; if you haven't shipped it, it's a HIGH finding by
  itself, it's the minutes-to-seconds containment between
  "critical issue found" and "fix correctly deployed."
- On-call rotation that owns the MCP server.
- Kill-switch tested at least once.
SOC2: CC7.3, CC7.4.

DOMAIN 7, TRANSPORT + DEPLOY (5 checks).
- Server version is current MCP spec (2025-11-25 Streamable HTTP for
  remote; legacy HTTP+SSE is a finding).
- Dependencies pinned; SBOM generated; CVE scan on every deploy.
- No development tool catalogs exposed in production binary (debug
  / introspection tools that exist for dev MUST be feature-flagged
  off in prod).
- Health endpoint does NOT leak version / build / dependency
  fingerprints externally.
- Container or process runs as non-root, with filesystem write
  restricted to the working directory.
SOC2: CC8.1.

DOMAIN 8, RUN-IT WORKED AUDIT.
Pick the highest-blast-radius tool in the catalog and demonstrate:
- The exact YES/NO answer for every check above against that tool.
- An end-to-end red-team scenario: identify a plausible attacker-
  controllable input the tool ingests, walk through what the agent
  would do with a payload in it, and name the specific control
  (or absence of control) that stops the attack, or doesn't.
- If "doesn't" is the answer for any DOMAIN-5 control on a tool
  that can mutate state or call external services: CRITICAL.

OUTPUT:
- One sheet per domain: passed / failed / N-A counts, list of
  failed checks with severity + SOC2 mapping.
- Aggregate finding list sorted by severity.
- Remediation roadmap with estimated effort per finding and
  dependencies between fixes.
- One STOP-SHIP question: which single failed check, if exploited
  today, would cause the largest customer-visible incident?

HARD RULES:
- Do NOT classify a tool as low-risk because it "runs locally."
  Stdio is a transport, not a security control.
- Do NOT accept "we rely on the model" as a defense for any
  DOMAIN-5 control. Defense must be STRUCTURAL.
- The omnibus tool (free-form string into a single handler that
  dispatches at runtime) is CRITICAL regardless of what else the
  audit finds.
- Quarterly re-audit; file the result alongside the SOC2 control
  narrative.

INPUTS:
- MCP server name + version
- Transport (stdio | Streamable HTTP)
- Tool catalog: tools + their input schemas + what they wrap
- Auth scheme: {none | bearer | OAuth 2.1 + PKCE | mTLS | API key}
- Downstream systems the server's tools can touch
- Deployment context: {personal dev | internal team | production
  customer-facing}

Why: Three things make this distinct from the existing System Design & Architecture entries: (1) STRIDE threat-model generator covers general-system threats organized by S/T/R/I/D/E categories, this fills the MCP-server-specific slot which is now the dominant new privilege boundary in agentic deployments and which the spec has revised twice in 18 months (2025-03-26 deprecated HTTP+SSE, 2025-11-25 is the current Streamable HTTP); STRIDE applied to an MCP server misses the MCP-specific anti-patterns (omnibus tools, untrusted-content fencing, agent-as-credentialed-principal volume × composition assumptions) that the 8-domain × 75-check structure encodes directly. (2) The "agent is a credentialed principal at machine speed in compositions you didn't anticipate" framing collapses the most common security failure mode, teams audit MCP servers with the threat model they'd apply to a human-driven REST API and miss that rate limits calibrated for human use are functionally open doors, that confirmation flows the human pauses for the agent fires through, and that prompt injection from tool responses is now a first-class attack class with no analogue in pre-agent threat models. (3) The "stdio is a transport, not a security control" rule kills the single most expensive mental model error in the audited corpus, teams ship MCP servers with no auth, full admin tokens, and free-form `execute`-style tools because the server "runs locally, " then discover the same code path is the privilege boundary the moment another desktop app, another user account, or a remote-launch wrapper invokes it. The omnibus-tool-is-automatic-CRITICAL rule + the destructive-after-untrusted-read confirmation rule are the two highest-leverage controls and they're both architectural, not policy. Distinct from the Agent blast radius pre-deployment classifier in Workflow & Automation (which classifies AGENT tools into green/yellow/orange/red action tiers at the AGENT layer, what the agent is allowed to invoke); this audits the MCP SERVER layer, what the server exposes and how it defends itself when an agent invokes wrongly. | Use when: Before shipping any MCP server to production (especially remote Streamable HTTP servers, which most often ship without OAuth 2.1 + PKCE entirely), or quarterly on existing servers as a re-audit aligned with SOC2 CC6/CC7/CC8 evidence packs. Pairs with the STRIDE threat-model generator (run STRIDE first on the broader system the MCP server lives in, then this 8-domain audit on the MCP server itself), the Agent blast radius pre-deployment classifier in Workflow & Automation (server-side audit here, client-side tool classification there, they enforce at different layers and both are needed), and the AI agent incident runbook drafter in Documentation (the abuse-path register in DOMAIN 6 is the input to the runbook's blast-radius audit section).

You are auditing a test suite in a codebase that's been (or will be)
refactored with AI assistance. Most unit-test advice optimizes for
CORRECTNESS verification, the wrong target for AI-refactored code, where AI maintains internal consistency beautifully and unit tests
either pass trivially or chase implementation churn. The right target
is CONTRACT PROTECTION: detect silent contract breakage at boundaries
the AI doesn't know matter. Execute phases strictly in order.

PHASE 1, CLASSIFY EVERY TEST INTO ONE OF FOUR LEVELS:

  L1, Method / Class. Tests a single function or class in isolation.
       Purpose: verify unit correctness. EXTINCT in AI-refactored code
       because (a) AI rarely makes unit-level mistakes, (b) tests
       either pass trivially or churn with implementation, (c) the
       signal-to-maintenance ratio drops below 1.

  L2, Cross-class within namespace. Tests how multiple internal
       classes collaborate. Purpose: verify internal wiring. EXTINCT
       in AI-refactored code because AI maintains internal consistency
       across refactors; failures here are nearly always test
       brittleness, not real bugs.

  L3, Namespace boundary. Tests the AGGREGATE INTERFACE a namespace /
       module / package exposes to other namespaces. Purpose: detect
       when AI silently changes an interface other modules depend on.
       SURVIVES because internal classes shifting is fine; the
       namespace's outbound surface is not.

  L4, Public API boundary. Tests the contract exposed to external
       callers (HTTP API, SDK, library consumers). Purpose: protect
       external contracts. SURVIVES because the API is the irrevocable
       boundary, breakage here is incident-class, not refactor-class.

PHASE 2, TAG EVERY TEST. Add an explicit level marker the test
runner can filter on AND the AI can see when it reads the file:
  - C# / xUnit:  [Trait("Level", "L3")]
  - JUnit:       @Tag("L3")
  - pytest:      @pytest.mark.level("L3")
  - Jest / TS:   describe("[L3] ...")
  - Go:          t.Run("L3/...", ...)
The tag has DUAL purpose: it filters CI runs, and when AI encounters
an L3/L4 test it reads "this boundary matters; changes here require
verification", without the tag, the AI cannot tell which tests are
load-bearing and treats them all as fair game to refactor or delete.

PHASE 3, PRUNE THE EXTINCT. For every L1 and L2 test, ask:
  - Does it cover an EXPLICIT EDGE CASE (exception, boundary
    condition, failure mode the happy path won't hit)?
  - If YES: KEEP, retag as L1-EDGE. AI excels at happy paths but
    misses subtle error conditions; these tests retain signal.
  - If NO: DELETE. A passing test that exists only to be updated on
    every refactor is negative-value, it consumes review attention
    and produces no diagnostic.

PHASE 4, PROTECT THE SURVIVING. For every L3 and L4 test:
  - Add a comment above the assertion explaining what CONTRACT is
    being protected and what BREAKING IT MEANS for downstream
    consumers. The comment is the artifact the AI reads first.
  - For L4 (public API): the test asserts the response SHAPE, the
    error codes, and the documented behavior, NOT the implementation
    path. If the implementation can change without the test breaking, the test is correctly scoped. If swapping the DB layer breaks an
    L4 test, the test was L2-in-L4-clothing, rescope it.

PHASE 5, REPORT. Output a table:
  | test file | current level | new level | action (KEEP / EDGE / DELETE / RESCOPE) | contract protected |
Plus four numbers:
  - L1/L2 deleted: N
  - L1-EDGE retained: M
  - L3/L4 retained + retagged: K
  - Estimated maintenance reduction (% of pre-audit test-update PRs)

HARD RULES:
- Do NOT keep an L1/L2 test "just in case." If it doesn't cover an
  edge case AI is likely to miss, it's negative-value in an
  AI-refactored codebase.
- Do NOT classify a test as L4 because it touches an HTTP endpoint.
  L4 means it asserts the CONTRACT, not the path. A test that
  exercises a route to verify a database write is L2 in disguise, rescope or delete.
- Do NOT skip phase 2. Untagged tests are invisible to the AI; it
  cannot honor a "this boundary matters" rule it can't see.
- An L3/L4 test that breaks is a STOP, not a "fix the test" task.
  Investigate before merging, the AI may have improved the
  implementation in a way that changed the contract without realising
  it. That's exactly the silent-breakage failure mode the framework
  exists to catch.

INPUTS:
- Test files / directories to audit: {paste}
- Framework: {xUnit | JUnit | pytest | Jest | Go testing | other}
- Codebase area: {namespace / package / module being audited}
- Recent AI-refactor scope: {what the AI touched in the last N PRs}

Why: Three things make this distinct from the existing Testing & QA entries: (1) Behavior-focused unit tests writes new tests for the *correct* behavior of code, Property-based test author writes invariants, Flaky test root-cause finder triages flaky tests, Characterization tests for legacy code locks in CURRENT behavior including bugs, and Differential mutation-test survivor killer runs mutation testing on AI-generated code, none address the INVERSE problem of *what to KEEP vs. PRUNE* when AI is doing systematic refactoring of an existing test suite, which is now where most engineering teams spend their test-maintenance budget; teams that refactored a codebase with Claude Code or Cursor report L1/L2 tests "becoming meaningless" (passing trivially or requiring constant updates as AI rewrites internals) while L3/L4 tests catch real interface-drift bugs. (2) The L1-L4 classification + dual-purpose `[Trait("Level", "L3")]` tag is the load-bearing piece, the tag filters CI runs AND signals to the AI itself that a boundary is load-bearing; without the tag, the AI can't tell which tests are contract-protecting versus implementation-coupled, so it either treats them all as equal (and you spend weeks fixing brittleness) or asks before each one (and productivity collapses). The "untagged tests are invisible to the AI" rule operationalizes the insight that test classification is now a COMMUNICATION channel between human and agent, not just a CI filter. (3) The "L1/L2 are extinct in AI-refactored code" claim inverts the default test-everything-at-every-level intuition and frees the team to delete tests that produce no signal, paired with the "EXCEPT explicit edge cases → L1-EDGE retag" exception, which preserves the genuinely valuable error-path tests AI rarely exercises during normal happy-path development. The "L4 means contract, not path" rule kills the most common misclassification (L2-in-L4-clothing tests that exercise an HTTP route to verify a DB write), which is the failure mode that makes "we have integration tests" mean nothing under AI refactor. | Use when: Auditing a test suite heavily refactored by AI in the last N sprints where the team spends more time updating tests than shipping features, before greenlighting an unattended Claude Code / Cursor agent to refactor a module (mark the L3/L4 protection layer FIRST so the AI knows what it can't change), or quarterly on any codebase where AI-assisted refactoring is now standard practice. Pairs with the existing Characterization tests for legacy code (use that BEFORE refactor to lock in current behavior; use this AFTER refactor to prune the test suite to what still provides signal), Differential mutation-test survivor killer (apply it specifically to the L3/L4 retained set, those are the tests that should resist mutation; L1/L2 mutation testing is wasted budget under AI refactor), the Harness engineering blueprint in Workflow & Automation (the L3/L4 retained tests become the harness's computational-test sensor; the tag means the harness can filter to fast-iteration L3/L4 runs and full L1-EDGE+L3+L4 runs at the verify gate), and the Cross-language migration scaffolder in Workflow & Automation (that scaffolder produces the migrated codebase; this prompt produces the test suite that protects it post-migration).

You are extracting an Architecture Decision Record from a pull request
that ALREADY SHIPPED. The decision was made; the code was merged; no one
wrote it down. Your job is to reconstruct the ADR from the artifacts that
exist, the PR diff, description, review comments, and produce a record
the team can commit to docs/adr/ today.

STEP 1, DETECTION. Decide whether this PR contains an architectural
decision worth recording. An architectural decision is ONE of:
  1. A new dependency added (package.json / Cargo.toml / go.mod / pyproject.toml).
  2. A change to a data structure or DB schema (migration, new table, column type change, index change, FK change).
  3. A new PATTERN introduced (caching, queueing, retry strategy, pub/sub, eventing, circuit breaker, feature-flag scheme).
  4. An API contract change (route added/removed/renamed, request or
     response shape changed, auth scheme changed, status-code mapping changed).
  5. A choice between two or more approaches that was DEBATED in the PR
     description, review comments, or linked discussion.

If NONE of the 5 criteria apply, output exactly:
  "No ADR needed, {one sentence on why this PR is implementation-only}"
and stop. Do not invent a decision. The "no decision here" output is
load-bearing, the failure mode of this prompt is manufacturing ADRs
for routine bug fixes, which floods docs/adr/ with noise that drives
the genuine ADRs into obscurity.

STEP 2, DRAFT. If at least one criterion applies, generate:

# ADR-{number}: {Decision title, noun phrase, not a sentence}

You are wiring documentation freshness into CI as a per-page 0-100 score
that gates merges the same way a flaky-test budget does. The deterministic
math is below; you are responsible for the Claude semantic-check prompt
that handles the gray zone deterministic checks cannot resolve.

THREE DETERMINISTIC SIGNALS (cheap, reproducible, no LLM):

  1. GIT AGE DELTA. For each doc page, compute
        doc_age_days   = days since the page's last commit (use git log
                         --follow so renames don't reset the clock)
        code_age_days  = min(days since last commit) across the
                         frontmatter `sources:` globs
        age_penalty    = clamp((doc_age_days - code_age_days) / 3, 0, 30)
     On a long-lived feature branch, compute the delta against
     git merge-base origin/main HEAD, NOT origin/main directly, otherwise
     a six-week branch eats penalty for code that moved in tandem.

  2. PER-PAGE TTL CONTRACT. Each doc declares its shelf life in YAML
     frontmatter:
        freshness:
          ttl_days: 90              # quickstart, release-bound
          # ttl_days: 365           # architecture overview, stable
          sources:
            - "src/api/users.ts"
            - "src/api/users/*.ts"
          critical: true            # optional, raises this page to a
                                    # hard SLO with a 60 floor
        ttl_penalty = max(0, (doc_age_days - ttl_days) * 2)
     TTL is per-page on purpose. A directory-wide threshold either nags
     stable pages or gives live pages too much rope.

  3. SYMBOL-LEVEL DRIFT. Extract every backticked token from the page
     body (regex `([A-Za-z_][A-Za-z0-9_]*)`). For each source file in
     `sources:`, build a live-symbol set (tree-sitter query on
     function_declaration / class_declaration / method_definition; regex
     fallback for prototype). For dotted references like
     `MyClass.my_method`, split on `.` and count as a hit if every
     component is in the live-symbol set, otherwise legitimate method
     references read as drift.
        missing = referenced_symbols - live_symbols
        drift_penalty = min(40, len(missing) * 10)

  COMBINE:
        score = max(0, 100 - age_penalty - drift_penalty - ttl_penalty)
  EXCLUDE: CHANGELOG.md and historical pages with
  `freshness: { exclude: true }`, they legitimately reference removed
  symbols.

GRAY-ZONE LLM CHECK (the only place Claude runs).
Pages scoring 35-64 are the band where pattern-match cannot decide, the symbols exist but the behavior around them may have changed.
Filter to that band; do NOT send 100-scoring or 18-scoring pages to
Claude. The gray-zone prompt is exactly:

  Read each page listed in /tmp/gray.txt and the source files in its
  frontmatter `sources` block. For each page, decide whether the
  documented behavior still matches the code.
  - Compare claims about return shape, error cases, side effects, auth requirements, and ordering against the source.
  - Ignore cosmetic differences (whitespace, variable renames inside
    function bodies).
  - DO NOT propose edits. Classify only.
  Respond with one line per page, EXACTLY this format:
        {path}: {VERDICT}, {one-line reason citing a specific
                              line, symbol, or behavior}
  VERDICT is one of: STILL_ACCURATE | DRIFTED | NEEDS_HUMAN_REVIEW.
  Use NEEDS_HUMAN_REVIEW when the source pulls behavior from a file
  not listed in `sources` or when the doc describes a contract you
  cannot verify from code alone.

Run Claude with --max-turns 8, --allowedTools "Read, Glob, Grep", and
continue-on-error: TRUE. The semantic check is an assist. The hard gate
is the deterministic score below.

TWO SLIs ON THE SAME freshness.json (different jobs):
  - PR-delta SLI (mean, noisy by design): per-PR sticky comment, fails
    on a >=4-point drop on the PR head. Mean is right here because one
    page tanking 40 points MUST move the headline.
  - Trend SLI (median, stable by design): rolling 7-day, fails when
    median < 75. Allow median dips below floor for up to 10% of green
    main samples in a 28-day window before treating it as impact.

CRITICAL-PAGE HARD FLOOR. Any page marked `critical: true` fails the
build at score <= 60 (INCLUSIVE comparison, the one-point cliff is
intentional; there is no error budget on a promise-level page).

ESCAPE HATCH. Honor a `bypass-freshness-gate` PR label for incident
response. The workflow re-runs on `labeled`/`unlabeled` events so a
freshly-applied label clears the required-check.

ROLLOUT (4 steps, ~3 weeks):
  1. Land the workflow with FRESHNESS_BOOTSTRAP=1. Pages without
     `sources:` opt out of the drift signal so the baseline isn't
     poisoned by every backticked token reading as missing.
  2. Map your top 10 most-edited pages with `sources:` blocks.
  3. Add an allowlist for inline-code regex false positives (CLI flags, env vars). Map another 10-20 pages.
  4. Drop FRESHNESS_BOOTSTRAP. Median should sit above 75; if not, you
     have a real drift problem the score just made legible.

HARD RULES:
- Do NOT route 100-scoring or below-35-scoring pages to Claude. The
  deterministic signal is correct on the extremes; the LLM call is
  pure cost.
- Do NOT compare the PR-delta SLI to the median or the Trend SLI to the
  mean. Each statistic exists because the other one would lie in its
  role.
- Do NOT let Claude's verdict gate the build. Anthropic API flakes
  must not fail a release pipeline.
- Do NOT include `freshness: { exclude: true }` pages in the median
  calculation, they skew the floor downward for no reason.

Why: Distinct from every existing Documentation entry, API endpoint doc generator writes reference docs from code, Postmortem timeline reconstruction reconstructs incidents, AI agent incident runbook drafter is operational, Error message documentation is per-error, Documentation gap audit is a reader-perspective one-time scan with BLOCKS/SLOWS/MINOR tiers, Retrospective ADR generator captures one decision at a time. None of them gives docs an SLO that runs on every PR. The 2024 ESE study cited by Dosu found 28.9% of popular GitHub repos document a function/file/class that no longer exists, average outdated reference wrong for 4.7 years, drift is the dominant doc-quality failure mode, and the only way to keep up with AI-accelerated code velocity is to gate on it the same way you gate on tests. Three things make this the kill-shot paste-ready prompt and not a tutorial summary: (1) the deterministic-first architecture (three signals computed BEFORE Claude is ever called) avoids the canonical mistake of "ask Claude if the docs are fresh", which is unreliable, expensive at scale, and gives no signal you can plot; the score is reproducible and graphable, the LLM only fills the 35-64 gray zone. (2) The two-SLI split, mean for the PR delta (so one critical page tanking is immediately visible) and median for the trend (so long-term drift drives the review), is the field-tested fix for the "median across 15 pages doesn't move when one page collapses" failure that breaks naive single-statistic dashboards; most freshness-score guides ship one number and either over-fire or under-fire. (3) The frontmatter contract (`ttl_days` + `sources` + `critical`) is the load-bearing primitive, without it, the score has no baseline to decay from, and adding it forces page owners to make commitments that are legible at PR time; the critical-page inclusive `<=60` hard floor with the explicit one-point-cliff justification is what turns "we should keep docs fresh" into a per-page contract with consequences. The exact 35-64 gray-zone band, the continue-on-error: true rule, and the STILL_ACCURATE | DRIFTED | NEEDS_HUMAN_REVIEW classification with the "DO NOT propose edits, classify only" constraint are operational details that turn the Claude call from an open-ended doc-review chat (expensive, noisy, drifts into rewriting) into a structured judgment call that costs ~$0.05-0.15 per PR. Pairs with the existing Documentation gap audit (run that quarterly to find missing pages; run THIS on every PR to keep existing pages honest) and the Retrospective ADR generator (that produces NEW pages; this keeps them fresh once they're in docs/adr/). | Use when: Docs are starting to lie because code is moving faster than the team can hand-edit pages; an AI coding agent is generating PRs that don't touch docs even when behavior changes; you want a public README badge that turns docs-freshness into a recruiting/credibility signal; you need an SLO for documentation the same way you have one for tests and latency. Skip on small repos with <20 pages (the median is too noisy to gate on under 50 pages) and on docs that live primarily in Notion / Confluence / a hosted platform outside Git (this signal only sees in-repo content). On polyglot monorepos, swap the regex symbol extractor for a tree-sitter dispatcher keyed by file extension, the input/output shape of `_live_symbols` doesn't change.

You are auditing the prompt-caching posture of a production LLM
workload. As of early 2026, Anthropic dropped the prompt cache TTL
from 60 minutes to 5 minutes, a change that increased effective
API costs by 30-60% for many workloads tuned for the old TTL and
that, in low-traffic scenarios, makes caching ACTIVELY MORE
EXPENSIVE than not caching at all. The audit's job is to figure
out, per workload, which side of the breakeven you're on and what
to do about it.

PHASE 1, MEASURE THE ACTUAL HIT RATE. Do not skip to fixes.
Pull usage stats from the API response on production traffic
(`usage.input_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`) for at least one full traffic
cycle (24h covering peak + trough, weekend if relevant). Compute:
- Cache hit rate = cache_read / (cache_read + cache_creation)
- Average reads per write per 5-min window
- Cached prefix size in tokens
- Spend split: write premium vs. read savings vs. uncached input
A hit rate <60% with non-trivial cache writes is a yellow flag;
<30% is a red flag (you are likely losing money by caching).

PHASE 2, APPLY THE BREAKEVEN FORMULA, PER WORKLOAD.
Caching pays off only if:
  reads_per_5min × (base_input_price - cache_read_price) >
  cache_write_premium

For Claude Sonnet 4.6 reference economics ($3.00 base input, $3.75 cache write, $0.30 cache read per 1M tokens):
  - 5-min TTL: breakeven at ~1.3 reads per write
  - Below 1.3 reads/window: caching costs MORE than not caching
  - At 2 reads/window: marginal, depends on prefix size
  - At 10+ reads/window: caching wins decisively
For each workload, state the per-5-min-window read count, the
prefix size, and the verdict: KEEP / BATCH / DISABLE / KEEPALIVE.

PHASE 3, CLASSIFY WORKLOAD INTO ONE OF FOUR PATTERNS.
Each maps to a SPECIFIC fix; misclassifying produces the wrong
remediation:

PATTERN A, KEEP-ALIVE PING (long-lived servers with high-value
cache, intermittent user traffic). Spawn a daemon thread that
sends a 1-token request with the cached prefix every 4 minutes
(reset before 5-min expiry). Fix code (Python):
    def _ping():
        while True:
            time.sleep(240)  # 4 min, reset BEFORE 5-min TTL
            client.messages.create(
                model="claude-sonnet-4-6", max_tokens=1, system=[{
                    "type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}, }], messages=[{"role": "user", "content": "ping"}], )
USE WHEN: long-lived API server, chat backend with idle users.
DON'T USE: serverless / cron, no persistent process to host the
keepalive.

PATTERN B, BATCHING (workload arrives in irregular drips but
can be coalesced). Accumulate work in a queue and process N items
in a tight burst (single cache write amortized across N reads).
Target burst window <2 min so all items land in one TTL.
USE WHEN: document-processing pipelines, async job queues, notification fan-out.
DON'T USE: latency-sensitive user-facing requests.

PATTERN C, DISABLE CACHING (low-traffic, irregular pattern).
If reads_per_5min < 1.3 for the prefix size, DROP the
cache_control directive entirely. Paying the 25% write premium
without enough reads to amortize it is strictly more expensive
than uncached.
USE WHEN: low-traffic production apps, staging/dev environments, cron jobs with >15 min gaps, any workload where keepalive isn't
viable and batching can't reach 2+ reads/window.

PATTERN D, STRUCTURE PROMPTS FOR BYTE-IDENTICAL REUSE. The most
common silent killer: ANY character difference in the cached
prefix invalidates the cache. Audit your prompt assembly:
  BAD:  system = f"You are helpful. Time: {datetime.now()}. {long_context}"
        # timestamp in prefix invalidates cache EVERY request
  GOOD: system = LONG_CONTEXT  # static, cacheable
        user = f"Time: {datetime.now()}. Query: {query}"
        # dynamic content in user turn; system prefix is byte-stable
Rules:
- NO timestamps, request IDs, user names, session IDs in the
  cached prefix
- NO dict-iteration that produces non-deterministic key order
  (Python <3.7 / Go maps / JSON.stringify on a Map)
- Tool definitions count as cached prefix, adding/reordering one
  tool invalidates cache for ALL requests
- Even whitespace counts, trailing newline difference is a miss

PHASE 4, REARCHITECTURE DELIVERABLE. For each audited workload
produce:
  | workload | prefix tokens | reads/5min | hit rate | spend now | pattern | spend after fix |
Plus the SPECIFIC diff for each fix (the daemon thread, the
batch coalescer, the cache_control removal, the prompt
restructuring).

PHASE 5, STANDING MONITORING. Hit rate is not a one-shot audit.
Add to your observability stack:
- Per-deployment cache_hit_rate metric (alert if drops >20%
  week-over-week, usually a prompt edit accidentally broke
  byte-stability)
- Per-workload reads_per_write distribution (catches
  pattern-shift before it shows up on the invoice)
- Cache write cost as a % of total LLM spend (climbing % with
  flat read % = write premium with no payoff)

INPUTS:
- Workload name + description (cron job / API endpoint /
  background worker / chat session)
- Cached prefix tokens (system prompt + tool definitions +
  static context)
- Observed requests/hour (with daily distribution if uneven)
- Current cache_control posture (caching on/off + which blocks)
- Provider + model (pricing varies; formula above is for Claude
  Sonnet 4.6, re-derive for Haiku / Opus / OpenAI cache pricing)

HARD RULES:
- Do NOT enable caching by default on a new workload. Measure
  read rate first, then decide.
- Do NOT add caching to LOW-TRAFFIC workloads "to be safe." The
  5-min TTL inverts the cost math; you'll silently lose money.
- Do NOT skip Phase 4 byte-identical audit on workloads that
  "should be caching", a 65% hit rate with a 10k-token prefix
  is almost always a sneaky timestamp / iteration-order / tool
  reordering bug, not actual cache misses.
- Do NOT keep "we've always cached this" as a justification, the TTL change in early 2026 invalidated most pre-2026
  caching tuning. Re-audit anything tuned before then.

Why: Three things make this distinct from the existing Workflow & Automation entries: (1) Production routine design table covers 6 deployment governance dimensions, Agent blast radius pre-deployment classifier covers per-tool worst-case-reversibility, and LLM provider snapshot rollout discipline covers model version bumps, none address LLM COST DISCIPLINE, which became materially more expensive in early 2026 when Anthropic silently dropped the prompt cache TTL from 60 minutes to 5 minutes; this is now the single largest hidden-cost driver in production LLM workloads and zero existing entries surface it. (2) The breakeven formula (`reads_per_5min × (base - read_price) > write_premium`) is the load-bearing piece, most teams flip caching on because "it's a savings feature, " but at the new 5-min TTL the ~1.3-reads-per-window threshold means LOW-TRAFFIC workloads actively lose money by caching, and without the formula in hand the audit reduces to vibes ("our cache hit rate is 40%, should we worry?"). (3) The four-pattern classifier (keepalive ping / batching / disable / byte-identical-prefix discipline) maps each workload shape to a SPECIFIC fix, without the classifier, every fix gets jammed into "enable caching with cache_control on the system prompt, " which is exactly the pattern that costs more than no caching at all on intermittent workloads. The byte-identical-prefix audit catches the most common silent failure mode where a prompt looks cacheable but a hidden timestamp or non-deterministic dict iteration order produces a cache miss on every request (the team sees a low hit rate, assumes it's traffic-pattern noise, and keeps paying the write premium for nothing). Pairs naturally with the existing Production routine design table (when designing a new routine, include a "should this cache?" decision against this prompt's breakeven formula) and the LLM provider snapshot rollout discipline (a model bump can change tokenizer behavior in ways that silently invalidate cache hit rates, Phase 1 behavioral evals should include cache-hit-rate delta as a tracked slice). | Use when: Quarterly audit on production LLM workloads (especially anything tuned for the pre-2026 60-min TTL), after observing an unexplained LLM bill spike, before enabling caching on a new workload (default off, measure read rate, decide), or when investigating why "we added caching but costs didn't drop" reports come in from the finance side. Especially valuable on intermittent / bursty workloads (cron jobs, document processors, dev / staging environments) where the breakeven math most often falls on the wrong side. Pairs with the Production routine design table (cache decision belongs in the design table for any new routine) and the LLM provider snapshot rollout discipline in this section (the regression-eval phase should monitor cache-hit-rate as a behavioral slice, because model / tokenizer changes silently shift it).

You are designing the HARNESS around an AI coding agent before
letting it run unattended on a non-trivial task. "Harness
engineering" is the 2026 evolution past prompt engineering and
context engineering, the deliberate construction of the SENSORS, CONSTRAINTS, and PHASE GATES that surround the agent so a
probabilistic engine produces deterministic outcomes. The agent is
not the system. The harness is the system.

Output ONE BLUEPRINT covering four sections. Skipping any section
is how "we tried Claude Code and it ships garbage" happens.

1. COMPUTATIONAL SENSORS (deterministic, run on every iteration).
   List the four sensor types and the SPECIFIC tooling wired into
   the harness for each. A sensor the agent can be asked to
   "remember to run" is not a sensor, it must FIRE automatically
   and BLOCK on red:
   - TYPE CHECK: {strict tsc / mypy --strict / cargo check /
     go vet}, pick a strongly typed language where possible; the
     type system is your most expressive harness for free.
   - LINT / STYLE: {ruff / eslint --strict / golangci-lint /
     clippy}, every rule the team enforces in code review goes
     here. If you ever wrote "follow our coding standards" in a
     system prompt, replace it with a lint rule.
   - TESTS: which test suites run, in what order, with what
     timeout. Unit / integration / characterization split. Run
     on every change.
   - ARCHITECTURAL FITNESS: {ArchUnit / dependency-cruiser /
     no-direct-db-import-from-handler ESLint rule / custom AST
     check}, encode "domain has no infra imports" / "no circular
     deps" / "handlers don't call repositories directly" as a
     runnable check. This is the rule layer the agent will
     silently violate without enforcement.

2. INFERENTIAL SENSORS (LLM-judged, run at phase boundaries).
   Computational sensors catch what's deterministic; inferential
   sensors catch what isn't. Two minimum:
   - SEMANTIC DIFF REVIEWER: a separate LLM call (cheaper model, fresh context) reads the diff against the PLAN and answers:
     "did the agent implement the planned change, or did it
     drift?" Output: pass / fail / drift-summary.
   - INVARIANT JUDGE: a fresh LLM call applies a rubric for
     properties the codebase must maintain (no PII in logs, no
     hard-coded secrets, no new public APIs without a contract).
     Use the LLM-as-judge faithfulness rubric pattern, enumerate
     before scoring, deterministic verdict rule, temperature 0.

3. PHASE GATES, PLAN → EXECUTE → VERIFY, no phase collapses.
   The agent runs one phase at a time. Each gate is a HARD BLOCK;
   the agent does not advance until the gate is green.
   - PLAN GATE: the agent emits a structured IMPACT MAP before
     any code: files touched, functions modified, public-API
     changes, test plan, rollback plan. Human or automated
     reviewer approves the impact map. If the agent skips the
     plan, the harness REJECTS and re-prompts with the missing
     artifact. NO code-first.
   - EXECUTE GATE: after each atomic commit, all computational
     sensors run. Red sensor → automatic rollback of that commit, return error context to agent, retry with bounded budget
     (typically 3 attempts). After budget exhausted → escalate
     to PLAN gate with failure context, regenerate the remaining
     plan.
   - VERIFY GATE: inferential sensors run on the full diff.
     Semantic drift OR invariant violation → block, return rubric
     output to agent for revision. Only after both inferential
     sensors return pass does the harness produce the PR for
     human review.

4. IMPACT MAP, the structured handoff artifact between phases.
   The plan-to-execute handoff is where most agent runs lose
   coherence. The impact map is the CONTRACT. Required fields:
   - Files in scope (allowlist, agent cannot touch others)
   - Files explicitly out of scope (denylist, explicit guardrail)
   - Functions / classes added, modified, removed
   - Public-API surface changes (Y/N, if Y, contract gate
     triggers)
   - Test plan (which tests added, which existing tests should
     still pass, which are expected to fail and why)
   - Rollback path (single command, must be testable)
   - Risk register (top 3 things that could go wrong, with
     mitigation)

HARD RULES:
- Do NOT write "the agent should run tests after each change", wire the tests to fire automatically and block. If a rule is
  in the prompt instead of the harness, you've moved from harness
  engineering back to prompt engineering.
- Do NOT skip the inferential sensors. Computational sensors catch
  syntax and structure; they miss semantic drift (the agent
  implements the wrong thing correctly).
- Do NOT let the agent emit the impact map AND the implementation
  in one turn. The plan/execute split is what allows the plan to
  be reviewed BEFORE code locks in the wrong direction.
- Do NOT collapse the verify gate into "tests pass." Tests prove
  the code does SOMETHING; the inferential semantic-diff reviewer
  proves the code does the RIGHT thing.

INPUTS:
- Codebase language / framework / size: {e.g. TypeScript /
  Next.js / 80k LOC}
- Task type: {feature add / refactor / migration / bug fix}
- Agent: {Claude Code / Cursor / Codex / custom}
- Existing harness components (what's already wired): {list}
- Risk tolerance for this task: {sandbox / staging / production}

OUTPUT:
- The blueprint as a markdown doc with the four sections populated
- A checklist of harness components MISSING from the current setup, ranked by impact-per-effort
- One STOP-SHIP question: which single missing sensor, if absent
  today, is the most likely cause of the next agent-produced
  regression?

Why: Three things make this distinct from the existing Workflow & Automation entries: (1) the existing agent entries (Production routine design table, Cross-language migration scaffolder, Agent blast radius pre-deployment classifier, LLM provider snapshot rollout, Prompt-cache audit) cover deployment governance / one-time migrations / per-tool risk classification / model bumps / cost, none address the OUTER FRAME of sensors + constraints + gates that surrounds a coding agent during execution, which is what Karpathy named "agentic engineering" in February 2026 and what Martin Fowler / Augment Code / Red Hat / Stripe's Minions / OpenAI's Codex case study consolidated as the 2026 paradigm shift past prompt engineering and context engineering. (2) The computational / inferential sensor split is the key insight that fixes the most common "AI coding agent is unreliable" failure mode, teams wire syntax/type/lint/test sensors but forget the inferential layer (semantic-diff reviewer + invariant judge), and the agent ships code that PASSES all deterministic checks while implementing the wrong thing; computational sensors catch what's deterministic, inferential sensors catch what isn't, and you need both. (3) The "if a rule is in the prompt instead of the harness, you've moved back to prompt engineering" hard rule is the kill-shot, it inverts the most common failure mode where teams keep adding instructions to CLAUDE.md and watch them silently get ignored under edge inputs; harness engineering's central claim (Fowler: "architectural constraints are enforced by linters, not prompts") is that DETERMINISTIC enforcement beats PROBABILISTIC compliance, and the rule operationalizes that claim. The impact map as the plan-to-execute handoff contract solves the specific failure where the agent emits a plan AND code in one turn, the plan was wrong, but you only find out after the code has locked it in. | Use when: Before setting up any unattended Claude Code / Cursor / Codex loop, before letting an agent loose on a non-trivial refactor or feature add, or when auditing an existing agent setup that "works most of the time but occasionally ships something terrible", the audit always finds at least one missing computational sensor (architectural fitness is the most commonly missed) or both inferential sensors entirely absent. Pairs with the existing Production routine design table (this prompt is the runtime harness; that one is the deployment governance around the harness), the Agent blast radius pre-deployment classifier (this designs sensors; that designs per-tool risk tiers, both required), the LLM-as-judge faithfulness rubric in Prompt Engineering Meta (its 4-part structure is exactly what the invariant judge sensor uses), and the Cross-language migration scaffolder (which is a specific instance of this blueprint applied to one task type, CLAUDE.md + MIGRATION.md as the impact-map artifact for a migration).

You are about to describe a task to Claude Code that will run as a DYNAMIC
WORKFLOW (an orchestration JavaScript that fans out 16-1000 parallel
subagents in a runtime separate from your session; intermediate state
lives in script variables, not the context window; results are
adversarially cross-checked before reaching you; the run is resumable in
the same session). Do NOT write a prose paragraph and hope Claude picks
the right shape, that's how a workflow burns 200k tokens producing
nothing better than a single-pass agent would have. Fill out this brief, every section, in this order, then paste it after the trigger word
`workflow` (Claude Code highlights the word and routes to the workflow
runtime).

1. TASK SHAPE, pick ONE, name it explicitly. If the task fits none of
   these four, STOP, a workflow is the wrong primitive; use a single
   agent + skills, or break into smaller workflows:
   - REPO-WIDE SCAN: same question against every file/module in scope
     (auth audit, dead-code hunt, profiler-guided perf scan, license
     scan, security audit). Naturally parallel. Expected output: one
     finding per location plus a roll-up.
   - LARGE TRANSFORMATION: same transformation across hundreds-to-
     thousands of files (framework swap, API deprecation, language
     port, type-system migration). Per-file work + a fix loop. Expected
     output: green build + green test suite.
   - ADVERSARIAL PLAN: ONE question, drafted from N independent angles, weighed against each other by refuter agents (architecture
     proposal, threat model, rollout plan, incident response plan).
     Expected output: a single recommendation with the rejected
     alternatives and the specific refutation that killed each.
   - CROSS-CHECKED RESEARCH: one question, sources fetched in parallel, claims voted across sources, low-confidence claims dropped.
     Expected output: a cited report with unsupported claims filtered
     out (this is what the built-in `/deep-research` does).

2. SCOPE, be merciless. Soft scope = runaway run:
   - Exact path(s) the workflow touches: `src/routes/**/*.ts`, NOT
     "the API".
   - Exact exclusions: vendored code, generated code, third-party SDK
     directories, build artifacts.
   - Per-phase agent count ceiling. Default: phase-1 (scan) up to 50;
     phase-2 (verify) exactly 1 verifier per phase-1 finding; phase-3
     (synthesize) exactly 1. HARD CAP: 1000 agents per run, 16
     concurrent. If your scope can't bound itself under 1000, narrow
     it BEFORE the run, narrowing mid-run loses the in-flight agents'
     work.

3. PHASES, write as a numbered list, each phase a single sentence
   with its QUALITY GATE:
   "Phase N: {what each agent does}. Gate: {what makes a finding
   survive to the next phase}."
   The gate is the most important field, it is what makes a workflow
   beat a single-pass agent. Without it you have parallel single-agent
   calls, not a workflow. Default gates by shape:
   - REPO-WIDE SCAN gate: a second agent (different prompt, different
     starting context, no access to the first agent's notes)
     independently reproduces the finding from raw evidence. Only
     findings reproduced by both survive.
   - LARGE TRANSFORMATION gate: per-file build + targeted test pass.
     Fix-loop until both pass or the file is flagged for human.
   - ADVERSARIAL PLAN gate: a refuter agent attempts to break each
     angle's plan with a specific failure scenario. Only angles that
     survive their refutation move forward.
   - CROSS-CHECKED RESEARCH gate: each claim must appear in at least
     2 independent sources; claims that don't are dropped, not
     hedged.
   The LAST phase MUST be synthesis to a SINGLE artifact (markdown
   report, PR description, list of file edits). Workflows return ONE
   answer to the session, design backwards from that artifact.

4. KILL CRITERIA, explicit STOP conditions, not just "when done":
   - For LARGE TRANSFORMATION: a test-suite-pass-rate threshold
     ("≥99% of existing tests pass", the Bun Zig→Rust workflow ran to
     99.8% over 750k lines / 11 days).
   - For ADVERSARIAL PLAN / CROSS-CHECKED RESEARCH: a convergence rule
     ("stop when the same finding appears in 3+ independent angles" OR
     "stop when a new angle produces no claims that survive the gate").
   - Cost ceiling: maximum token budget or agent-runtime hours after
     which the workflow pauses for human review. Default: pause at
     half a tank, not at empty.

5. SAVE-AS-COMMAND DECISION, decide BEFORE the run, not after:
   - One-off (an investigation, a research question, a "let me try"):
     do NOT save. Saved workflows become `/`-autocomplete commands and
     a polluted namespace makes the keeper workflows harder to find.
   - Repeatable per-team (every-branch security review, weekly
     dead-code sweep, per-PR migration check): save to
     `.claude/workflows/` (shared with the repo).
   - Repeatable personal (your own pre-merge audit, your own research
     template): save to `~/.claude/workflows/` (only you see it).

6. PRE-RUN ALLOWLIST, list the shell commands, web fetches, and MCP
   tools the agents will need, and add them to your allowlist BEFORE
   the run starts. Mid-run permission prompts on a 200-agent run pause
   the runtime and burn both your patience and your token budget. The
   subagents always run in `acceptEdits` mode regardless of your
   session's permission mode, file edits are auto-approved, so the
   allowlist is your only chokepoint for tool calls.

After filling this in, prepend the word `workflow` to your prompt so
Claude Code routes it to the workflow runtime. When the approval prompt
appears, press `Ctrl+G` to VIEW THE RAW SCRIPT before approving, the
JavaScript orchestration script IS the artifact a workflow produces
(saving as a command just persists this script), and a 30-second read
catches a misshaped phase plan that would otherwise burn 90 minutes.
Approve with "Yes, and don't ask again for {name} in {path}" only after
the first successful run for that workflow in that project.

Why: Dynamic workflows (Anthropic, May 28 2026, released two days ago at time of writing) are a NEW orchestration primitive, Claude writes a JavaScript orchestration script that runs 16-1000 parallel subagents in a separate runtime, with intermediate state in script variables instead of the context window and a quality gate per phase, and every existing Workflow & Automation entry in this doc is about deployment / governance / harness / cost / migration, not about how to *shape a task* for the new runtime. The brief is engineered around the four task shapes Anthropic itself documents (repo-wide scan / large transformation / adversarial plan / cross-checked research) and the "if it fits none of these four, STOP, workflows are the wrong primitive" rule kills the load-bearing failure mode of wrapping a vague request in `workflow` and burning thousands of tokens on an unbounded run. The QUALITY GATE field is the actual mechanic that makes workflows beat single-pass agents (independent reproduction of findings, adversarial refutation, cross-source voting, NOT just more agents in parallel) and most paste-ready "workflow templates" omit the gate entirely and produce nothing better than parallel single-agent calls; spelling out the default gate per shape ("different prompt, different starting context, no access to the first agent's notes" for scans; "refuter agent attempts to break each angle with a specific failure scenario" for plans) is what turns the gate from a slogan into a mechanism. The 1000-agent / 16-concurrent hard caps and the per-phase agent ceiling are the real resource constraint the runtime enforces, soft scope = runaway run, and naming the constraint upfront with "narrowing mid-run loses in-flight agents' work" forces the discipline at the only moment it's cheap. The Bun Zig→Rust 99.8% test-pass threshold over 750k lines / 11 days from Jarred Sumner's case study (highlighted in Anthropic's launch post) is a concrete operating point for transformation workflows, most prompts give you "stop when done" which means "stop when the budget runs out." The save-as-command decision matters because saved workflows become `/`-autocomplete commands and Anthropic's docs put the save decision AFTER the run, but deciding before is much cheaper than evicting a polluted namespace later, and the project-vs-personal location split is the actual scoping mechanism. The `Ctrl+G` view-raw-script rule is the highest-leverage cheap operation in the whole workflow lifecycle: the script IS the artifact, and a 30-second read catches a misshaped phase plan that would otherwise burn 90 minutes; this rule is buried in the docs and missing from every paste-ready "workflow template" elsewhere on the web. The subagents-always-run-in-acceptEdits-regardless-of-session-mode detail is the security tell that makes the pre-run allowlist non-optional rather than nice-to-have. Distinct from Supervisor + subagent pattern (Claude-as-orchestrator with plan in context window, different primitive, doesn't scale past a few delegated tasks), Headless scheduled audit (single agent in CI, not parallel verification), Production routine design table (deployment governance for a long-lived agent, not a one-shot orchestration), Cross-language migration scaffolder (a specific *instance* of a LARGE TRANSFORMATION workflow, the CLAUDE.md + MIGRATION.md it produces are exactly the per-file context the workflow's transformation agents will read every iteration), and the Harness engineering blueprint (which is the runtime sensors the agents inside the workflow run against). Pairs upstream with Agent blast radius pre-deployment classifier (the workflow's tool allowlist IS the blast radius, decided upfront in section 6) and downstream with LLM provider snapshot rollout discipline (a saved workflow that runs in CI should be pinned to a model version like any other production prompt). | Use when: A task is too big for one conversation, codebase-wide audits, migrations spanning hundreds-to-thousands of files, plans you want stress-tested from independent angles, research questions where you want claims cross-checked across sources before you read them. Skip for routine single-agent work, workflows consume meaningfully more tokens, and Anthropic recommends "starting on a scoped task to get a feel for usage." Pair with the existing Cross-language migration scaffolder (which gives you the CLAUDE.md + MIGRATION.md the workflow's per-file transformation agents will read on every iteration), the existing Agent blast radius classifier (the workflow's section-6 allowlist IS the blast radius), and the LLM-as-judge faithfulness rubric in Prompt Engineering Meta (its 4-part structure is what the synthesis phase's quality gate should use when grading the candidate output before it returns to the session).

ROLE: Agent security architect applying Meta's Agents Rule of Two
(Oct 2025) as a HARD STRUCTURAL invariant, NOT a probabilistic
defense, NOT a policy-layer mitigation.

THE RULE.
Within a single agent operational context, AT MOST TWO of the
following three properties may be simultaneously true:
  A. UNTRUSTED INPUT, the agent ingests content from sources the
     adversary can influence: web pages, email bodies, user-uploaded
     files, third-party API responses, retrieved-doc text, tool output
     from non-first-party services, MCP-server responses from external
     servers, transcribed audio/video, chat messages from non-employees.
  B. SENSITIVE DATA OR SYSTEMS, read access to PII, secrets, internal
     code, prod databases, customer records, private repos, billing
     systems, identity providers, employee directories.
  C. EXTERNAL STATE CHANGE OR COMMUNICATION, write actions, sends, or
     posts: file commits, POST/PATCH/DELETE on any API, money
     movement, calendar invites, email send, Slack post (including
     DM), webhook fire, infra mutation, prompt-cache writes that other
     sessions read.
If A AND B AND C are true together, a single prompt injection in the
A source can exfiltrate B via C, system-prompt instructions
("ignore injected commands") DO NOT change this. Treat as structural.

INPUT (paste below):
  1. Agent name + one-sentence purpose.
  2. Tool inventory: name | what it reads | what state it writes |
     auth scope | trust class of any input it consumes.
  3. All untrusted-input entry points (A1..An).
  4. All sensitive resources the agent can reach (B1..Bn).
  5. All write/comms capabilities (C1..Cn).

OUTPUT (in this exact order, do not skip sections):

1) PER-TOOL CLASSIFICATION TABLE.
   One row per tool. Columns: tool | A? | B? | C?.
   FLAG any single tool that is A∧B∧C internally, that is an
   automatic FAIL even if the rest of the agent is clean.
   (Example trap: a "summarize-doc-and-post-to-Slack" tool that reads
   a private repo doc, A from doc, B from repo, C from Slack post.)

2) CONTEXT-LEVEL TRIPLE CHECK.
   Across ALL tools available in one session: does the agent satisfy
   A∧B∧C? Yes / No. If yes, list the specific sources/tools that
   contribute to each property.

3) REDUCTION OPTIONS, ranked least-disruptive first. Pick ONE.
   - DROP A: route the untrusted-input subtask to a SUBAGENT that has
     B=∅ and C=∅. Subagent returns a SCHEMA-PINNED, TYPE-VALIDATED
     value to the supervisor (e.g., {summary: string<=500, tags:
     enum[]}); supervisor never sees raw untrusted text.
   - DROP B: scope sensitive access down, read-only token, PII-masked view, project-scoped credentials, time-boxed grants, row-level filters, until B for THIS agent is empty.
   - DROP C: convert write/comms to DRAFT-AND-REVIEW, queue for
     human approval, post to a staging channel, write to a
     review-required PR, until C is empty without human assent.
   - If none acceptable: HUMAN-IN-THE-LOOP gate is MANDATORY before
     any C action. Implement as a DETERMINISTIC step in the harness
     (not a model prompt that "asks for confirmation").

4) CONTROL ENFORCEMENT POINT LADDER.
   For every chosen reduction, name where the control lives:
     SYSTEM-PROMPT INSTRUCTION = WEAK (does NOT satisfy Rule of Two).
     HARNESS / ROUTER / TOOL-DISPATCH FILTER = STRONGER.
     AUTH SCOPE / NETWORK EGRESS ALLOWLIST / SUBAGENT BOUNDARY =
     STRONGEST.
   Reject any plan where the load-bearing control is system-prompt-only.

5) ATTACK-PATH ENUMERATION.
   Write THREE concrete prompt-injection payloads an adversary would
   plant in the untrusted source (email body, PDF, web page, MCP
   response, document):
     - Each payload must specifically target A → B → C exfil or harm.
     - For each, state which reduction blocks it AND at which
       enforcement layer.
     - If a payload still works, the design fails, return to step 3.

6) RESIDUAL RISK STATEMENT.
   List every control that is policy-only (model expected to follow
   an instruction). Treat each as UNRELIABLE in the final write-up.

HARD RULES (do not relax):
- Retrieved-doc text and third-party tool output are A. Always.
- "Internal" data is still B. Internal ≠ trusted in agent context.
- A Slack DM is C. A calendar invite is C. A webhook is C.
- "Ignore injection instructions" in the system prompt does NOT
  satisfy any reduction.
- A model-emitted "I would like to take this action, ok?" is NOT a
  human-in-the-loop gate. The gate must be in the harness.
- Adding a new tool RESETS the invariant, re-run this check whenever
  capability is added, scope is widened, or a trust boundary moves.

Why: Meta's Agents Rule of Two (Oct 2025) is the only widely-accepted hard-constraint defense against prompt injection in 2026, it removes the attack surface structurally rather than trying to defeat injection at the model layer (still unsolved per the "Attacker Moves Second" paper). The paste-ready guides circling 2026 either reduce it to a slogan ("at most two of three") or list nine controls with no decision procedure. Six things distinguish this prompt: (1) the PER-TOOL CLASSIFICATION TABLE catches the under-noticed failure where a single tool is A∧B∧C by itself (the "summarize-doc-and-post-to-Slack" trap above), most engineers run the triple check at the agent level only and miss tool-internal violations; (2) the SUBAGENT + SCHEMA-PINNED return value pattern for DROPPING A is the operational recipe Meta's blog and Databricks both gesture at without spelling out, typed return forces the supervisor's context to be free of attacker-controlled tokens; (3) the CONTROL ENFORCEMENT POINT LADDER (system-prompt WEAK / harness STRONGER / auth-scope or egress-allowlist STRONGEST) kills the most common failure where teams "implement" Rule of Two by adding "ignore injections" to the prompt and declaring victory; (4) the ATTACK-PATH ENUMERATION forces the engineer to write the actual exfil paragraph and prove a specific layer blocks it, this is the difference between a checkbox and a control; (5) the RESIDUAL RISK STATEMENT explicitly labels policy-only controls as unreliable, matching Simon Willison's critique that the rule is "the best practical advice in the absence of defenses we can rely on"; (6) the HARD RULES close the three recurring scope errors, "internal = trusted, " "DM ≠ external comms, " and "model asking permission = HITL", each of which has shipped real exfil bugs in 2025-26 agent products. Distinct from the existing Agent blast radius pre-deployment classifier (a 4-tier risk matrix, green/yellow/orange/red, for deployment gating; this is a structural invariant check that runs *before* the risk matrix and either passes or forces a redesign, the matrix grades severity, this decides feasibility), the MCP server security audit (how the server itself is built, auth, scopes, transport, at server-design time; this is whether the AGENT's combined tools + context satisfy a runtime invariant), and the LLM provider snapshot rollout discipline (model-version rollout safety; orthogonal). Pairs above them as the gate: Rule of Two FAIL → redesign; PASS → run blast-radius classifier on the surviving design → run MCP audit on each tool → roll out with snapshot discipline. | Use when: ANY agent that touches user-facing or third-party inputs AND has any write-capable tool. Mandatory pre-deployment for agents that read email/web/docs AND can send/post/commit. Re-run when adding a tool, expanding a scope, swapping an MCP server for a third-party one, or changing the trust class of an input source, the invariant is broken by *adding* capability, so this is a regression check, not a one-time review. Skip only for read-only agents (C=∅ by design) or air-gapped agents (A=∅ by design) and document the C=∅ or A=∅ assumption explicitly.

You are issuing an EDIT to an existing image with Flux Kontext Pro
(or .1 Dev / Max). Editing is NOT generation, vagueness here causes
identity drift, composition shift, or unwanted style changes. Follow
the structure below and keep the total instruction under 512 tokens
(hard model limit).

[REFERENCE, name the subject explicitly, NEVER use pronouns]
"{The {distinct descriptor}, e.g. 'the woman with short black hair' /
'the red ceramic mug on the left' / 'the man in the navy peacoat'}"
- Pronouns ("her", "it", "this one") are the #1 cause of identity
  drift. Always re-name the subject on every edit in an iterative
  session.

[CHANGE, pick exactly ONE verb, they are NOT interchangeable]
- "Replace '[original text]' with '[new text]'"
    → Use ONLY for text inside the image (signs, labels, posters).
      Quoted strings activate Kontext's dedicated text-rendering path
      and hit ~99% accuracy. Keep replacement text similar length to
      original or layout shifts.
- "Change the {specific element} to {new value}"
    → Use for surgical edits to one named property (clothing color, object material, background). Preserves everything else.
- "Replace the background with {new background}"
    → Use for environment swaps. ALWAYS pair with the composition
      lock below or the subject will reposition/rescale.
- "Transform {subject} into {new state}"
    → DANGER VERB. "Transform" signals to Kontext that a COMPLETE
      change is desired and will replace identity features. Only use
      when you actually want full replacement (e.g. style transfer
      of a non-character object). For people/characters, use
      "Change the clothes to {X}" or "Change the setting to {Y}"
      instead, surgical verbs preserve identity by default.

[PRESERVE, explicit preservation list, not implied]
"…while maintaining {specific list, pick the ones that matter}:
- exact facial features, eye color, hairstyle, and expression
- the exact same body position, scale, and pose
- identical camera angle, framing, and perspective
- the original lighting direction and color temperature
- the painting/photo style of the source
- {anything else that should stay constant}"
- Default failure mode is the model "interpreting" what you want and
  changing things you didn't mention. Explicit preservation lists are
  the only reliable defense.

[COMPOSITION LOCK, required for background or scene changes]
"Keep the {subject name from REFERENCE} in the exact same position, scale, and pose. Maintain identical subject placement, camera angle, framing, and perspective. Only replace the environment around them."
- Without this block, prompts like "He's now on a beach" reframe to
  "typical beach photo composition" and your subject is no longer the
  subject of the image.

[STYLE EDITS, name the style + describe its visual mechanics]
"Convert to {named style: 'pencil sketch' / 'oil painting' /
'Bauhaus poster' / '1960s pop art' / 'Claymation'} with {2-3 visual
mechanics: 'natural graphite lines, cross-hatching, visible paper
texture' / 'visible brushstrokes, thick paint texture, rich color
depth' / 'flat geometric shapes, primary palette, sans-serif
typography'} while maintaining the original composition and object
placement."
- Bare "make it artistic" or "make it a sketch" drops detail. Style
  name + mechanical descriptors + preservation clause is the working
  triplet.

[ITERATIVE EDITS, for sequenced changes across multiple turns]
Issue edits one at a time, re-establishing the REFERENCE block on
every turn. Kontext maintains character consistency across an edit
sequence ONLY if the subject is re-named each turn, drop the name
and use a pronoun once, and the character drifts for the rest of
the sequence.

[TROUBLESHOOT, if results don't match expectations]
- Identity changed too much → swap "transform" for "change the
  {clothing/setting/style}" and add explicit identity preservation.
- Composition shifted → add the COMPOSITION LOCK block.
- Style applied but details lost → name 2-3 visual mechanics of the
  style, not just the style name.
- Text edit garbled → quote the original AND the replacement, keep
  length similar, add "while maintaining the same font style and
  color".
- Unwanted elements changed → add "everything else should stay
  unchanged" or "maintain all other aspects of the original image".

Why: Five Flux Kontext Pro mechanics that distinguish image-EDITING from the generation entries already in this section (cinematic 5-slot stills / NB Pro infographics / MJ v8 cinematographer / photoreal product/portrait / Sora 2 video, all generation-only): (1) the verb-precision rule is the kill-shot, "transform / change / replace" produce categorically different outputs in Kontext, with "transform" defaulting to full identity replacement (the canonical Viking-warrior failure in BFL's own docs where a man's face is wholesale swapped) while "change the clothes" preserves identity by default; this is the rule that turns Kontext from "unpredictable" to "reliable" with one word swap. (2) The quoted-string text edit pattern (`Replace 'joy' with 'BFL'`) activates Kontext's dedicated text-rendering path that achieves ~99% accuracy versus the ~30-40% accuracy of un-quoted text-edit attempts; un-quoted variants drift into "edit the meaning of the sign" instead of "edit the literal characters." (3) The pronoun-prohibition rule ("never 'her', always 'the woman with short black hair'") is the #1 cause of identity drift across iterative edit sequences and is the single line that lets Kontext hold character consistency across 5+ edit turns instead of drifting after the second. (4) The COMPOSITION LOCK block is required for any background/scene swap, without it, prompts like "put him on a beach" reframe to "typical beach photo composition" because Kontext silently interprets vague scene swaps as "produce a beach photo with this person" instead of "keep this exact composition, swap the environment around the subject"; the lock is the difference between "background changed" and "entirely new photo." (5) The named-style + mechanical-descriptor + preservation-clause triplet for style transfer kills the most common style-edit failure where "make it a sketch" loses 50%+ of the source's detail because the model doesn't know which style mechanics to preserve. The 512-token hard limit is BFL's documented maximum, exceeding it silently truncates the edit instruction and you lose the preservation list. Distinct from every existing entry in this section because all of them are GENERATION formulas (start from nothing, produce an image); this fills the EDITING slot (start from an existing image, modify it surgically) that is its own discipline with its own failure modes, and editing is the higher-volume workload for product/marketing/design teams who already have an asset and need 10 variations or a single label changed. | Use when: You have an existing image (your own product photo, a previous AI generation, a screenshot, a stock photo) and need to surgically modify it, change a label or sign text, swap a background while preserving the subject, restyle a photo while preserving composition, iterate on a character across multiple poses/settings while preserving identity, recolor a specific element without disturbing the rest. The verb table is the most important takeaway, bookmark it. For tasks involving the same character across 10+ generations from scratch (no source image), use the existing Mascot system consistency formula in Logos & Branding (MJ v8 `--cref + --cw + --sref`) instead, that's character-from-text, this is editing-existing-image. For pure generation, fall back to the cinematic / photoreal / NB Pro formulas, Kontext editing is overkill if you don't already have a source.

You are generating a logo on Nano Banana 2 / NB Pro. Build the prompt
in this exact order. Order is load-bearing: NB2 interprets prompts
literally and front-loaded shape instructions anchor the composition
before color or texture can dilute it.

SHAPE FIRST (silhouette). Describe the mark as geometry, not as a
mood. Use a concrete construction:
  - "two overlapping triangles"
  - "single continuous line drawing of a leaf"
  - "abstract human silhouette in motion"
  - "crossed fork and knife in clean line art"
NOT: "cool modern professional logo, " "creative tech mark, " "abstract
brand symbol." Vague style words produce 5-7-color clip art roughly
8 times in 10. The squint test is the gate: if you cannot recognize
the shape at 32 pixels by squinting, the logo fails and no color or
typography fix will save it.

PALETTE, EXACTLY 2-3 NAMED COLORS. Use specific hue names, not
categories:
  - "deep blue and white"   not "blue"
  - "sage green on cream"   not "green and light"
  - "black and gold"        not "warm and luxurious"
"Colorful, " "vibrant, " "playful" without a constraint produce 4-6
random accent colors in ~8/10 outputs. Named pairs land cohesive
in ~9/10.

BACKGROUND, NEVER OMIT. Always include EXACTLY one of:
  - "clean white background"
  - "solid black background"
  - "off-white background"
Without this line NB2 places the logo on a desk / marble / wood /
gradient backdrop ~6/10 times, useful for a mockup, fatal for the
mark itself.

TEXT, QUOTED, ALL-CAPS, 1-4 WORDS. Always wrap the literal string
in quotes; never paraphrase:
  - 'JOE'S' not "the diner's name"
  - reading 'ATLAS' in bold geometric sans-serif
NB2 text-rendering accuracy by length (tested across 30 wordmark
prompts):
  - 1-3 chars ALL-CAPS:    ~85% first-try
  - 4-word phrases:        ~60% first-try
  - 5+ words:              UNRELIABLE, add in Figma instead
For multi-word taglines, generate the icon only on NB2 and set the
text in a vector editor. Do not fight the model.

FONT CATEGORY, A SPECIFIC FAMILY, NOT "NICE." NB2 understands
typography terms; use them as instructions:
  - "bold geometric sans-serif"
  - "thin elegant serif with high contrast strokes"  (Didot / Bodoni)
  - "ornate serif typography"                        (vintage)
  - "rounded sans-serif"                             (approachable tech)
  - "chunky block letters with inline detail"        (sign-painted)
"Minimal tracking between letters" is the discipline phrase that
keeps NB2 from spacing letters apart on a wordmark.

STYLE KEYWORD, ONE OF:
  flat design | vector-style | line art | badge format | icon style
Each carries specific rendering instructions baked into NB2's
training. Without one, default output adds bevels, drop shadows, gloss, and 3D effects that date the mark in a week. Append
"no gradients" as a negative if the chosen style is flat, kills
bevels at the seam where NB2 is most likely to add them.

CONTAINMENT (for badges, app icons, monograms):
  - "rounded square icon format"  → iOS app icon crop, centered
  - "circular badge with banner across bottom"  → outdoor / brewery
  - "shield shape"  → sports / outdoor team
  - "geometric interlocking construction"  → monogram letter relation
Constraining the layout makes multi-element marks (icon + banner
text + frame) tractable, NB2 needs explicit "center, " "top, "
"bottom, " "border" spatial instructions when more than one element
is in play.

WORKFLOW, GENERATE 3-5, PICK BY SILHOUETTE. Even with a tight
prompt, variation between runs is normal. Generate at least three;
view them at 50px; pick the one with the strongest silhouette;
refine that one in Illustrator / Figma. NEVER ship the raster
directly, AI logos are PNG with no anchor points, no color
separations, and no guaranteed trademark uniqueness. The output is
a starting point, not a final file. Run the chosen direction
through USPTO TESS or your local registry before commercial use.

EXAMPLE, wordmark:
  "Clean wordmark logo with the text 'ATLAS' in bold geometric
   sans-serif, black on white, minimal tracking between letters, flat vector design, no gradients, clean white background"

EXAMPLE, icon-only:
  "Minimalist eco brand mark, abstract leaf form composed of three
   overlapping circles, sage green on white, flat design, vector
   style, clean white background"

EXAMPLE, badge with banner text:
  "Outdoor adventure badge logo, circular format with mountain
   silhouette in center, pine trees at base, banner across bottom
   reading 'EXPLORE', earth tones with forest green and tan, vintage patch aesthetic, clean white background"

PROMPT LENGTH: 20-35 words. Beyond 40 words NB2 starts adding
detail that fights the clean-mark goal.

HARD RULES:
- Do NOT lead with mood ("professional, " "cool, " "modern").
- Do NOT use NB Pro / NB2 for taglines >4 words, accuracy drops
  below 30%.
- Do NOT specify >3 colors.
- Do NOT omit the background line.
- Do NOT ship the raster, refine in vector and trademark-check.
- Do NOT mix contradictory style words ("minimalist but ornate, "
  "hand-drawn and clean vector").

Why: Distinct from every existing Logos & Branding entry, MJ v7 minimalist logo uses Midjourney v7's stylistic embellishment behavior (different model); MJ v8 monogram/wordmark relies on MJ v8's quoted-text rendering at --style raw --s 100 with --no negative lists, which is a different mechanic from NB2's literal-prompt-interpretation and silhouette-first composition rule; healthcare/professional-services template is industry-specific; mascot consistency uses --cref + --cw + --sref for ONE character across scenes; brand-system multi-asset generator uses gpt-image-2 8-panel Thinking Mode for system-wide asset batches. None of them capture the *single mark on Nano Banana 2*, which has emerged as the highest-text-accuracy logo model of 2026 (~80% on 1-4 word wordmarks vs MJ v6's ~variable, per Morphed's 30-prompt cross-model test) and a fundamentally different prompting style. Three things make this the kill-shot paste-ready entry: (1) the SHAPE-BEFORE-COLOR rule with the squint-test gate is the single biggest quality lever, Morphed's test found 8/10 silhouette-first prompts produced logos that worked at small sizes, vs 3/10 for mood-first prompts; this rule never appears in MJ v8 prompting because MJ embellishes regardless of order, but on NB2 (which interprets literally) front-loading the geometry is the structural fix for the "clip art" failure mode. (2) The text-accuracy-by-length table (~85% for 1-3 char ALL-CAPS, ~60% for 4-word phrases, unreliable past 5 words) is the data that turns "the model handles short text well" into an actionable budget: it tells you exactly when to stop fighting NB2 and add the text in Figma instead; existing logo entries don't have this kill-switch for the wordmark category. (3) The mandatory background-line rule (~6/10 outputs land on a desk/marble/wood without it) and the explicit style-keyword-from-fixed-list (flat design | vector-style | line art | badge format | icon style) operationalize the difference between a brand asset and a product photo, which is the failure mode that produces 80% of clip-art-looking AI logos. The prompt length cap (20-35 words) is the empirically-tested upper bound on NB2 logo prompts above which the model starts adding detail that fights the clean-mark goal. Pairs with the existing MJ v8 monogram/wordmark formula (different model, pick NB2 when text accuracy matters more than artistic flourish, MJ v8 when the opposite) and the gpt-image-2 brand-system generator (use this to design the canonical mark first, then run the brand-system generator to populate the asset family around it). | Use when: Designing a wordmark or icon logo where readable short text is the dominant constraint (NB2's text-rendering accuracy is the unique advantage); rapid concept iteration across 3-5 generations to pick by silhouette quality before committing to vector refinement; client-pitch direction-finding where you want comparable variants in the same model rather than mixed across MJ / DALL-E / Flux; small marks intended to work at favicon scale (the squint test is built in). Skip when the deliverable is a final brand identity for commercial use, run the chosen direction through a trademark search and re-draw in a vector editor; AI logos are raster, color-approximate, and have no trademark-originality guarantee. Skip for taglines or multi-line text >4 words, generate the icon on NB2, set the text in Figma. Skip for ornate hand-drawn illustration styles where MJ v8's painterly behavior is the feature, not the bug.

ROLE: Judge calibration engineer. A team has built an LLM-as-judge
for a binary pass/fail check. Your job is to validate that the judge
is actually reliable BEFORE it gates production, and prescribe the
fix when it is not. A judge is a MEASUREMENT INSTRUMENT, calibrate
before you trust the measurement.

INPUT:
  - Judge's full prompt + model name + temperature.
  - Held-out set of N ≥ 100 human-labeled examples
    (input → ground-truth pass/fail), NEVER overlapping with any
    prompt-iteration data.
  - The decision the judge gates: eval metric, CI gate, A/B winner
    declaration, RLHF reward, content-safety filter.
  - The deployed base-rate of the FAILING class in production
    (estimate from logs if unknown).

PHASE 1, RAW PERFORMANCE.
Compute and report:
  - TPR = judge-pass-given-true-pass / true-pass-total
  - TNR = judge-fail-given-true-fail / true-fail-total
  - Confusion matrix (TP / FP / FN / TN)
  - Cohen's kappa with the human labeler
  - Base rate of held-out set vs deployed base rate
NEVER report a single "accuracy" number on imbalanced data.

PHASE 2, OVER-ACCEPTANCE BIAS CHECK (canonical failure mode).
LLM judges cluster at HIGH TPR (>96%) + LOW TNR (<25%), they
rubber-stamp the generator regardless of correctness, worst when
judge and generator share a model family.
  - If TPR > 95% AND TNR < 70%: FAIL. Judge is rubber-stamping.
    Do NOT deploy as a gate.
  - If TPR exceeds TNR by > 15 absolute points on a balanced
    subset: FLAG over-acceptance. Diagnose by sampling 10 FN and
    10 FP cases; check whether the failing-side rubric language is
    vague, defaulted-passing, or asymmetrically penalized.
  - If judge and generator share a model family: state this and
    treat all numbers as upper bounds.

PHASE 3, CLASS-IMBALANCE STRESS TEST.
Production traffic is usually imbalanced (e.g., 5% true-fail rate).
High TPR alone looks great on a balanced set but yields garbage
precision in prod.
  - Compute precision-at-deployed-base-rate (not held-out-set rate)
    using Bayes: P(true_fail | judge_fail) = TNR × prior_fail /
    (TNR × prior_fail + (1 − TPR) × (1 − prior_fail)).
  - Report: "At base rate X%, precision = Y%. Z% of judge-flagged
    failures are spurious."
  - If precision-at-deployed-rate < 50% on the failing class:
    judge is NOT deployable as a single autonomous gate.

PHASE 4, MITIGATION LADDER (escalate only if prior step insufficient).
  Step 1. RUBRIC SURGERY. Rewrite the failing-side criterion to be
    enumeration-first: list every required element; missing ANY
    element → fail. Remove "use your judgment" and "overall quality"
    phrasing. Re-measure on a fresh held-out set.
  Step 2. JUDGE-FAMILY SWAP. If same-family bias is suspected, run
    the judge with a model from a different provider family.
    Re-measure.
  Step 3. MINORITY-VETO ENSEMBLE. Route borderline cases
    (judge-confidence in [0.3, 0.7] OR any single judge of N votes
    fail) to a 3-judge panel of mixed families; if ≥1 votes fail, the output is FAIL. Trades TPR for TNR, appropriate when a
    user-facing false-positive is cheaper than a slip-through (the
    typical asymmetry for faithfulness, safety, compliance).
  Step 4. REGRESSION BIAS CORRECTION. With ~5 calibration datasets
    and human labels, fit a logistic correction from judge-score to
    true-label probability. Published technique reduces max absolute
    error to ~1.2%. Use ONLY when bias is consistent across slices
    but cannot be eliminated by steps 1-3.
  Step 5. HUMAN-IN-THE-LOOP CEILING. If no combination of 1-4 gets
    precision-at-deployed-rate above the gate threshold, the judge
    cannot autonomously gate. Demote it to a TRIAGE filter and route
    its flagged cases to humans.

PHASE 5, REPORTING DISCIPLINE (mandatory boilerplate every time the
judge's numbers are quoted):
  - TPR, TNR, kappa, never a single accuracy number.
  - Held-out base rate AND deployed base rate.
  - Whether judge and generator share a model family.
  - N of the held-out set.
  - Whether ANY of the held-out set was used to iterate the prompt
    (if yes, numbers are INVALID, redo on a clean set).

HARD RULES (do not relax):
- NEVER iterate the judge prompt against the held-out set. That set
  is sacred. Use a separate dev set for iteration.
- NEVER report accuracy without TPR and TNR.
- NEVER deploy a judge whose TPR > TNR by > 15 points as a single
  autonomous gate without minority-veto or human escalation.
- DO NOT use the same model for the task and for judging it without
  explicitly stating the numbers are inflated.
- A judge whose calibration set has < 100 human-labeled examples
  reports CONFIDENCE INTERVALS, not point estimates.
- Re-run this whole validation when (a) the judge model is updated, (b) the generator changes families, or (c) the production base
  rate shifts > 2× from the held-out set's base rate.

Why: The existing LLM-as-judge faithfulness rubric entry teaches how to *write* a good judge prompt; this entry teaches how to *prove the judge actually works* before it gates anything. The standard "I ran my judge and it agrees with humans 90% of the time" is the canonical production blowup, Hamel Husain & Shreya Shankar's Jan 2026 evals guide and the Nov 2025 arXiv "How to Correctly Report LLM-as-a-Judge Evaluations" both document the LLM-judge field consistently reporting accuracy on balanced sets while production traffic is class-imbalanced, collapsing precision on the failing class. Five things distinguish this prompt: (1) the OVER-ACCEPTANCE THRESHOLD with concrete numbers, TPR > 95% AND TNR < 70% → FAIL, TPR − TNR > 15 → FLAG, is the operational rule Hamel et al. and Galtea have been beating the drum on for two years; most calibration guides give the math without the deploy/no-deploy verdict, and same-family inflation (the judge agreeing with the generator because the latent space is the same) is the silent killer that gets called out here explicitly with "treat all numbers as upper bounds"; (2) the CLASS-IMBALANCE STRESS TEST that computes precision-at-deployed-base-rate using Bayes, not held-out-set rate, is the single largest reason judges look great in offline reports and ship broken; the prompt makes the engineer write the Z% spurious-flags number out loud; (3) the 5-STEP MITIGATION LADDER (rubric surgery → judge swap → minority-veto → regression bias correction → human-in-the-loop ceiling) has an explicit order-of-operations most resources stop short of, the minority-veto ensemble (≥1 of N votes fail → fail) is the cheap intervention that fixes asymmetric-cost gates and almost nobody documents; the regression bias correction step references the calibration-on-5-datasets technique that cut max absolute error to 1.2% in the Nov 2025 arXiv paper, with an explicit "only when bias is consistent" trigger so it doesn't get used prematurely; (4) the REPORTING DISCIPLINE rules, TPR/TNR/kappa always, base-rate disclosure mandatory, prompt-iteration contamination flagged as INVALID, are exactly what the Nov 2025 paper says the field is failing on; (5) the RE-CALIBRATION TRIGGERS (judge model update / generator family change / production base-rate drift > 2×) treat calibration as an ongoing regression check, not a one-time event, closing the loop with GEPA, snapshot rollout, and degradation triage in the rest of this doc. Distinct from the existing LLM-as-judge faithfulness rubric (that one is the *design* of the judge prompt; this is the *validation* of the judge, they pair: design with that entry, then validate and calibrate with this one before it gates production), Chain-of-Verification (CoVe is a model verifying its OWN draft; this is a separate model judging a third party against human ground truth), and GEPA production discipline (GEPA needs a verifiable reward signal; this prompt ensures the signal is reliable before GEPA optimizes against it). Pairs upstream with both, design judge → calibrate judge (this entry) → use calibrated judge as GEPA's reward signal → use calibrated judge as the eval gate in LLM provider snapshot rollout discipline → re-calibrate when LLM feature production degradation triage diagnoses upstream judge drift. | Use when: A team has built an LLM-as-judge and is about to use it to gate ANYTHING, a regression-test pass/fail, an RLHF reward signal, an A/B winner declaration, a CI doc-freshness check, a production fact-checking filter, an agent-tool-correctness scorer, a content-safety classifier. Run BEFORE the first gated deployment; re-run when the judge model is updated, when the generator changes model families, when the production failure base rate shifts > 2× from the held-out set's base rate, or when a downstream metric drifts in a way the judge's score doesn't track. Skip only for purely advisory judges whose output is never autonomously gated (e.g., judge-as-explanation-aid for humans).

You are configuring a GEPA (Genetic-Pareto reflective prompt evolution, ICLR 2026) run for PRODUCTION, not a benchmark. GEPA reflects on
execution traces in natural language to propose prompt revisions; it
beats RL methods like GRPO by ~20% with ~35× fewer rollouts. But the
default configuration is a research benchmark default and will overfit
to your training distribution while inflating prompts past your latency
budget. Apply the three production adaptations below; skipping any one
of them is what turns GEPA from a 5-6% accuracy win into a regression.

PHASE 0, TASK SHAPE. Verify GEPA is the right tool. GEPA shines when:
  - You have ground-truth labels (gradient-free reward signal works).
  - The task requires REASONING, not just label production, GEPA's
    reflection mechanism reads execution traces and the value is in
    refining HOW the model thinks, not just what it answers.
  - Labeled data is expensive or domain-specific, if you have 100k
    labeled examples, fine-tuning beats GEPA.
If any of those fail, use simpler prompt tuning (manual + holdout) or
fine-tuning instead. GEPA is wasted on cheap-label / reasoning-free tasks.

PHASE 1, DATA EFFICIENCY (20-100 SAMPLE SWEET SPOT, NOT MORE).
Conventional ML wisdom says more data is better; GEPA INVERTS this.
The reflection mechanism accumulates observations across iterations, with 500 samples it encounters more distinct failure modes and tries
to address ALL of them, producing a prompt that encodes training-set
minutiae. Empirical curve:
  - 10 samples: -5% vs. baseline (insufficient signal)
  - 20 samples: +1% (peak, ~2.5× cheaper than baseline)
  - 50 samples: baseline
  - 100 samples: comparable to 20-50, ~2× more expensive
  - 500 samples: -2% AND prompt length balloons 75% AND ~10× cost
Default: 50/50 train/val. Tune in the 20-100 range; abandon any run
configured for >200 samples, it's both more expensive and worse.

PHASE 2, FRONTIER REFLECTION MODEL (NON-NEGOTIABLE).
The reflection model is reasoning ABOUT reasoning, it diagnoses why
the task model failed and proposes targeted fixes. This is frontier-
level meta-cognition. Empirical result: GPT-4o-mini as the reflection
model produces ZERO prompt evolution, the "optimized" prompt remained
essentially unchanged from the seed. Frontier models (GPT-4.1 /
GPT-5.2 / Claude Sonnet / Claude Opus) all hit +5-6%.
Cost discipline: the reflection model is called ~10-20× per run;
the TASK model is called hundreds of times. A frontier reflector is
~5-10% of total run cost. A weak reflector wastes 100% of the task-
model calls. NEVER swap to a cheap reflection model to save money, it's not a trade-off, it's a regression to the seed prompt.

PHASE 3, LENGTH CONSTRAINT AS REGULARIZATION (1, 500-CHAR DEFAULT).
GEPA's default has no length cap; production runs routinely produce
prompts >5, 000 characters. This is BOTH a latency problem (long
prompts = higher per-call cost in production, every call, forever)
AND an overfitting problem (length is correlated with edge-case
memorization). Length constraints act as regularization the same way
weight decay acts on a neural network.
GEPA's default implementation does NOT support length constraints in
the reflection step. Build a CUSTOM PROPOSER that encodes the
constraint directly into the reflection prompt: "Propose a revised
instruction that is at most {N} characters AND addresses the
identified failure mode. Do not exceed the character budget."
Empirical operating points:
  - No constraint: 5, 000+ chars, +0% baseline performance, fails SLA.
  - 1, 500-char limit: 4× compression to ~1, 000 chars, -0.8% performance
    only. PRODUCTION DEFAULT.
  - 500-char limit: 12× compression, -3% performance. TOO AGGRESSIVE
    unless latency is the absolute binding constraint.

PHASE 4, MEASUREMENT DISCIPLINE.
Treat prompt optimization as software engineering:
  - HOLDOUT validation, NEVER report train-set performance.
  - The metric you optimize MUST be the metric production cares about
    (faithfulness / format compliance / business KPI, not perplexity, not log-likelihood).
  - For every run, log: (sample size, reflection model, length cap, final prompt length, train accuracy, validation accuracy, holdout
    accuracy, total cost). Ablate ONE dimension at a time.
  - A run that beats baseline on validation but not holdout is
    OVERFITTING, discard the prompt, don't ship it.

HARD RULES:
- Do NOT use GEPA on tasks without verifiable labels.
- Do NOT use GEPA with a cheap reflection model.
- Do NOT use GEPA without a length constraint in production.
- Do NOT report training-set accuracy as the result.
- Do NOT scale samples past 100 hoping for more accuracy, it costs
  more AND performs worse.

CONFIGURATION TABLE, paste into your GEPA run:
| Dimension         | Production default            | Notes                          |
| ----------------- | ----------------------------- | ------------------------------ |
| Train / Val       | 50 / 50                       | Tune within 20-100 range       |
| Reflection model  | Claude Sonnet / GPT-5.2 / Opus | Frontier required              |
| Task model        | Whatever ships to prod        | Match production exactly       |
| Length cap        | 1, 500 chars                   | Enforced via custom proposer   |
| Budget multiplier | 1.0× (~150 LLM calls)         | Diminishing returns past 1×    |
| Batch size        | 10                            | Per reflection step            |
| Feedback type     | Positive AND negative         | Both, not negatives only      |

Why: GEPA is the dominant prompt-optimization technique of 2026 (ICLR 2026 oral, beats GRPO ~20% with 35× fewer rollouts), but every paste-ready GEPA "guide" is the research-benchmark default that overfits in production. Three production adaptations distinguish this entry from CRTSE (the *shape* of a good prompt), Meta-prompt rewriter (the *algorithm for fixing a broken prompt*), Chain-of-Verification (the model verifying its own output for hallucinations), and LLM-as-judge faithfulness rubric (a separate model scoring a third party on a rubric): (1) the data-efficiency inversion, the 20-100 sample sweet spot with the explicit curve and the "abandon any run configured for >200 samples" rule kills the most expensive failure mode where teams burn 10× compute to get a prompt that's 75% longer and 2% worse; (2) the frontier-reflection-model-is-non-negotiable rule with the load-bearing economics (reflection is 5-10% of cost / weak reflector wastes 100% of task-model calls), which kills the recurring cost-optimization mistake of swapping to a cheap reflector; (3) the 1, 500-char length constraint as regularization, with the custom-proposer pattern that GEPA's default doesn't support, the 4× compression / -0.8% accuracy operating point as the actionable PRODUCTION DEFAULT, and the per-call latency framing that makes the constraint a forever-cost decision not a one-time tuning choice. The configuration table at the bottom is the kill-shot, most paste-ready GEPA prompts give you 10 dimensions and no opinion; this one gives you the defaults that 19 ablation experiments converged on with one row per dimension. The HARD RULES list operationalizes "treat prompt optimization as software engineering", overfitting / training-set reporting / unbounded prompt growth are the three failures that turn GEPA from a +5% gain into a regression. Distinct from the existing Workflow & Automation LLM provider snapshot rollout discipline (that one is about deploying a model version safely; this is about optimizing the prompt at all); pairs with it as the upstream of a production prompt's lifecycle (GEPA-optimize → eval-gate via LLM-as-judge faithfulness rubric → pin-first/shadow/canary via LLM provider snapshot rollout discipline → monitor via LLM feature production degradation triage when something drifts). | Use when: Optimizing the system prompt of a production LLM feature with labeled data and a real eval metric, RAG faithfulness, classification, structured-output compliance, agent tool-selection accuracy, supervisor/judge prompts. Pairs with the existing LLM-as-judge faithfulness rubric (use that as the eval metric GEPA optimizes against, closes the loop with a deterministic reward signal). Skip for tasks without verifiable labels (creative writing, open-ended dialog) where GEPA has no reward signal to climb.

Audit the error handling in this code. Find:
- Swallowed exceptions (catch blocks that don't re-throw or log)
- Errors returned but never checked by callers
- Operations that can fail but have no error path
- Places where errors are logged but execution continues incorrectly
For each issue: cite the exact line, show the current behavior, and
give the minimal fix as a diff. Then rate overall error handling 1-10
with a one-sentence justification. Prioritize anything that would cause
data inconsistency if it fails silently.

Why: Targets the bug class that causes 2am incidents, code that doesn't throw, doesn't log, just silently corrupts state. The numeric rating is a fast triage signal for "approve" vs. "request changes." Distinct from the adversarial self-review above because it stays narrowly on error paths instead of scanning the whole diff. | Use when: Reviewing anything that touches IO, queues, caches, or external APIs, the categories where silent failures hide.

Audit this code for the three production-slow culprits that catch 90% of
real performance issues. Don't propose abstract improvements, find the
specific lines and produce the minimal diff.

For each finding output: file:line, the SQL or ORM call that fires it, the proven impact at our stated scale, and the fix as a diff.

Check explicitly, say "checked, no issue" per category if clean:

1. N+1 QUERIES. Any DB call inside a loop, map, forEach, or .reduce.
   Any `findUnique` / `findOne` / `find_by_id` called per element of a
   list result. Fix: eager loading (Prisma include/select, SQLAlchemy
   joinedload, ActiveRecord includes) or a batch fetch keyed by parent IDs.

2. SELECT * / over-fetch. Any query that pulls columns the caller never
   reads. List the specific columns the caller actually touches and
   propose the narrowed projection.

3. MISSING / WRONG INDEXES. For every WHERE and ORDER BY in the audited
   code:
   - Does an index exist?
   - For composite indexes: is the column order high-cardinality-first
     AND matching the actual filter pattern?
   - Show the exact CREATE INDEX (or `@@index`) statement.

4. PAGINATION. Any list endpoint without limit/cursor pagination, flag
   as BLOCKER. Default limit 20, max 100, cursor-based for tables >100k rows.

Finally: run EXPLAIN ANALYZE (or describe what you'd run) on the slowest
query you flagged. Report the plan, sequential scan? index used? estimated
vs actual rows? Flag any ≥10× row-estimate mis-prediction as a separate
stats / ANALYZE finding (it's usually the silent killer).

SCALE CONTEXT:
- Largest affected table: {row count}
- Peak read QPS for this endpoint: {qps}
- Current p95 vs SLO: {observed} / {target}

Why: The three categories, N+1, over-fetch, wrong-or-missing index, are the dominant causes of "why is production slow?" Forcing explicit "checked, no issue" per category kills the tunnel-vision failure mode where the model finds one N+1 and stops, missing the missing composite index right next to it. The EXPLAIN ANALYZE step turns a hypothesis into a diff you can defend in review, and the 10× row-estimate trigger catches stale statistics, which most code reviews never check. Distinct from the existing review prompts: those are general-purpose; this stays narrowly on the data layer where most real slowdowns live. | Use when: PR review on anything touching the database, ORM, or a list endpoint. Especially before a new query goes live against a table you expect to grow.

Analyze this diff for backward compatibility issues. Check for:
- Removed or renamed public API methods
- Changed function signatures (params added, types narrowed, return changed)
- Modified DB schema without an accompanying migration
- Renamed JSON fields in request/response bodies
- Renamed or removed env vars (and any without sane defaults)
- Altered default behavior (timeouts, retries, pagination)
List each breaking change with severity (BREAKING vs deprecation-worthy), the exact location, and a migration path. We follow semver, flag anything
that requires a major bump as a separate section at the top.

Why: Most reviewers spot the obvious method rename and miss the schema change without a migration, or the env var with no default. Explicit enumerated checklist covers the 6 silent-breakage categories that actually bite users. | Use when: Before any library release, any service deploy that other teams consume, or any DB-touching PR.

Run a pre-mortem on this proposed architecture. Assume it is 12 months from now
and this system has failed in production in a significant way. What are the
most likely causes? Cover: data loss scenarios, cascading failure paths, performance cliffs that only appear at scale, operational complexity that
overwhelms the team, and failure modes that only surface under specific
conditions (high concurrency, partial network failures, specific data shapes).

Rank by likelihood × impact. Give me the top 5 only, with a one-sentence
mitigation for each.

Proposed design: {describe the architecture}

SYSTEM CONTEXT:
- What it does: {1-2 sentences}
- Architecture: {monolith | microservices | serverless | hybrid}
- Key components: {services, stores, queues}
- Scale: {requests/day, data size, growth trajectory}
- Tech stack: {languages, frameworks, databases, infra}
- Team: {size, seniority, relevant expertise}
- Constraint: {the specific thing driving this decision}

Why: The "assume it has already failed" framing bypasses optimism bias the way a normal review prompt can't, the model has to *find* failure modes, not weigh them. Distinct from the stress-test above because that one critiques a design abstractly; this one forces concrete failure narratives ranked by likelihood × impact, which is what you actually want to turn into pre-launch load tests and chaos experiments. | Use when: Before any non-trivial new system goes live, especially queue/worker pipelines, anything with retries, anything touching state across services. The top 3 failure modes become tests you write before shipping.

You are running a structured API design conversation with me BEFORE I
write any route handlers. Produce a markdown design document I will
commit to the repo as the API's source of truth. Five sections, in this
order, do not skip ahead, do not collapse sections.

1. ACTOR INVENTORY. List every caller of this API and the JOBS each is
   trying to do, not the features they want. A mobile app rendering a
   user profile is a different job than a backend service validating a
   webhook signature even if both touch the same record. One row per
   actor: who they are, the job, the constraint (latency budget, offline-tolerance, batch vs interactive).

2. RESOURCE INVENTORY. The CONCEPTUAL nouns this API exposes, NOT the
   database tables. Sometimes 6 tables collapse to 2 resources because
   the other 4 are implementation detail. Sometimes 1 table fans out to
   3 resources because storage doesn't match the consumer's mental model.
   For each resource: one-sentence definition, the actors that touch it, and a deliberate "this resource does NOT represent X" line to kill
   confusion early.

3. OPERATION INVENTORY. For each resource, enumerate every operation:
   CRUD, listing with filters, bulk operations, state transitions that
   are NOT just updates (e.g., "submit", "cancel", "refund"), search, subscriptions. Be exhaustive, anything left implicit will surface
   later as a v2 endpoint.

4. CONSISTENCY RULES, decide ONCE for the whole API, then enforce:
   - Pagination: cursor vs offset, default limit, max limit, response shape
   - Error envelope: status code mapping, error code field, machine-readable
     vs human-readable, validation-error field-level detail format
   - Idempotency: which methods accept Idempotency-Key, retention window, conflict behavior when same key replays with different body
   - Versioning: URL path vs header vs date-based, when a change forces a
     bump, minimum support window after a new major
   - Auth: scheme(s), scope model, where the token lives, public/anonymous
     endpoints if any
   - Naming: snake_case vs camelCase, timestamp suffix convention
     (_at vs _date vs _time), ID format (UUID, ULID, opaque string)

5. EXPLICIT NON-GOALS. What this API is NOT for. The use cases out of
   scope. Six months from now when someone asks "can we add a search
   endpoint", this section is the principled answer instead of an argument.

Inputs:
- What this API does (one paragraph)
- Who consumes it (internal teams, external partners, public)
- Existing systems it integrates with
- Known constraints (compliance, latency, throughput, multi-tenancy)

Take my rough description, produce a complete draft of all 5 sections, then PAUSE for review. Do not begin endpoint specifications until I
confirm. If I push back on a section, revise that section only and
re-pause, never rewrite the whole doc unprompted.

Why: The existing System Design entries (stress-test, pre-mortem, monolith split) all CRITIQUE an existing design, this fills the GENERATIVE slot for designing an API from a blank slate before any code is written. The five sections target the three most expensive API failure modes documented in real post-mortems: (1) "emergent design" from endpoints added in request order, fixed by the actor + resource + operation inventories that force a holistic view; (2) "exposed the database schema" coupling, fixed by the explicit "resources are NOT tables" framing in section 2; (3) cross-cutting inconsistency drift (three pagination styles, two error envelopes), fixed by deciding consistency rules once in section 4. The explicit non-goals section is the single highest-leverage line in the doc, it preempts the "can we just add X" arguments that derail v1 APIs six months in. The pause-for-review gate before endpoint specs is the cheapest safety check on a multi-day API design. | Use when: Before writing the first route handler on any new API (REST/GraphQL/gRPC), or before a major v2 that significantly reshapes an existing API. Pairs with the existing Backward compatibility / breaking-change audit in Coding & Code Review, design the contract here, then enforce non-regression there as the API evolves.

Evaluate whether extracting {component/module} from our monolith into a
separate service is justified right now. Analyze: deployment coupling (how
often does this component cause deploys it doesn't own?), team ownership
(does a different team need to own this independently?), data coupling (how
many DB tables does it share with the rest of the monolith?), independent
scalability (does this component have meaningfully different load
characteristics?), and operational cost (what new concerns does a service
split introduce?).

Give a go / no-go recommendation with the specific condition that would
flip it.

SYSTEM CONTEXT:
{paste your system context block}

Why: Applies the actual *preconditions* for microservices instead of the theoretical benefits. Premature splits fail on operational cost and data coupling, not on architecture principles, this prompt enumerates exactly those dimensions. The "flip condition" output turns "no" into "no, until X" which is a usable decision instead of a permanent veto. | Use when: Anyone on the team starts proposing "let's split this out" or you're staring at a fat module and wondering if now's the time. Forces honest accounting before you write a single Dockerfile.

You are running a STRIDE threat-modeling pass on a system design BEFORE
implementation begins. Output ONE table per asset, not one big
undifferentiated list. The asset-by-asset structure is what makes the
output usable; a flat list of 40 threats mixing "spoof the login
endpoint" with "tamper with the audit log" is what produces threat-model
docs nobody reads.

PHASE 1, ASSET INVENTORY. List every asset the system touches:
- Data stores (DBs, caches, queues, blob storage)
- External integrations (APIs called, webhooks received)
- Trust boundaries (where untrusted input crosses into trusted code)
- Secrets (tokens, keys, signing material)
- Identity surfaces (auth endpoints, session stores)
For each asset: one-sentence purpose, who can read it, who can write it.

PHASE 2, STRIDE PER ASSET. For each asset, produce a table:
| Category | Threat | Likelihood (H/M/L) | Impact (H/M/L) | Mitigation | NIST 800-53 control |

Walk every asset through ALL SIX categories, don't stop at the
obvious one. Mark "N/A, {one-sentence why}" for genuinely
inapplicable categories; do NOT silently skip:

S, SPOOFING. Can an attacker pretend to be a legitimate principal?
    Mitigation pattern: strong auth, MFA, signed tokens, mTLS.

T, TAMPERING. Can data in flight or at rest be modified undetected?
    Mitigation pattern: TLS, signed payloads, checksums, immutable logs.

R, REPUDIATION. Can a legitimate action be denied later?
    Mitigation pattern: audit logs with timestamp + actor + integrity, signed receipts.

I, INFORMATION DISCLOSURE. Can the asset leak data to an unauthorized
    party? Include SIDE CHANNELS: error message text, response timing, differential HTTP status codes, cached responses, log lines.
    Mitigation pattern: encryption, scoped tokens, redaction at logging
    boundary, generic error messages externally.

D, DENIAL OF SERVICE. Can an attacker exhaust the asset's capacity?
    Mitigation pattern: rate limiting, quotas, circuit breakers, bounded queues, request size caps, expensive-query timeouts.

E, ELEVATION OF PRIVILEGE. Can a user gain rights they shouldn't have?
    Mitigation pattern: least privilege, scoped tokens, capability
    checks at every layer, no client-supplied role claims.

PHASE 3, PRIORITIZED RISK REGISTER. Combine the per-asset tables.
Rank threats by Likelihood × Impact. Output the top 10. For each:
the asset, the STRIDE category, the proposed mitigation, the NIST
control reference (e.g. AC-3 access enforcement, AU-2 audit events, SC-5 protection against DoS), and the cost class of the mitigation
(free / 1-day / 1-week / 1-month).

HARD RULES:
- Do NOT propose mitigations that treat client-supplied input as a
  security boundary. Client-side checks are UX, not security.
- Do NOT skip the "what's the side channel" question under
  Information Disclosure, timing attacks and error-message leaks
  are the most-missed STRIDE-I threats in real reviews.
- If a category genuinely doesn't apply, write "N/A, {one sentence}"
  rather than omitting it. Silence reads as oversight.

SYSTEM CONTEXT:
- What it does: {1-2 sentences}
- Data sensitivity: {public | internal | PII | PHI | financial | secrets}
- Trust model: {who's authenticated, who's anonymous, what roles exist}
- Integrations: {external APIs, OAuth providers, message buses}
- Compliance: {SOC 2 | HIPAA | PCI-DSS | none, affects mitigation cost class}

Why: STRIDE is the standard threat-model framework but most LLM-generated threat models produce a flat list that mixes spoofing of the login endpoint with a tampering threat on the audit log, useless for prioritization. Three things fix that here: (1) asset-by-asset structure groups threats around the thing being protected so engineers reading the doc find "what could hurt the database" in one place; (2) walking every category for every asset with explicit "N/A, {why}" surfaces the threats people skip, Information Disclosure is the most commonly missed because the obvious Spoofing and Elevation threats crowd it out, and side-channel leaks (timing, error text, status code deltas) live there; (3) the NIST 800-53 control mapping turns "we should rate-limit" into "AC-12 session lock + SC-5 protection against DoS", which is the language SOC 2/ISO auditors expect, so the threat model becomes a control-mapping artifact instead of a separate deliverable. The "client-side checks are UX not security" rule kills the recurring LLM failure mode of proposing input validation as a security mitigation. Distinct from the adversarial pre-commit self-review in Coding & Code Review: that one is attacker mode on a specific diff for implementation bugs; this is architecture-level threat enumeration before code exists. | Use when: Before any new service hits production, before any feature that handles PII/PHI/financial data or signs/issues tokens, or quarterly on existing services as a refresh. Pairs with the API design conversation in this section (design the contract first, then threat-model the resources) and the adversarial pre-commit self-review in Coding & Code Review (STRIDE catches architecture-level threats; the self-review catches implementation-level bugs that violate STRIDE mitigations).

You are designing a ZERO-DOWNTIME Postgres schema migration. The system
is live, multiple application versions run concurrently during deploy, and "take a maintenance window" is not an option. Output a PHASED plan
using the expand-contract pattern, never a one-shot migration that
breaks the running application or holds long locks on hot tables.

For each phase, output one row:
| Phase | DDL/DML | Lock taken (type + duration estimate) | App-code compatible with | Verification | Rollback |

PHASES, the model MUST produce all that apply. Skipping the "expand"
or "contract" half is exactly what causes outages:

1. EXPAND, add the new structure WITHOUT breaking old readers/writers:
   - For new columns: ADD COLUMN ... DEFAULT NULL. NEVER add NOT NULL
     with a default on a large table on Postgres ≤10, that rewrites
     the whole table under ACCESS EXCLUSIVE. On Postgres 11+, a
     constant default is metadata-only, so it's safe.
   - For new tables: create them; do NOT add foreign keys to large
     existing tables yet.
   - For renames: ADD the new column. LEAVE the old one. Renames are
     contracts, not operations.

2. DUAL-WRITE, deploy app code that writes to BOTH old and new
   structures. Old readers still work (read from old). New readers can
   be deployed in any order behind a feature flag.

3. BACKFILL, populate the new structure from the old, in BATCHES:
   - Batch size by table size: 1k, 10k rows per batch for <100M-row
     tables, 1k for >100M.
   - Sleep 100ms, 1s between batches to avoid replication lag spikes.
   - Non-locking pattern:
       UPDATE tbl SET new_col = expr
       WHERE id IN (
         SELECT id FROM tbl
         WHERE new_col IS NULL
         ORDER BY id
         LIMIT N
         FOR UPDATE SKIP LOCKED
       );
     SKIP LOCKED is the critical clause that prevents the backfill from
     contending with live writes, without it, you WILL take production
     down at 11am Monday.
   - Monitor during backfill: replication lag (seconds), WAL bytes/sec, locks held >1s, dead-tuple growth (autovacuum needs to keep up).

4. CUTOVER, flip readers to the new structure:
   - Deploy app code that READS from new, still WRITES to both.
   - Verify new-read parity against old-read for a sampling window
     (1% of reads, compare results, alert on mismatch).
   - Feature-flag the cutover so it's reversible WITHOUT a redeploy.

5. CONTRACT, once stable for {N days, typically 7, 14}, remove the old
   structure:
   - Stop writing to old (deploy).
   - DROP COLUMN old_col / DROP TABLE old_tbl as the LAST step, NEVER
     coupled to the cutover deploy. DROP COLUMN on a hot table is
     metadata-only and cheap; DROP TABLE takes ACCESS EXCLUSIVE
     briefly, schedule for low traffic.

LOCK-AWARE DDL RULES, for every phase, state the lock type and the
mitigation:
- CREATE INDEX → use CREATE INDEX CONCURRENTLY (no ACCESS EXCLUSIVE, but slower, cannot run in a transaction, needs idempotent retry on
  failure, leaves an INVALID index that must be dropped first).
- ADD CONSTRAINT NOT NULL → add as NOT VALID first, then VALIDATE
  CONSTRAINT, splits the lock window into two cheap operations
  instead of one long ACCESS EXCLUSIVE.
- ADD FOREIGN KEY → same pattern: NOT VALID then VALIDATE. Otherwise
  ACCESS EXCLUSIVE on BOTH tables for the duration.
- Long ALTER TABLE → set lock_timeout = '2s' before issuing, retry on
  timeout. Better to fail fast than block the connection pool.

ROLLBACK PATH, for EVERY phase, define the explicit reverse procedure.
Phase N must remain rollback-able until Phase N+1 is confirmed stable.
"Rollback is hard, so we don't" is the philosophy that produces 3am
incidents. If a phase is genuinely irreversible (DROP COLUMN with
deleted data, dropped index that's slow to rebuild on a live table), flag it RED and require an explicit go/no-go gate before execution.

INPUTS:
- Schema change goal: {what the end state should be}
- Affected table(s) and approximate row count: {table → rows}
- Postgres version: {15 | 14 | 13 | 11, earlier versions need extra care}
- Read QPS, write QPS, peak hours: {numbers}
- Deploy cadence: {how fast you can ship app-code phases}

HARD RULES:
- Do NOT propose any DDL that takes ACCESS EXCLUSIVE on a hot table
  without an explicit mitigation (CONCURRENTLY / NOT VALID + VALIDATE
  / lock_timeout + retry).
- Do NOT propose a backfill that scans the table without batching AND
  SKIP LOCKED, it WILL contend with live writes and explode replication
  lag.
- Do NOT couple cutover and contract in the same deploy. Cutover
  rollback must be possible WITHOUT a redeploy.

Why: Three things distinguish this from the existing Backward compatibility / breaking-change audit in Coding & Code Review (which scans diffs for missing migrations) and the cross-language migration scaffolder in Workflow & Automation (which migrates code, not schemas): (1) the expand-contract phased structure is the SOP for live Postgres schema changes and the most-skipped step is CONTRACT, that's how you accumulate years of dead columns nobody can safely remove; forcing all 5 phases as named outputs makes contract a first-class deliverable instead of an afterthought. (2) The lock-aware DDL rules (CREATE INDEX CONCURRENTLY, ADD CONSTRAINT NOT VALID + VALIDATE, lock_timeout + retry) target the specific Postgres operations that take ACCESS EXCLUSIVE, these are the operations that cause outages, and encoding the safer variants by name stops the model from proposing a one-liner ALTER that holds the lock for 20 minutes. (3) The per-phase rollback path with the "cutover and contract must not be in the same deploy" rule is what makes the migration recoverable, most production-incident postmortems trace back to a coupled cutover+contract deploy where the moment readers found a bug, the old column was already dropped and there was no way back. The SKIP LOCKED backfill clause is the quietly important detail, it's the difference between "backfill runs over a weekend" and "backfill takes production down." | Use when: Any non-trivial schema change on a live table, adding a NOT NULL column to >1M rows, renaming a column, splitting a column into multiple, adding a foreign key, indexing a hot column for the first time. Pairs with the Backward compatibility / breaking-change audit in Coding & Code Review (that screens a diff and flags missing migrations; this designs the migration once flagged) and with the AI agent incident runbook drafter in Documentation (the runbook for any migration-driven incident should reference the phase the migration was in when symptoms appeared).

You are going to write property-based tests for {target: file | module | function}.
Use {Hypothesis | fast-check | jqwik | ...}. Follow these phases strictly, do
not skip ahead:

1. READ. Open the target. Read code, type annotations, docstrings, function names, and any callers you can find. Note what the code claims to do, what its
   invariants are, and what its input domain looks like.

2. PROPOSE. List 5, 10 candidate properties this code should satisfy. Ground each
   one in something specific (a sentence in the docstring, a type signature, a
   known mathematical law like commutativity / idempotence / inverse, a
   round-trip such as serialize→deserialize). For each property, state the input
   strategy you will use.

3. WRITE. Translate the top 3 properties into property-based tests. Use the
   framework's input generators, do not write example-based tests.

4. RUN + SELF-REFLECT. For each test:
   - If it passes: is it actually testing something non-trivial, or did you
     accidentally write a tautology / wrap the whole body in try/except?
   - If it fails: is this a real bug in the target, or is the property wrong?
     If it's a real bug, produce a minimal counterexample and a one-paragraph
     bug report (what property was violated, the input that triggered it, the
     observed vs. expected behavior).

5. REPORT. Final output: the test file, plus a table of properties tried, pass/fail, and a verdict (real bug / spec ambiguity / property was wrong).

Target: {paste path or function name}

Why: Mirrors the workflow Anthropic's agent used to find hundreds of real bugs in NumPy, SciPy, Pandas, and others, the unlock is the explicit self-reflection step that catches the failure mode where the model wraps the whole test in `try/except` and declares victory. The "ground each property in something specific" rule kills generic invariants and the tautology check at step 4 kills tests that pass for the wrong reason. | Use when: Adding PBT to a module with strong invariants, parsers/serializers (round-trip), numerical code (mathematical laws), pure functions, anything with a type-narrow public API. Especially valuable on legacy modules with thin example-based test coverage.

This test sometimes passes, sometimes fails. I cannot reproduce it reliably.
Analyze the test and the code it's testing for sources of nondeterminism. Check
each of these six categories explicitly, do not stop at the first plausible cause:

1. Shared mutable state between tests (module-level vars, singletons, caches)
2. Timing dependencies (sleeps, timeouts, async ordering, retries with jitter)
3. Test-order dependencies (does this test pass only when another runs first/never?)
4. Uncontrolled randomness (unseeded RNG, time.now(), UUIDs in assertions)
5. Environment variable leakage between tests
6. Database / filesystem state not cleaned up between runs

For each category, state EXPLICITLY: "checked, no issue" or "issue found at line X".
Then identify the single most likely root cause, show the minimal fix as a diff, and propose a fixture or isolation pattern that prevents this category recurring.

Test code:           {paste}
Code under test:     {paste}
Failure output:      {paste, when it fails}
Passing output:      {paste if meaningfully different}

Why: Six explicit categories force a checklist scan instead of latching onto the first plausible explanation, flaky tests almost always die from the *non-obvious* category, so making the model say "checked, no issue" for each one is what catches the real cause. Distinct from the existing Debugging entries: this stays narrowly on test nondeterminism (DB state, ordering, RNG, env) instead of general bug hunting, and the "fixture or isolation pattern" output produces a structural fix, not a one-line patch. | Use when: Any test that's been retried or `@pytest.mark.flaky`'d more than once. Also great pre-merge on a new test that passes locally but you suspect will leak state in CI.

You are generating CHARACTERIZATION tests for legacy code. The goal is NOT
to assert correct behavior, it's to lock in CURRENT behavior so any refactor
that changes it is caught the moment it changes.

Target: {file or class}
Framework: {JUnit 5 + Mockito | pytest | Jest + ts-jest | ...}

Execute phases strictly in order, do not skip ahead:

1. INVENTORY. List every public method, its signature, and every input it
   reads (params, instance fields, env vars, IO it touches). Do not write
   tests yet.

2. CAPTURE. For each method, write tests that record what it ACTUALLY does
   today against:
   - The happy path
   - Every input the type system allows: null, empty, zero, negative, max
     boundary, malformed type, unicode / escape-heavy strings
   - Each documented error path AND every silent-failure path you can find
   Tests must assert OBSERVED outputs, including any apparent bugs. If
   the method returns a stale cache, swallows an exception, or returns
   `null` where it should throw, the test ENCODES that, with a comment:
   `// CURRENT BEHAVIOR, may be buggy, do not "fix" during refactor`

3. NAME tests in the form
   `should_{observedBehavior}_when_{condition}`
   so any future regression is named in the failure message itself.

4. MOCK boundary IO (DB, HTTP, queue, clock, filesystem). Do not hit the
   network. Where legacy code has hidden dependencies, static singletons, module-level state, time.now(), thread-local context, list them at
   the end as "untested coupling, refactor before extracting".

5. REPORT. Final output: the test file PLUS a section titled "behaviors
   I encoded that look like bugs", one bullet per suspicious behavior
   with the line reference. I'll decide later which become real assertions.

Why: Characterization tests are Michael Feathers' Working Effectively with Legacy Code pattern, the only safety net that catches "refactor accidentally changed behavior." Distinct from the Behavior-focused unit tests entry (writes tests for the *correct* behavior of new code) and Property-based test author (tests invariants). The killer rule is the `CURRENT BEHAVIOR, may be buggy` comment: most engineers can't resist "fixing" a bug while writing its test, which is exactly how you discover three weeks later that production silently depended on the bug. Encoding it preserves the safety net AND surfaces the suspicious behavior for an explicit decision later. | Use when: Before touching any untested legacy file. Run this first; then refactor against a green suite. Pairs naturally with the post-fix class-of-bug extractor: characterize → refactor → extract the class lesson.

You are auditing AI-generated code with mutation testing. Coverage is
high and tests pass, that IS the failure signal you're hunting, not
the success signal. Run scoped to the files changed in this PR only
(differential mutation testing, never the whole codebase, that turns
a 3-minute pre-merge check into a 3-hour batch job).

Framework: {PIT for Java | Stryker for JS/TS | mutmut or cosmic-ray for
Python | go-mutesting for Go}

Execute phases strictly in order:

1. SCOPE. Identify the files changed in this PR. Run mutation testing
   ONLY on those files with their corresponding tests. Reject any
   suggestion to run on the whole repo.

2. CLASSIFY each surviving mutant into exactly one of three buckets.
   Every survivor is a blind spot, but only bucket (a) is worth your
   time:

   a) REAL BLIND SPOT, the test asserted shape but not value. Classic
      example: `assertEquals(3, result.size())` passes whether dedup
      uses reference equality OR business-key equality. Or
      `assertEquals(90, applyDiscount(100, PCT_10))` passes for both
      `amount * 0.9` and `amount - 10` because 100 → 90 either way.
      Action: write a new test that distinguishes the two
      implementations.

   b) EQUIVALENT MUTANT, the mutation produces semantically identical
      behavior (e.g. `i <= n-1` → `i < n`, or reordering commutative
      operands). Action: mark equivalent with a one-sentence
      justification. Do NOT write a test.

   c) TRIVIAL / OUT-OF-SCOPE, survivor is in logging, error-message
      text, telemetry, or a default branch documented as unreachable.
      Action: mark and skip.

3. KILL THE BLIND SPOTS. For each (a), write a test that:
   - Uses DIFFERENT inputs than the existing test. The existing test
     masked the mutant, your new input must distinguish the two
     implementations. If the existing discount test uses 100 → 90, your new test uses 200, because `200 - 10 ≠ 200 * 0.9` is what
     kills the mutant.
   - Asserts SEMANTIC intent, not structural shape. Assert the business
     rule, not the collection count.
   - Has a name in the form `should_{behavior}_when_{condition}` so a
     future regression names itself in the failure message.

4. REPORT. Output a table:
   | mutant | file:line | bucket (a/b/c) | killing test added |
   Plus the new mutation score and the delta vs. the PR baseline.

THRESHOLDS, flag the PR if these aren't met:
- ≥80% mutation score on newly added AI-generated code
- ≥90% on auth, billing, data-integrity, and security paths
- Mutation score must NOT DECREASE when the agent modifies existing
  files. This catches the silent anti-pattern where a PR raises LINE
  coverage by adding tautology tests (`assertNotNull(result)`, `verify(mock).wasCalled()`) that pass for the wrong reason.

Do NOT chase 100%. Equivalent mutants and the test-suite cost curve
make that a trap. The deliverable is bucket-(a) survivors killed, not
a round number.

Why: Line coverage tells you what *ran*; mutation testing tells you what your tests would *catch if the code were wrong*, exactly the gap AI-generated tests fall into because LLMs produce structurally-correct-but-semantically-drifted tests at roughly 15, 25% higher survivor rates than human-written suites at equivalent coverage. Three things make this distinct from the existing Testing & QA entries: (1) PR-SCOPED (differential) mutation testing, running on changed files only is what collapses runtime from hours to minutes and lets this live as a pre-merge gate rather than a quarterly batch job; (2) the three-bucket classifier kills the failure mode where the model dutifully writes tests for equivalent mutants and burns the review budget on noise, only bucket (a) survivors get tests; (3) the "different inputs than the existing test" rule is the actual mechanic that kills mutants, most survivors live because the chosen test inputs accidentally collapse two implementations (the canonical 100→90 discount example), and forcing a distinguishing input is what makes the mutant die. The "score must NOT decrease" rule catches the AI-tests anti-pattern where a PR raises line coverage by adding `assertNotNull` / `verify(mock).wasCalled()` tautologies that pass without asserting anything. | Use when: PR review on AI-generated code touching auth, billing, data integrity, or anywhere a silent-failure bug would page someone, exactly the domains where "tests pass at 92% coverage" is the failure signal. Pairs with the existing Behavior-focused unit tests (writes the right kind of test from scratch), Characterization tests (locks in legacy behavior including bugs), and the Adversarial pre-commit self-review in Coding & Code Review (attacker mode on the code itself).

You are my debugging partner. Your job is to help me produce a minimal
reproduction of a bug.

Constraints:
- Ask me at most 5 clarifying questions.
- Do not propose fixes yet.
- The output must be runnable and minimal.

What I will provide:
- A description of the bug (expected vs actual)
- Any error messages / stack traces
- The relevant code snippet(s)
- Environment details I know (OS, runtime versions)

Your tasks:
1) Restate the bug as a single-sentence "failure contract" (Given/When/Then).
2) Identify the smallest set of inputs + steps needed to reproduce.
3) Propose a minimal repro artifact:
   - either a single file I can run
   - or a tiny project skeleton (list of files + contents)
   - or a sandbox snippet
4) Output a checklist of "remove/unnecessary" items to strip next.
5) Define a stop condition: how we know the repro is minimal.

Start by asking your clarifying questions.

Why: Most debugging prompts try to *solve* the bug; this one refuses to fix anything and instead produces the runnable artifact you need to hand to a teammate or a maintainer. The Given/When/Then "failure contract" makes the bug testable, and the explicit stop condition (deleting any line breaks the repro) prevents the model from declaring victory at "small enough." Pairs with Reproduce-isolate-diagnose: that one hypothesizes the cause, this one builds the asset you debug against. | Use when: Filing an upstream issue, escalating to another team, or pinning down a "works on my machine" intermittent. Also great for the moment you realize you've been debugging in-tree for 90 minutes and need to step out into a clean directory.

I just fixed this bug. Don't celebrate, extract the generalizable lesson.
Output four sections:

1. CLASS. Name the category of bug this is (e.g. "fencepost / off-by-one", "TOCTOU race", "unhandled null in optional chain", "stale cache after write", "missing idempotency on retry"). One sentence on why this category recurs
   in any codebase, not just mine.

2. WHERE ELSE. Search patterns I can grep my codebase with RIGHT NOW to find
   other instances. Be specific, file globs, regex, function-name patterns.
   Example: `rg "OFFSET .*\* limit" --type py` not "look for pagination code".

3. STRUCTURAL FIX. The pattern, abstraction, or invariant that would have made
   this bug impossible to write. If the answer is "be more careful" you have
   not thought hard enough.

4. AUTOMATED CATCH. One linter rule, type-system trick, property-based test, or CI check that would catch the entire class going forward. Show the rule
   or test, not a description of it.

Bug: {what it was}
Fix: {paste the diff or describe}
Codebase: {language, framework, rough size}

Why: Most teams fix a bug and move on. This prompt turns a one-time fix into a permanent guardrail by demanding (a) a grep pattern you can run today to find siblings, and (b) an automated check that prevents the whole class, not just "be more careful next time." The "if the answer is 'be more careful' you have not thought hard enough" line is a working anti-platitude trigger. | Use when: Right after closing any non-trivial bug, especially the second time you've seen the same class. Pairs naturally with the Reproduce-isolate-diagnose and minimal-repro prompts above, diagnose, repro, fix, then extract.

You're investigating an unattended Claude-Code-style agent session that
shipped a wrong PR. Tests pass. Code compiles. Something is subtly
wrong, a security assumption violated three hours in, a context
decision that poisoned the implementation, or a tool call that
silently returned an empty result and was treated as success. The diff
is visible; the decisions that produced it are not.

You have three artifacts:
- The PR / output (the visible failure)
- The audit log JSONL (tool calls, exit codes, timestamps)
- The session transcript JSONL (model turns, tool inputs, tool outputs)

Execute phases strictly in order. Do NOT skip to "the fix", every
shortcut here produces archaeology, not debugging.

1. TIMELINE RECONSTRUCTION. Join the audit log and the transcript on
   timestamp. Produce ONE chronological view:
     `turn N | tool | command (60 char) | exit | output preview (200 char)`
   Sort strictly by timestamp. Do not summarize yet, facts only.

2. DIVERGENCE BISECT. Look at the final output and identify the FIRST
   wrong decision visible in it (wrong file modified, wrong assumption
   made, wrong architectural choice). Find that decision in the
   timeline. Then walk BACKWARD to the last decision that was still
   correct. The divergence is the boundary between those two turns.
   Read only that window. Do NOT read the full transcript end-to-end.

3. EVIDENCE AT THE BOUNDARY. For the divergence window, list:
   - What was in the context (which prior tool results was the model
     reading from at that turn?)
   - What tool the model called and what it returned
   - Whether a context COMPACTION happened just before this point, in Claude Code this is the silent-killer: a compaction at turn
     N-2 drops a constraint, and every decision after N is made
     without it
   - Whether any tool returned `exit_code: 0` with empty
     `output_preview` (silent tool failure, the agent treated "no
     findings" as "no issue to act on" and proceeded)

4. ROOT-CAUSE CLASSIFICATION. Pin the cause into EXACTLY ONE of four
   buckets, the bucket determines the fix layer, and a misclassified
   cause results in a fix in the wrong layer that doesn't prevent
   recurrence:

   a) CONTEXT DECISION, the model decided correctly given what it
      saw, but what it saw was wrong (stale summary, dropped
      constraint, misleading earlier tool output). Fix layer:
      CLAUDE.md / project instructions / context-compaction strategy.

   b) SILENT TOOL FAILURE, a tool returned an empty result and the
      agent treated it as success. Fix layer: PostToolUse validation
      hook that asserts non-empty results for tools where empty is
      suspicious (Read on a known file, Grep that should match a
      known marker, list_files on a non-empty directory).

   c) POLICY VIOLATION, the agent did something it should never have
      been allowed to do (touched a forbidden path, called a write
      tool without approval, exceeded its scope). Fix layer:
      PreToolUse blocking hook with an allowlist or deny pattern.

   d) MISSING EXPERTISE, the model didn't know a domain-specific
      rule (your API requires idempotency keys; your migrations need
      a specific lock; this codebase forbids X library). Fix layer: a
      Skill, or a CLAUDE.md rule that injects the missing knowledge.

5. COUNTERFACTUAL TEST. Before committing the fix:
   - Reconstruct the context state at the divergence point
   - Re-run the same task from that point WITH the fix applied
   - Verify the new outcome is correct
   - Only THEN commit the fix to its layer (hook / skill / CLAUDE.md)

OUTPUT:
- The divergence boundary: `turn N → turn N+1`
- The root-cause bucket (a/b/c/d) with a one-sentence justification
- The exact fix in the correct layer (the hook code, the skill
  content, the CLAUDE.md addition, not a description of it)
- The counterfactual result (correct / still wrong / partial)

HARD RULES:
- Do NOT propose a fix without identifying the divergence turn first.
- Do NOT "ask the agent what it did", it has no episodic memory of
  the prior session, it will hallucinate a plausible reconstruction.
  The transcript is the only source of truth.
- Do NOT read the full transcript end-to-end. Bisect to the boundary, read the surrounding 5 turns, stop.

Why: Three things make this distinct from the existing Debugging entries: (1) Reproduce-isolate-diagnose, Minimal repro artifact builder, and Post-fix class-of-bug extractor all target *code* bugs with a stack trace and a reproducible failure, this fills the new failure mode of unattended agent sessions where the bug is a *decision*, the run was nondeterministic, and there is no stack trace because nothing crashed; the agent "succeeded" but did the wrong thing. (2) The four-bucket root-cause classifier (context / silent tool failure / policy violation / missing expertise) is the closing loop, each bucket maps to a *specific* fix layer (CLAUDE.md, PostToolUse hook, PreToolUse hook, Skill), which is what turns one-off forensic work into permanent guardrails. Without the classifier, every fix gets jammed into the system prompt and the prompt grows until the agent ignores half of it. (3) The "do NOT ask the agent what it did" rule kills the most common autonomous-session debugging failure, engineers ask Claude "explain what you did" and the model cheerfully hallucinates a plausible reconstruction because it has no episodic memory of the prior session and is just continuing the conversation. The transcript-as-ground-truth + bisect-don't-replay discipline is what converts a 45-minute autonomous session post-mortem from "read 30 git diffs and guess" into a targeted 5-turn read. | Use when: Any time an unattended Claude Code / agent session produces an outcome you didn't expect, a PR with a subtly wrong commit, a refactor that quietly violated a constraint, a release-notes draft that asserted something the code doesn't actually do, an overnight migration loop that landed on a wrong schema. Pairs with the AI agent incident runbook drafter in Documentation (runbook is preparation; this is forensics) and with the Post-fix class-of-bug extractor above (once you've pinned the divergence and fixed the layer, run that prompt to extract the grep pattern / linter rule that prevents the whole class).

You are triaging an LLM-powered FEATURE in production that's degrading.
Latency, error rate, and throughput all look normal, the model is
"succeeding" but the outputs are subtly wrong, drifting, or hallucinated.
Standard SRE runbooks are blind to this failure class. Work the
diagnosis tree IN ORDER, do not skip layers, do not fix anything until
you've named the layer.

CONTEXT TO PASTE:
- Sample failing trace (full prompt + retrieved chunks + model output)
- Model version (read from the API RESPONSE, not your config, they
  diverge during provider rolling updates)
- Prompt version ID (immutable hash, not "the current prompt")
- Retrieval index version + "last indexed at" timestamp
- Sampling params (temperature, top_p)
- Recent changes (model bumps, prompt edits, index rebuilds, sampling
  param edits, tool schema changes, last 30 days, with timestamps)

PHASE 1, TRACE IT. Locate the failing span. Separate retrieval, prompt rendering, and generation steps. Output what each layer produced.
Facts only, no interpretation yet.

PHASE 2, ISOLATE IT. Classify the fault into EXACTLY ONE of four
layers. Misclassifying wastes hours and can mask the cause:

Layer 1, RETRIEVAL FAILURE. The model's answer is wrong because the
right context never reached it. Test: do the retrieved chunks contain
the correct answer? If NO, the fault is retrieval. Common causes:
embedding drift (embedding model rotated, vector index not rebuilt), index staleness (ingestion broke silently), top-K truncation (correct
answer scored below cutoff), tokenization mismatch between retriever
and generator. DO NOT touch the prompt or model.

Layer 2, GENERATION FAILURE. Retrieved context is correct but the
model ignored, contradicted, or fabricated past it. Test: replay the
EXACT retrieved context directly to the model. If the replay also
fails, the fault is generation. Common causes: silent model version
change (provider rolled a new snapshot under your model name, compare the `model` field on the API response to your pinned
version), prompt instruction conflict (system says X, user says
not-X, model resolves the wrong way), context-position bias (critical
content buried mid-context gets ignored), sampling param drift
(someone shipped a temperature/top_p change without an eval).

Layer 3, ROUTING ERROR. The wrong tool, sub-agent, or model class
was invoked. A query that needed the capable model went to the cheap
one; a query that needed tool A went to tool B. Test: check the
tool_call / intent_class field in the trace. If the selected route
differs from what you'd expect, routing is the fault. Watch
specifically for two-sub-agent loops with no circuit breaker, the
"clarification ping-pong" failure mode is the most expensive variant;
one documented case ran for 11 days, $127/wk → $47k/wk, before
anyone noticed.

Layer 4, UPSTREAM DATA CORRUPTION. Quality degrades across an
entire topic cluster starting on a specific date. The model cites
plausible-looking sources with high confidence and is wrong. Test:
per query, which source docs are being retrieved? Sudden
concentration from one recently-ingested source on newly-degraded
topics is the signal. Causes: bad ETL batch, vector store indexing
against a stale snapshot, or active poisoning, as few as 5
crafted documents against millions can achieve a 90% attack success
rate via embedding-proximity manipulation.

PHASE 3, EVALUATE IT. Run automated evaluators on the failing
trace (groundedness, format compliance, retrieval relevance).
Output numeric scores, you need a baseline to confirm any fix
actually works, not just "looks better."

PHASE 4, SIMULATE IT. Replay the failed request in a sandbox.
Swap ONE variable at a time: prompt version → context → model
version → sampling params → tool schema. The single variable
whose swap fixes the failure IS the root cause. Resist
combinatorial fixes, they hide which change actually mattered.

PHASE 5, FIX AND REGRESS. Test the fix against a golden eval
dataset BEFORE deploy. Add the failing case to the eval suite, this is the actionable artifact, not the fix itself. Deploy via
CANARY (1% of traffic keyed on user_id for reproducibility, NOT
random), with behavioral evaluators running for 1-2h. Promote on
green; kill the canary flag on red.

HARD RULES:
- Do NOT attempt a fix before phase 2 layer classification.
  Fixing generation when the fault is retrieval makes the symptom
  go away while the cause spreads.
- Do NOT trust your config for the model version, read the
  `model` field on the API response. Provider rolling updates
  are invisible to your deploy log.
- An UNRESOLVED layer is a feature, flag it for L2, do not
  smooth to a confident wrong conclusion.

OUTPUT:
- The diagnosis: layer 1/2/3/4 with the trace evidence that proves it
- The single root-cause variable identified in phase 4
- The new eval case added to the suite (input + expected behavior)
- The canary deploy plan with the behavioral evaluator that would
  catch this regression next time

Why: Three things make this distinct from the existing Debugging entries: (1) Reproduce-isolate-diagnose, Minimal repro artifact builder, and Post-fix class-of-bug extractor all target *code* bugs with a stack trace and a deterministic failure, this fills the new failure mode of LIVE LLM features degrading where dashboards stay green, no error fires, and the symptom is "subtly wrong output, " which standard SRE runbooks are structurally blind to. (2) The 4-layer diagnosis tree (retrieval / generation / routing / upstream data) forces a layer classification BEFORE any fix attempt, every layer has a different fix mechanism (rebuild the index vs. re-pin the model vs. add a circuit breaker vs. find the bad ETL batch) and reaching for the wrong lever is exactly how these incidents stretch from hours to days. (3) The "read the `model` field from the API response, not your config" rule catches the silent-model-version-rotation failure mode that's now the single most common cause of unexplained LLM regressions in 2026, providers do rolling updates under the same public model name and your pinned config doesn't catch it. Distinct from the Agent session divergence post-mortem above (which is about unattended code-writing agents producing wrong PRs); this is about production LLM features serving end-user traffic. | Use when: Any LLM-powered feature in production where users are reporting "the answers got worse" but your dashboards are green, RAG/QA bots, summarization endpoints, classification services, content generation features. Run this BEFORE rolling back blindly; the layer classification is what tells you whether a rollback even helps. Pairs with the AI agent incident runbook drafter in Documentation (runbook is preparation; this is triage in-flight) and the LLM provider snapshot rollout discipline in Workflow & Automation (one of the layer-2 root causes this prompt surfaces is exactly what that prompt prevents).

You are diagnosing a LONG-RUNNING AI agent that's mid-workflow and
producing increasingly wrong-looking outputs. Standard error
monitoring sees nothing, no exception, no nonzero exit, the agent
keeps running. The failure mode is context poisoning: the agent's
own accumulated context window has become a source of wrong
information, and every subsequent step is reasoning on corrupted
premises.

You have the full session transcript (tool calls, tool results, model turns) and the agent's structured state at checkpoints.

Execute phases strictly in order. The most common failure here is
jumping to "just compact the context" before classifying WHICH of
the four mechanisms is poisoning the session, each has a
different fix and compaction itself is a known trigger for new
poisoning (a summary can become a hallucinated fact).

PHASE 1, CLASSIFY THE POISONING MODE. Pin the cause into EXACTLY
ONE of four buckets. The bucket determines the fix:

  a) POISONING. A hallucinated fact was embedded early and is now
     treated as ground truth. The agent asked a tool whether a
     file existed, misread the response, wrote "file confirmed
     present" into its notes, and every downstream step that
     touches that file is reasoning on a false premise. Test:
     walk the transcript and find the FIRST claim the agent
     asserted as true. Check the tool response that produced it.
     If the tool response does NOT support the claim, you've
     found the poisoned fact.

  b) DISTRACTION. The session has crossed roughly 50% of the
     context window and the model has started pattern-matching
     against its own past steps rather than synthesizing new
     plans. Symptom: tool calls 80+ start looking like clones of
     tool calls 30, 50, regardless of whether current state
     warrants them. Test: are recent tool calls structurally
     similar to older ones with minor parameter changes, even
     when the task has shifted? If yes, distraction.

  c) CONFUSION. Tool definition sprawl. The agent has too many
     tools and is picking wrong ones. Accuracy degrades
     measurably past ~30 tool definitions; the failure rate is
     non-linear above that. Test: count distinct tools in the
     manifest. If >30 and wrong-tool-pick is a recurring symptom, confusion.

  d) CLASH. The agent took a wrong turn early and the incorrect
     reasoning is still in the context window, contradicting
     later correct reasoning. Benchmark data shows a 39%
     performance drop when earlier errors persist, the model
     does NOT detect the contradiction, it rationalizes around
     it. Test: is there a CORRECTED claim later in the transcript
     that contradicts an earlier asserted claim? If both are
     still in the window, clash.

PHASE 2, SESSION HEALTH SIGNALS. Whether or not Phase 1 pinned a
mode, walk these four signals, they're the standing diagnostics
worth checking on every long-running session and they often
surface the cause when Phase 1 is ambiguous:

  - TOOL OUTPUT STALENESS: An agent that fetched a resource in
    step 2 and references it in step 11, is it re-querying or
    relying on a 9-step-old value? Stale reads are especially
    dangerous in workflows that span minutes/hours where external
    state can change underneath an in-flight agent.

  - REASONING COHERENCE DRIFT: Intermediate reasoning steps that
    contradict earlier steps. Agent says "the file does not
    exist" at step 4 and "processing file contents" at step 7.
    That's context corruption, not goal completion. List every
    such contradiction with the two turn numbers.

  - TOOL CALL REDUNDANCY: A spike in duplicate tool calls
    (sometimes with slightly different results) signals the
    agent has lost track of what it already knows. Count
    duplicate calls in the most recent 20-turn window.

  - INSTRUCTION COMPLIANCE DECAY: The initial system prompt is
    the most important input AND the least attended content as
    the session grows. Pick 3-5 fixed invariants from the system
    prompt (output format rule, forbidden action, required
    field) and check whether the agent still honors them in the
    most recent 10 turns. Decay is the early warning.

PHASE 3, FIX LAYER. Each Phase-1 bucket maps to a SPECIFIC fix.
Misclassifying produces a fix in the wrong layer that doesn't
prevent recurrence:

  Poisoning → INVARIANT CHECKING. Before the agent acts on any
  asserted fact about external state (file exists, record found, API returned 200), it must RE-VERIFY against the source of
  truth. The fix is a wrapper that re-queries the tool whose
  response is being relied upon if the response is older than N
  turns or N minutes.

  Distraction → CHECKPOINT-RESTORE. At defined milestones
  (typically after each irreversible action OR every ~30 turns, whichever is first), persist the agent's STRUCTURED STATE, not the full context, and restart from a known-good
  checkpoint with a freshly summarized context. The new context
  contains the checkpointed state plus the immediate task, not
  the full conversation history.

  Confusion → TOOL-MANIFEST PRUNING. Per task, dynamically
  scope the tools the agent can see to the minimum required. A
  "summarize this ticket" task should NOT see the 47
  CRM-mutation tools, they cost tokens AND increase wrong-tool
  selection rate.

  Clash → SELECTIVE CONTEXT PRUNING. Mark the wrong reasoning
  segment as RETRACTED rather than deleting it. The agent's
  next turn sees a prefix that says "turns N, M were based on
  incorrect information that was later corrected; ignore them
  when reasoning about current state." Plain deletion is worse, it leaves dangling references in subsequent turns that the
  model fills with hallucinations.

PHASE 4, INVARIANT TEST FOR THE FIX. Before deploying the fix, replay the affected session from the divergence point with the
fix applied. Verify (a) the wrong claim is now flagged or
re-verified, (b) subsequent steps no longer depend on the
corrupted premise, (c) the agent doesn't infinite-loop trying to
re-verify indefinitely (a poorly-bounded invariant checker is
its own failure mode).

OUTPUT:
- The poisoning mode (a/b/c/d) with the transcript evidence
  that proves it
- The four session-health signals scored (present / absent /
  unable-to-determine)
- The fix in the correct layer (invariant wrapper / checkpoint
  schedule / dynamic tool scope / RETRACTED marker), show the
  code or config, not a description
- The invariant test result (clean replay / still corrupted /
  bounded-loop on re-verify)

HARD RULES:
- Do NOT "just compact the context" before classifying the
  poisoning mode. Compaction can DESTROY the evidence of which
  mode hit you and is itself a known trigger for new
  poisoning.
- Do NOT trust the agent's own self-report on what went wrong.
  It's reasoning from the same poisoned context that produced
  the failure. The transcript is the only source of truth.
- Standard error monitoring is BLIND to this class. Do NOT
  close the investigation because logs are clean. Clean logs +
  wrong-looking output IS the signal.

Why: Three things make this distinct from the existing Debugging entries: (1) Reproduce-isolate-diagnose / Minimal repro artifact builder / Post-fix class-of-bug extractor target *code* bugs with a stack trace; Agent session divergence post-mortem targets *unattended* code-writing agents producing wrong PRs after a session ends; LLM feature production degradation triage targets live *user-facing LLM features* (RAG, classification, summarization). None of those address the LONG-RUNNING, in-flight, multi-turn agent that's mid-workflow and silently corrupting downstream steps because its own context window has become the source of wrong information, a failure mode standard error monitoring is structurally blind to (no exception, nothing crashes, the agent runs to completion and returns a wrong answer that gets laundered through four downstream systems and arrives at the user looking like legitimate work). (2) The four-mode classifier (poisoning / distraction / confusion / clash) maps each cause to a SPECIFIC fix layer (invariant wrapper / checkpoint-restore / dynamic tool scoping / RETRACTED marker), without the classifier, every fix gets jammed into "compact the context" which can DESTROY the evidence of which mode hit you AND become a new poisoning trigger when the compaction summary itself contains a hallucination. (3) The four session-health signals (tool output staleness / reasoning coherence drift / tool call redundancy / instruction compliance decay) double as a standing diagnostic checklist for any long-running agent, they catch the failure before the cascading-failure pattern downstream-amplifies the corrupted fact through multiple systems. The "do NOT trust the agent's own self-report" rule mirrors the same anti-pattern flagged in the existing Agent session divergence post-mortem entry, for the same reason: the model has no episodic memory and will reason from the same poisoned context that produced the failure. | Use when: Any long-running agent (workflow spans minutes-to-hours, multi-step task chains, multi-agent pipelines where one agent's output feeds another) that's producing increasingly wrong-looking outputs while standard monitoring stays green. Also as a quarterly audit on production agents, run the four session-health signals against a sample of recent sessions; rising staleness / drift / redundancy / compliance-decay numbers are an early warning before user complaints. Pairs with the Agent session divergence post-mortem above (single-session forensics AFTER a wrong PR ships; this one handles in-flight long-running agents) and the LLM feature production degradation triage above (its Layer 1 retrieval-failure root cause and this prompt's poisoning mode are different mechanisms for the same surface symptom, wrong output with no error fired).

ROLE: You are an SRE reconstructing an incident timeline from raw
operational data. Order events strictly by timestamp. Preserve the
source of every event. Flag gaps and contradictions, do not guess
to fill them.

CONTEXT:
  Incident ID: {paste}
  Output time zone: UTC, ISO 8601, second precision
  Raw inputs (each in a separate labeled block):
    - Slack transcripts (#incidents, #eng-oncall)
    - PagerDuty event log
    - Deploy notifications from CI
    - Log lines from affected services (15 min before first alert
      through 15 min after resolution, error/warning only)
    - Ticket updates

TASK: Produce ONE chronological timeline. For each row include:
  - UTC timestamp (ISO 8601, second precision)
  - Source (which input block)
  - Event description, one sentence, factual, no interpretation
  - Actor role (e.g., "on-call engineer", "CI system", "automated
    alert"), NEVER a person's name

Tie-break order: automated alerts > logs > deploys > PagerDuty > Slack > tickets.
If a gap >5min has no events from any source, insert: [GAP: N min].
If two sources contradict, insert: [CONTRADICTION: A says X, B says Y].

ACCEPTANCE:
  - Zero individual names in the output (roles only)
  - Every event traceable to a source block
  - Gaps and contradictions flagged, never smoothed
  - Facts only, interpretation belongs in the RCA, not the timeline

Why: The "actor role, never a name" constraint is the unlock, a timeline with names reads as a record of *who did what*; a timeline with roles reads as *how the system behaved*. Same events, completely different postmortem culture. The explicit gap/contradiction flagging stops the model from quietly papering over 10-minute holes. | Use when: Drafting any postmortem from raw Slack + PagerDuty + logs. Run this BEFORE the RCA prompt, never in the same pass, or interpretation creeps into the timeline.

You are drafting an INCIDENT RUNBOOK for an AI agent in production. Traditional
service runbooks fail here because agent failures are behavioral, non-deterministic, and have a blast radius that spans every tool the agent can touch. Your runbook
must answer the questions an on-call engineer will have at 2am when the agent is
"working" but producing wrong outputs.

Output FOUR sections, each with concrete, executable steps, not principles:

1. SESSION TRACE PULL. The exact procedure to retrieve the complete execution
   record for the affected session(s): every LLM call, every tool invocation, token count per step, the full context window at each decision point. Name
   the system (Langfuse / Arize / custom OTEL pipeline) and the query or URL
   the on-call runs. If the artifact doesn't exist yet, flag it as a pre-deploy
   blocker.

2. KILL-SWITCH. The pre-established procedure to stop this agent, both for a
   single session and for all sessions globally, executable in <5 min by an
   on-call engineer who did NOT build the agent. Show the exact command, feature
   flag, circuit-breaker config, or API call. "Submit a PR and redeploy" is not
   a kill-switch. Include how to verify the kill is effective.

3. BLAST RADIUS AUDIT. An enumerated checklist of every external system this
   agent has write access to (CRM, DB, queue, email, Slack, external APIs).
   For each: the query/log endpoint that surfaces this session's activity, the
   team/contact to notify, and the reversal procedure if reversible. The list
   must be exhaustive, every tool in the agent's manifest, not just the
   obvious ones.

4. BEHAVIORAL SLA. The thresholds that should TRIGGER incident response BEFORE
   a customer complaint. Each as a specific number and signal:
   - Token spend per session ceiling
   - Tool calls to any system outside the agent's defined scope
   - Output confidence floor (if scored)
   - Sustained latency or retry rate above X
   For each: where it's enforced (governance layer / circuit breaker /
   observability alert), and who gets paged.

Agent description: {what it does, what tools it has, who owns it}

Constraint: roles only, never individual names, runbooks survive team changes.

Why: Most agent runbooks are recycled service runbooks, they walk through error rate, trace, rollback. None of that applies when the agent "succeeded" but did something wrong. The four-element structure (trace / kill-switch / blast radius / behavioral SLA) is what the SRE community settled on in early 2026 after the first wave of production agent incidents, and forcing executable specifics on each (the actual command, not "have a kill-switch") turns the runbook into something on-call can use at 2am instead of a slide deck. The "roles only, never names" line borrows from the postmortem prompt, same justification: the runbook becomes a record of how the system behaves, not who babysits it. | Use when: Drafting the operational runbook BEFORE any new agent reaches production, or auditing an existing agent's runbook for the four elements that service runbooks typically miss. Pairs with the postmortem timeline prompt above, runbook is prep, postmortem is forensics.

Write documentation for these error messages. For EACH error produce:

1. The error code and message exactly as it appears in the system.
2. What state actually caused it, explain the failed precondition or the
   wrong system input, not the message restated in different words.
3. The two or three most common causes, listed in order of frequency for
   real users (most common first). Each cause should name a specific
   condition a developer can check: "wrong key environment (live vs test)"
   not "authentication problem".
4. A resolution path, what to check first, what to change, and what to
   do if none of those work.
5. A "still stuck" line with the request ID / correlation ID a developer
   should include when filing a ticket, plus what they should NOT include
   (e.g. the token itself, raw PII).

Do NOT paraphrase the error message. "INVALID_TOKEN: the token is invalid"
adds nothing. Document the diagnostic the developer needs.

Format: markdown reference, one error per section, scannable on first read.

Errors to document:
{paste code + message pairs, or paste your error-definitions file}

System: {what produces these errors, API, SDK, CLI}
Reader: {external integrator, internal teammate, end user}

Why: The "don't paraphrase" rule is the entire game, most error docs say "INVALID_TOKEN: the token is invalid" and add zero diagnostic value. Listing causes by *frequency* (most common first) matches how a stressed developer actually reads docs, scan three options, try the most likely. The "what NOT to include in the ticket" line is a quiet security win: keeps tokens and raw PII out of support inboxes. Distinct from the existing API endpoint doc generator, that one documents the contract; this one documents the *failure* the contract throws. | Use when: Closing an undocumented-errors backlog, or right after shipping a new endpoint and you want the developer-portal entry live before customers hit the errors at 2am. Pairs with the documentation gap audit below, audit surfaces the undocumented errors, this prompt writes them up.

Audit the documentation below from the perspective of {target reader, e.g. "an external developer integrating this SDK for the first time" or
"a backend engineer onboarding to this service in their first week"}.

Do NOT rewrite anything. Produce a prioritized gap list, diagnostic only.

For each finding output: severity, the specific gap, and a one-sentence
fix note. Use these severity tiers strictly:

- BLOCKS THE READER. Without this, the reader literally cannot proceed
  (missing auth steps, no install command, no working example).
- SLOWS THE READER. The reader can proceed but loses 10+ minutes on
  something that should have taken 30 seconds (missing version
  requirement, unstated default, response schema absent, OS-specific
  gotcha not documented).
- MINOR. Style, inconsistency, broken link, typo.

For each gap also identify, when applicable:
- The implicit knowledge the doc assumes that the reader doesn't have.
- Steps that could be interpreted multiple ways.
- Error scenarios mentioned but not explained.
- Anything likely outdated or contradicting current stack behavior.

If you can attach a few real support questions (paste below), map each
ticket to the documentation gap that caused it, this turns the audit
into evidence: every gap that maps to a real ticket is funded work.

Documentation to audit:
{paste docs}

Target reader: {describe, be specific, not "a developer"}
Stack / context: {language, framework, what these docs cover}
Sample support tickets (optional): {paste 2-3 if you have them}

Why: Severity tiers force triage, without them, a flat list of 40 gaps puts the missing auth step next to the inconsistent capitalization, and the author has to do the prioritization the audit was supposed to do. The "blocks the reader" framing identifies what actually stops someone from using the product, which is the only gap that matters urgently. The optional support-ticket mapping is the killer line: it turns the audit from a writing exercise into evidence, where every gap that maps to a ticket has a customer attached to it. Distinct from existing review/audit entries, those scan code; this stays narrowly on docs and surfaces missing-information failures, not correctness failures. | Use when: Before any major doc rewrite, after any large product change, or quarterly on the docs that drive integration. Run this *before* the writing prompts so you fix the BLOCKS gaps first instead of polishing the MINOR ones.

You are designing a production-grade Claude Code / agent routine that will run
unattended. BEFORE any system prompt or tool wiring, design the routine on
these six dimensions. Output one table, one row per dimension. No principles, specific, executable choices only.

1. TRIGGER. {scheduled | API webhook | repository event}. State the cadence
   or event. If scheduled and the daily run cap is tight, declare whether this
   is the daily meta-orchestrator slot OR a real-time slot reserved for
   latency-bound work, and justify which.

2. APPROVAL SURFACE. The exact human checkpoint before any write hits
   production. Options: lands in a draft doc, opens a PR against a prefixed
   branch (e.g. release-notes/*), or files into a triage queue (Linear/Jira
   un-triaged). "Slack-DM the result" is not an approval surface, name what
   the human does and what they merge / publish / triage.

3. PERMISSION SCOPE. Per connector: list ONLY the scopes this routine needs.
   Read-only where possible. If the routine never edits a Jira ticket, the
   token must not grant write. State the principle: scope is the minimum a
   day-1 attacker holding this token could do, not the maximum the human
   creator can do.

4. PROMPT-INJECTION SURFACE. Identify every field of untrusted external text
   the routine ingests (customer ticket body, Sentry error payload, Slack
   message content, PR description, URL params in error traces, etc). For
   each: the sanitization that happens BEFORE the LLM sees it (PII redaction, code-block stripping, user-supplied-strings dropped from error payloads, allowlist of fields).

5. RATE LIMIT CONSTRAINT. The upstream API limit this routine bumps into
   first (e.g. Slack conversations.history = 1 req/min for non-Marketplace
   apps, GitHub GraphQL secondary limits, vendor-specific quotas). The
   workaround: search API, targeted webhook, batching, or backoff.

6. AUDIT TRAIL. The minimum fields logged per run, structured:
   triggering event ID → tools called with params → resulting object IDs
   (e.g. Sentry event ID → Linear ticket ID). State the destination (SIEM, S3, OpenTelemetry collector), not just "we log it".

Routine goal: {one sentence}
Connectors needed: {list}
Owning team: {team, not person}

End with a single STOP-SHIP question: what's the smallest thing that, if it
broke silently in this routine, would cause a real customer incident? If you
can answer that, you're ready to write the prompt. If you can't, the design
isn't done.

Why: Most "build an agent" prompts dive straight into the system prompt and tool list. This one forces the governance dimensions FIRST, trigger choice (against run quota), approval surface, scoped permissions, injection surface, rate-limit reality, audit, which is the production-readiness gate that bundled-connector demos skip and then fail in security review. The stop-ship question at the end is the kill-shot: if you can't name the silent failure mode that would page you, the design isn't ready. Distinct from the Headless scheduled audit (which IS one specific routine's output) and Supervisor + subagent (which is about runtime decomposition, not deployment safety). | Use when: Before writing the system prompt for any unattended routine, scheduled cron, webhook-triggered, or repo-event-triggered. Pairs with the AI agent runbook drafter in Documentation: design first, run safely, then runbook the failure modes.

You are scaffolding a cross-language codebase migration that will run
mostly unattended with a Claude-Code-style agent in a loop. Output TWO
files, do not begin generating target-language code yet.

Setup is a monorepo:
  {source-language}-source/   # original codebase, read-only
  {target-language}-target/   # new implementation, written by the agent
  CLAUDE.md                   # design doc, what you're producing now
  MIGRATION.md                # ordered task list with dependencies

PHASE 1, DISCOVERY. Before writing either file, run these scans against
{source-language}-source/ and accumulate findings in a notes file. Each
scan is a SEPARATE pass, bundling produces shallow results:

  1. Codebase scan: file count, directory structure, entry points, test
     setup, key dependencies.
  2. Bounded contexts: logical groupings that map to domain boundaries.
  3. Ubiquitous language: domain vocabulary extracted from class names, method names, docstrings, test names.
  4. Pattern mapping: source-language idioms (decorators, ABCs, exception
     hierarchies, duck typing, generics) with proposed target-language
     equivalents.
  5. Dependency mapping: every external library mapped to its
     target-language counterpart, or marked "no equivalent, design
     replacement".
  6. Data-access layer: ORM, repositories, schema, migrations.
  7. Event mapping: domain events, publishers, handlers.
  8. DEAD-CODE & PHANTOM-FEATURE scan: any deprecated tables, leftover
     references, comments, or type hints that reference removed features.
     Flag these for cleanup BEFORE migration begins, the agent WILL
     rebuild deprecated features from stale references if you let it.

PHASE 2, CLAUDE.md must include these sections, populated from discovery:

  - Domain context and ubiquitous-language glossary.
  - TRANSLATION RULES TABLE: source idiom → target idiom → notes. Be
    exhaustive. Example rows for Python→Go: `class Foo(Base)` →
    `embed Base or implement interface`; `@dataclass` → `type Foo struct{}
    + NewFoo() constructor returning error`; `try/except` →
    `if err != nil { return ..., fmt.Errorf(...) }`; `Optional[T]` →
    `*T or (T, bool)`; list comprehension → loop with append.
  - Coding standards (compose over inherit, small interfaces, immutable
    where possible, name types for what they are not what they do).
  - Project structure: exact directory layout, layer rules (domain has no
    infra imports), file and package naming.
  - PUBLIC API design, which packages are exported, what the client
    interface looks like. Default agent behavior is to put everything in
    the language's private/`internal/` equivalent. If you need a public
    API for other projects to consume, specify it here or the agent will
    not produce one.
  - Configuration rule: config is set, defaulted, validated, and logged
    in ONE place, never scattered across downstream code.
  - Migration workflow: read MIGRATION.md at the start of every session, mark items complete after finishing, append to the session log.

PHASE 3, MIGRATION.md is an ordered task list with dependency tracking.
Each row maps a source file to its target file, lists prerequisite
tasks, and has verification checkboxes for: target compiles, unit tests
pass, lint clean, SMOKE TEST (start the app and hit the critical paths, unit tests alone are not acceptance), parity with source behavior on
REAL data (not synthetic fixtures).

PHASE 4, GUARDRAILS to bake into the agent's per-session prompt:
  - After each refactoring task, the agent runs an explicit dead-code
    check and reports what it removed. Dead code accumulates silently
    because internal islands import each other.
  - The agent runs the app end-to-end at least once per phase. Unit-test
    green is not acceptance, components in isolation can all pass while
    the wired system returns wrong results.
  - For any cross-cutting change (pagination, auth, logging), the agent
    produces a plan first and checks items off, it must NOT attempt all
    affected sites in one pass. It will compact context and miss half.
  - A real-data migration test runs at the END of phase 1 of the
    checklist, not at the end of the project, it surfaces phantom
    features and schema drift before they cost weeks.
  - The agent commits after each completed task with a message naming
    the MIGRATION.md row it closed.

INPUTS:
  Source language / framework / size: {e.g. Python 3.11 / FastAPI / 50k LOC}
  Target language / framework: {e.g. Go 1.22 / chi}
  Why migrate, one sentence (the agent uses this to break ties):
    {e.g. "deploy as a single Go binary, drop heavy ML deps"}
  Known dead code or deprecated schemas to remove first: {list}

Output the discovery notes file first. Pause for review. Then output
CLAUDE.md and MIGRATION.md. Do NOT begin writing target-language code
until I confirm the design files.

Why: Encodes the field-tested method behind Phil Winder's Python→Go migration of Kodit (50k LOC, completed unattended in ~2 hours of automation loop). Three things make this distinct from "Supervisor + subagent" (runtime decomposition) and "Production routine design table" (deployment safety): (1) the explicit dead-code & phantom-feature scan BEFORE migration begins, Winder lost days because the agent rebuilt a deprecated `snippets` table from leftover type hints; (2) the translation-rules TABLE in CLAUDE.md keeps translations consistent across files instead of letting the agent improvise per file; (3) the smoke-test + real-data-migration requirement catches the integration bugs that pass unit tests but produce wrong outputs (Winder's Go port returned wrong search results because of L2-vs-cosine, truncated embeddings, and wrong-table reads, all of which unit tests missed). The "pause for review" gate before code generation is the cheapest safety check available on a multi-day migration. | Use when: Any cross-language port or major framework swap that the agent will run mostly unattended in a loop. Also useful as a forcing function before MANUAL migrations, even if a human will do the work, the design doc + checklist removes most "we forgot about that subsystem" failures.

You are about to bump the LLM provider model version your production
system depends on (claude-x.6 → claude-x.7, or rolling a snapshot date
forward). Output a STAGED ROLLOUT PLAN, never a one-line config edit, even for a minor bump. The version number is marketing, not a contract;
behavioral compatibility is what you actually depend on, and nobody is
committing to keep it stable.

PHASE 0, START FROM PINS, NOT ALIASES. If your production calls
`claude-sonnet` or `gpt-4o-latest`, fix THAT first. Aliases
auto-upgrade, you experience every provider snapshot as an
unannounced production deploy with zero rollout staging. Re-pin to
an explicit dated snapshot before doing anything else; this plan
only works against pins.

For the target version, produce one table per phase. Skipping a
phase is how minor bumps break production harder than majors:

PHASE 1, REGRESSION EVAL AGAINST A PINNED BASELINE.
- Pin the eval dataset version. Document the version ID.
- Run the new model against the SAME eval cases that pass on the
  current pinned version. Compute PER-CASE pass/fail, not just
  aggregate.
- Surface NEGATIVE FLIPS, cases the old model got right that the
  new model gets wrong, EVEN IF aggregate accuracy improved
  (Apple's research term for the phenomenon). Aggregate hides
  regressions; the regressions are exactly what your production
  depends on.
- Include the slices that DISTINGUISH the two models, edge cases
  where the old model's specific capability mattered, not the
  generic happy-path slice that grades well on both.
- Required behavioral evaluators on top of accuracy:
  • Format compliance: JSON-mode strictness, code-fence-around-
    structured-output likelihood, refusal verbosity.
  • Tokenization sanity: prompt-cache hit-rate delta (a new
    tokenizer changes cache behavior, which changes cost, which
    silently invalidates your caching strategy).
  • Instruction-following precedence: system vs user role conflicts, does the new model resolve them the same way?
  • Uncertainty calibration: did "I'm not sure" answers turn into
    confident hallucinations (or vice versa)?
  • Sycophancy slice: the April 2025 sycophancy incident
    postmortem named "standard checks weren't specifically looking
    for sycophantic behavior" as the gap, no aggregate eval
    catches this.

PHASE 2, SHADOW TRAFFIC.
- Mirror N% of production traffic to the new model, log only, do NOT serve the new model's output to users.
- Run the behavioral evaluators on shadow vs primary in parallel.
  Look at the per-call DISTRIBUTION SHIFT, not just the mean: a
  flat average hides 20% of calls getting meaningfully worse and
  20% getting meaningfully better.
- Watch for cost-per-call drift, latency p95 drift, and TOOL-CALL
  DIVERGENCE (new model picks different tools for the same input
  → routing-layer change you didn't authorize).
- Minimum 24-48h before promotion, enough to cover a daily
  traffic cycle and a low-volume weekend slice.

PHASE 3, CANARY (KEYED, NOT RANDOM).
- 1% of traffic, keyed on stable user_id or session_id (NOT
  random per-request) so the same user sees consistent behavior
  across a session and you can compare same-user before/after.
- Run behavioral evaluators on canary vs production traces for
  1-2h. The eval suite MUST include the sycophancy / behavioral
  slice, accuracy-only canary is exactly the gap that shipped
  the April 2025 incident.
- Promote on green (define green numerically: < X% regression
  per named behavioral slice). Kill canary flag INSTANTLY on
  red, no debate, no investigation in the moment.
- Stateful sessions: session-version-tag every canary session so
  a kill drains in-flight sessions gracefully rather than
  hard-cutting and corrupting context mid-conversation.

PHASE 4, PROMOTE VIA LABEL, NOT REDEPLOY.
- The `production` label is a configuration operation that
  propagates within seconds, never a code redeploy that takes
  10 minutes during which you cannot roll back.
- The new snapshot becomes the new pin. Document it.
- Keep the previous pin callable for the provider's deprecation
  window, that's your rollback path.

PHASE 5, ROLLBACK PROCEDURE, DEFINED BEFORE PROMOTE, NOT AFTER.
- Single command / label flip to revert to the previous pin.
  TEST IT IN SHADOW BEFORE PROMOTE, not during an incident.
- For stateful agents: graceful drain, in-flight sessions stay
  on the version they were started under, new sessions get the
  rollback. No hard cutover, no context corruption.
- Rollback eval: confirm the previous pin still produces the
  baseline behavior. Provider deprecation windows close silently;
  the call you thought was your rollback may now return an
  alias-resolved newer snapshot.

INPUTS:
- Current pinned model + snapshot date
- Target pinned model + snapshot date
- The 5-10 behavioral slices your product is most sensitive to
  (output format, refusal style, tool-call pattern, uncertainty
  expression, sycophancy, JSON strictness, code-fence behavior, reasoning verbosity, be specific to YOUR product)
- The numeric "green" threshold per slice
- Traffic volume (so eval and canary sample sizes are
  statistically sound)

OUTPUT:
- The five-phase plan with numeric thresholds per phase
- The eval slice list with one explicit behavioral test per slice
- The rollback command, tested in shadow
- One STOP-SHIP question: which behavioral slice, if it regressed
  silently, would cause a real customer incident before
  eval-on-traffic alerted? If you can't name it, you don't have
  the eval coverage yet.

Why: Three things make this distinct from the existing Workflow & Automation entries: (1) Headless scheduled audit and Supervisor + subagent are runtime-composition patterns; Production routine design table is governance for a Claude-Code-style unattended routine; Cross-language migration scaffolder is a one-time code migration, none address the recurring failure mode that every LLM provider model bump is a breaking change in disguise, which is now the most common cause of unexplained LLM regressions. (2) The pin-first-then-stage discipline kills the alias-trap failure mode where teams call `claude-sonnet` and experience every provider snapshot as an unannounced production deploy, fixing the alias before doing anything else is what makes the rollout plan even possible. (3) The negative-flips rule (cases the old model got right that the new model gets wrong, EVEN IF aggregate accuracy improved) targets the specific way Apple's research-named "negative flips" pattern bypasses standard regression evals: aggregate scores improve while specific high-value cases break, and the negative-flip review is the only check that catches it. The behavioral-eval-on-canary requirement (sycophancy, refusal verbosity, JSON strictness, not just accuracy) is the operational lesson from the April 2025 sycophancy incident postmortem that explicitly named "standard checks weren't specifically looking for sycophantic behavior" as the gap. | Use when: Before any LLM provider model version change, including minor bumps and snapshot date rolls, which break production harder than major ones because they trigger no institutional alarms. Also when you discover your production is calling an alias instead of a pin, run this prompt's Phase 0 fix first. Pairs with the LLM feature production degradation triage in Debugging (one of the 4-layer root causes that prompt surfaces is "silent model version change", this prompt prevents that root cause from existing) and with the AI agent incident runbook drafter in Documentation (the runbook should reference this rollout discipline as the standard pre-deploy check for model bumps).

You are running a PRE-DEPLOYMENT blast-radius analysis on an AI
agent before it ships. The question is not "what does this agent
do?", it is "what's the worst thing this agent can do if it
reasons incorrectly under an edge condition?" That question, answered systematically before launch, is what separates teams
that ship small failure surfaces from teams that discover their
limits through incidents (the canonical example: nine seconds
for a Cursor agent to delete an entire production database
including all volume-level backups while attempting to fix a
credential mismatch, the model did exactly what it calculated
it should do; nobody had bounded the permission scope).

Execute phases strictly in order:

PHASE 1, TOOL INVENTORY. List every tool in the agent's
toolkit. For each, answer three questions, and answer them
about MAXIMUM SCOPE of what the tool CAN do, not what the
product spec says it does:

  a) What's the most damaging thing this tool can do if called
     with WRONG PARAMETERS? A "search documents" tool that
     accepts a wildcard returns the entire document store. A
     "send notification" tool with no rate limit is a
     denial-of-service vector. A "manage calendar" tool with
     delete rights in addition to read is a data loss vector.
     Assume the agent WILL call the tool incorrectly under an
     edge condition, because it will.

  b) Is the worst case REVERSIBLE? Reading wrong records is
     recoverable. Deleting them is not. Sending the wrong
     email is not. Publishing to an external service is not.
     Charging a card is not. The reversible / irreversible
     split determines whether a failure is an incident or a
     disaster.

  c) Does this agent ACTUALLY NEED this tool? The most
     effective blast-radius reduction isn't better guardrails, it's removing permissions the agent doesn't need.
     OWASP's Excessive Agency category (LLM06) names this as
     the dominant failure mode: agents routinely receive more
     permissions than necessary because it's easier to grant
     access than to scope it carefully. Anything marked
     "irreversible" AND "not clearly necessary" must be
     removed before the agent ships, flag as STOP-SHIP.

PHASE 2, RISK CLASSIFICATION MATRIX. Classify every remaining
tool into EXACTLY ONE of four tiers. The tier determines
runtime control:

  GREEN (automatic). Read-only queries, internal lookups, logging, notifications to the operating user. Bounded blast
  radius. Execute without approval.

  YELLOW (async approval). Read-write operations on
  non-critical internal data. Agent proceeds; action logged
  with enough context for a human to review and reverse
  within hours. No in-flight approval, but the audit trail
  is mandatory.

  ORANGE (real-time gate). External API calls, any
  production-DB write, financial operations, cross-system
  state changes. Agent prepares the action in DRY-RUN mode, explains what it would do without doing it, and
  presents the plan for human confirmation before execution.
  The human reviews the plan, not the aftermath.

  RED (hard disable). Destructive operations on production
  systems, credential management, audit-log writes, anything
  requiring secondary authorization under your compliance
  framework. Either blocked entirely at the infrastructure
  layer, OR requires multi-party approval before the agent
  can proceed.

PHASE 3, ENFORCEMENT LAYER. State explicitly, per tool, WHERE the classification is enforced. A system prompt that
says "always ask before deleting" does NOT prevent deletion, it creates a reasoning expectation that the model may not
honor under unusual inputs. ORANGE and RED tiers MUST be
enforced at the HARNESS LAYER, not the model layer. The
agent infrastructure intercepts the tool call BEFORE
execution, validates against the risk tier, and proceeds /
gates / blocks, INDEPENDENT of what the model decided.
State the specific interceptor (Python decorator, MCP
server wrapper, gateway middleware, function-calling
validator) and what it does on a violation (raise, return
error to model, page on-call).

OUTPUT:
- The full tool permission matrix:
  | tool | worst case | reversible? | necessary? | tier | enforcement point |
- The STOP-SHIP list: tools flagged irreversible AND not
  clearly necessary
- A dry-run example for every ORANGE tool, the exact text
  the agent will present to the human reviewer before
  execution
- The kill-switch for every RED tool, the command, flag, or infrastructure-layer block that disables it
  independently of any agent decision

HARD RULES:
- Do NOT classify a tool based on what you EXPECT the agent
  to do with it. Classify based on the WORST it CAN do.
- Do NOT enforce ORANGE/RED at the model layer (system
  prompt rules, asking the model "are you sure?", chain-of-thought self-checks). The model may not honor
  those expectations under edge inputs.
- Do NOT skip Phase 1c. A tool that fails the "actually
  needs this?" test is a permission grant the model will
  eventually find a wrong use for.

INPUTS:
- Agent description and primary task: {one paragraph}
- Full tool manifest: {list every tool with its scope}
- Deployment environment: {sandbox | staging | production}
- Compliance regime if any: {SOC 2 | HIPAA | PCI-DSS | none}

Why: Three things make this distinct from the existing Workflow & Automation entries: (1) Production routine design table covers 6 governance dimensions (trigger / approval / permission scope / injection surface / rate limit / audit), those are *deployment* governance; this fills the missing slot for *action-level* worst-case-reversibility classification per tool, which is the level at which the 9-second-prod-DB-deletion class of incident gets prevented. (2) The four-tier matrix (green / yellow / orange / red) is the structure the industry converged on by mid-2026 for agent action classification, AWS Agentic AI Scoping Matrix, OWASP LLM06 Excessive Agency, and Anthropic's trustworthy-agents framework all converge on roughly these tiers, and forcing every remaining tool into exactly one of them stops the model-layer-versus-harness-layer ambiguity that allows "we have guardrails" to mean nothing. (3) The "ORANGE and RED MUST be enforced at the HARNESS LAYER, not the model layer" rule is the kill-shot, it targets the most common production-agent failure mode, where a system prompt rule ("always ask before deleting") gets ignored under an edge input because the model never actually had to honor it. Distinct also from the AI agent incident runbook drafter in Documentation (which describes the kill-switch for post-incident response); this is the pre-deployment classification that determines which tools NEED a kill-switch in the first place. | Use when: Before any new agent ships to production, before adding a new tool to an existing production agent (the new tool's tier may be more restrictive than the agent's current default), or as a quarterly audit on existing agents, especially agents whose tool manifests have grown by accretion since launch. Pairs with the AI agent incident runbook drafter in Documentation (this prompt's tier table is the input to the runbook's blast radius audit section), the Production routine design table above (that prompt's permission scope dimension references this prompt's tier classification), and the Long-running agent context-poisoning health check in Debugging (poisoning + insufficient blast-radius bounds is how a single corrupted fact becomes a production-DB DROP).

{Diagram type: architecture diagram / sequence diagram / data flow /
infographic / org chart}, {one-sentence subject, what the diagram explains}.

LAYOUT: {top-down | left-to-right | radial | swimlane | matrix}, {N} primary nodes/sections, {connector style, labeled arrows /
unlabeled lines / swimlane bands}.

NODES, label each with the EXACT text in quotes, do not paraphrase:
"{Label 1}", "{Label 2}", "{Label 3}", ...

EDGES, label each connector with the EXACT text in quotes:
"{edge label 1}", "{edge label 2}", ... (or state "unlabeled" if none).

TYPOGRAPHY: bold sans-serif for node titles (Inter / Helvetica /
IBM Plex Sans family), regular weight for body, ALL CAPS for section
dividers. ONE typeface family across the entire image, no mixing.

COLOR SYSTEM: {2-3 color palette, e.g. "navy #0F2940, slate #475569, accent amber #F59E0B on near-white #FAFAFA background"}. Reserve the
accent color ONLY for {what gets highlighted}.

STYLE: flat vector, {isometric-30° / top-down 2D / schematic}, 1px crisp strokes, no shadows, no gradients, no skeuomorphism, no decorative illustrations, no people, no stock-photo overlays.

OUTPUT: 16:9 at 4K resolution, print-ready.

KEEP TOTAL PROMPT TEXT UNDER 400 WORDS, above that threshold, NB Pro starts garbling labels.

Why: Three Nano Banana Pro specifics that change what's actually achievable for diagrams in late 2026: (1) the quoted-string label rule, NB Pro's text engine hits ~99% rendering accuracy when each label is in explicit quotes AND the total prompt stays under ~400 words, which is the threshold above which labels start to garble; (2) the single-typeface-family rule kills the most common "AI diagram" tell, which is mixed-font noise from the model improvising headers in a serif and body in a sans; (3) the explicit "no people, no decorative illustrations" negative holds NB Pro to "engineering diagram" rather than drifting to "marketing infographic." Distinct from the cinematic and photoreal entries, those are *photographic* formulas; this fills the "I need a system diagram for the design doc / deck" slot the section was missing, which is the workload NB Pro is uniquely good at because of its labeled-text rendering. | Use when: Architecture diagrams for design docs, sequence / data-flow diagrams for an explanation post, KPI infographics for the board deck, anywhere you'd otherwise hand-build in Excalidraw or Figma and want 10 variations fast. For diagrams with strict topology (precise spacing, technically exact), still draft in Excalidraw; NB Pro is best when the audience cares about clarity-of-explanation, not pixel-precise spec.

{Shot type + angle} of {subject + descriptor} {action/posture} in {environment}, {lighting direction + quality}, {atmospheric element if any}.

CINEMATOGRAPHY: shot in the style of {named DP or director, e.g.
"Roger Deakins", "Christopher Doyle", "Emmanuel Lubezki", "Bradford Young", "Wes Anderson", "Christopher Nolan"}. Use ONE name, mixing references muddies
the look.

FILM STOCK: {named emulsion, e.g. "Kodak Portra 400" (warm natural skin tones), "Kodak Ektachrome E100" (clean saturated blues/greens), "Fuji Velvia 50"
(landscape, punchy reds/greens), "Cinestill 800T" (tungsten halation, night
neon), "Ilford HP5" (B&W high-contrast street)}. The stock name carries the
color science and grain structure, do NOT layer a generic "color grade"
descriptor on top.

LENS + EXPOSURE: shot on {focal length, e.g. 35mm / 50mm / 85mm} at f/{aperture}, {ISO if relevant}, {composition rule, e.g. rule of thirds / centered close-up /
Dutch angle}.

NEGATIVE: --no plastic skin, oversaturated, HDR look, lens flare overlay, digital sharpening artifacts

--ar 16:9 --style raw --s 150 --v 8 --hd

Why: Three things that make this distinct from the existing 5-slot cinematic formula in this section: (1) one named cinematographer carries an entire visual philosophy that abstract descriptors like "moody, dramatic, cinematic" don't, "shot like Roger Deakins" tells v8 the lighting, framing, color temperature, and contrast curve in three words; (2) named film stocks (Kodak Portra 400, Cinestill 800T, Fuji Velvia 50) are now reproduced accurately in MJ v8, earlier versions garbled them, so "teal-and-orange grade" was the workaround; v8 makes the workaround obsolete; (3) the `--hd` flag on v8 renders at native 2K instead of upscaling, which is what reveals the film grain authenticity that makes the difference between "AI render" and "photographic." The "one name, don't mix" rule is the kill-shot, Lubezki-meets-Nolan produces nothing coherent. Distinct from the existing cinematic 5-slot formula (which stays tool-agnostic across MJ v7 / Nano Banana / ChatGPT) and the photoreal product/portrait formula (which is studio-softbox-spec for objects, not story-driven scenes). | Use when: Hero shots and story-driven imagery where the audience reads "this looks like a movie." Especially when previous MJ v7 attempts kept landing as "AI illustration that looks like a photo" instead of "photo." Drop `--v 8 --hd` and `--s 150` if running on Nano Banana Pro, the cinematographer + film-stock pair still works there because both models trained on enough labeled examples to recognize the references.

[SCENE]: {environment + time of day + weather + atmosphere, e.g.
"a neon-lit Tokyo alley at 1am during light rain, reflective puddles
on the pavement, distant traffic hum"}. Be specific about what is
NOT in frame too, Sora 2 fills empty slots with averages, and the
averages are stock-footage generic.

[SUBJECT]: {ONE primary subject with physical description, wardrobe, position in frame}. One subject for clips ≤10s. Multi-subject scenes
degrade, you'll prompt-bash for hours and still get face drift.

[ACTION]: {single verb-driven action, present-tense, lasting the
clip's full duration}. Avoid "X happens, then Y happens", Sora 2
still struggles with multi-shot continuity and will interpret
sequencing as a request for a jump cut. ONE action per clip.

[CAMERA]:
- Shot type: {wide | medium | close-up | extreme close-up | POV}
- Movement: {static | dolly push-in | dolly pull-out | tracking shot |
  orbit | slow pan left/right | crane up/down | handheld with subtle
  shake}
- Lens: {anamorphic 35mm | 50mm prime | 85mm portrait | 24mm wide}
- Framing: {rule of thirds | centered | over-the-shoulder | Dutch angle}

[MOOD / GRADE]:
- Film stock: {35mm grain | Super 8 warmth | clean digital |
  16mm documentary | Cinestill 800T night neon}
- Color tone: {desaturated teal | warm amber | high-contrast B&W |
  bleached pastel | golden hour}
- Emotional temperature: {tense | melancholy | exuberant | clinical |
  reverent}

[AUDIO, Sora 2 generates synced audio natively, unlike Sora 1]:
{ambient sound layer + any specific sound effects + dialogue in
quotes with speaker tag if any, e.g. "ambient: rain on metal awning, distant siren; SFX: footsteps on wet pavement; dialogue: man, mid-30s, gravelly voice: 'I told you not to come back here.'"}

[NEGATIVE]: no scene cuts, no on-screen text unless explicitly quoted, no multiple shots, no aspect-ratio change mid-clip, no rapid camera
movement that breaks continuity.

Duration: {4s | 6s | 8s | 12s}. Aspect: {16:9 | 9:16 | 1:1}.

Why: Three Sora 2 specifics that matter in 2026 and fill a section that had zero video coverage: (1) the Scene → Subject → Action → Camera → Mood layer order is the architecture OpenAI's own cookbook teaches, skipping a layer makes Sora "average" the missing one and you get generic stock-footage output, so the formula is structurally complete to prevent the most common failure; (2) the one-subject + one-action rule is the field-tested discipline because Sora 2 still degrades on multi-shot continuity and multi-subject crowd scenes, the prompt structurally enforces single-shot single-action so you stop fighting the model on its weakest dimension; (3) Sora 2 generates synced audio NATIVELY (the major upgrade over Sora 1), the explicit [AUDIO] slot with the ambient / SFX / dialogue breakdown is what lifts clips from "muted AI render" to "feels like real footage" with one extra line, and is the slot most prompt guides still omit because they're written for Sora 1 patterns. The negative list specifically forbids scene cuts because Sora 2's most common failure mode is interpreting "X then Y" as a request for two shots and producing a stuttering jump cut. Distinct from the existing cinematic 5-slot stills formula and the MJ v8 cinematographer-attribution + film-stock formula, both produce still images; this fills the moving-image slot the section was missing entirely. | Use when: Hero clips for landing pages, product demo footage, social-cut B-roll, opening shots for explainer videos, anywhere you'd otherwise license stock video. Drop the [AUDIO] block on Kling 2.5 or Veo 3, both still need a separate audio pass. The Scene → Subject → Action → Camera → Mood layer order works across all three video models because it's structural to how diffusion video models read prompts, not Sora-specific.

{Monogram | Wordmark | Lettermark} logo: "{letters or word in quotes}", {style: thin-line / sans-serif geometric / serif transitional / art-deco /
brutalist / humanist}, {2 colors max, e.g. "navy and gold" / "black on white"}, white background, flat vector, centered composition, {historical or designer reference, e.g. Bauhaus / Saul Bass / Massimo
Vignelli / Paul Rand / Herb Lubalin} influence
--ar 1:1 --style raw --s 100 --v 8
--no gradients shadows 3D photo realism noise texture sparkles

Why: Three things that actually move the needle on text-based logos in MJ v8: (1) the letters or word go in **quoted strings**, v8's biggest gain over v6.1 is rendering quoted text inside prompts much more accurately, so "luxury monogram MK" (unquoted) is the old pattern that drifts to "abstract M-and-K shape"; (2) the long `--no gradients shadows 3D photo realism noise texture sparkles` negative list is what actually holds the render to "flat vector logo" instead of "AI art that resembles a logo"; (3) `--style raw --s 100` floors the stylization so the historical-designer reference acts as a *direction* rather than a paint filter applied on top. Distinct from the existing minimalist and healthcare entries, those are symbol-based; this is the text-mark slot the section was missing. | Use when: Initials for a person, founder, or studio (LL, MK, JR); wordmarks where the letterforms ARE the logo (the "Saul-Bass-does-a-three-letter-company" brief); any time the minimalist formula keeps returning "abstract shape" but you wanted "the letter K, beautifully." Output is raster, vectorize via Vectorizer.ai or Illustrator Image Trace. Drop `--v 8` if running on Nano Banana Pro.

{Mascot type, animal | abstract creature | humanoid character} for
{brand / product}. Reference image attached.

POSE / EXPRESSION: {specific pose, waving / sitting cross-legged /
running / reading / pointing}. {Expression, neutral / smiling /
focused / friendly wink}.

CONTEXT: {the new scene, "on a laptop screen", "holding a product
box", "next to a giant arrow sign", "leaning on a question mark"}.
Plain white or solid brand-color background UNLESS a scene is needed.

STYLE LOCK: flat vector, {2-3 color palette matching the original}, {thick clean outline | no outline}, {flat shading | minimal gradient}.
Same proportions, same palette, same level of detail as the reference, do NOT add a new rendering style.

--cref {URL to canonical mascot, front-facing, clean background, full
body if proportions matter}
--cw {80 default for "same character, new scene"; 100 if face/hair
identity is non-negotiable; 40-60 for stylistic variation that's still
recognizable}
--sref {URL to one approved on-brand asset, locks color palette and
rendering treatment, separate from character identity}
--ar 1:1 --style raw --s 100 --v 8
--no photorealism 3D shadows gradients hyperrealistic stock-photo
lens-flare changed-proportions added-shading

Why: Three things make the --cref + --cw + --sref combination the v8 unlock for mascot systems: (1) earlier MJ versions drifted on character identity across renders, forcing manual photo-bashing; v8's character-reference engine plus the explicit weight slider turns "same mascot, 50 different scenarios" from a coin flip into a reproducible workflow. (2) The --cw 80 default is the field-tested sweet spot, 100 locks too rigidly and the character looks pasted in, below 60 the face drifts; 80 keeps face and hair recognizable while letting pose and outfit adapt to context. (3) The "do NOT add a new rendering style" line is the kill-shot for the most common mascot-system failure: the model adds shading/depth/lighting because the new scene "looks more complete" that way, and you end up with a 3D-rendered version of your flat mascot. The --cref / --sref separation is what makes it possible to vary the scene without varying the brand, --cref pulls identity, --sref strips aesthetic, they don't fight each other in v8. Distinct from the existing entries: minimalist is *abstract* logos, monogram is *text*-based marks, healthcare is symbol-based service logos, this fills the *character*-based brand identity slot where the same recognizable mascot needs to ship across web, social, packaging, and slides without redrawing. | Use when: Building out a mascot-based brand identity system, designing a launch campaign that needs the same character across hero image / Twitter avatar / blog header / event slide / packaging mockup, or onboarding a new mascot where you need 30 variants for designer review without redrawing each one. Pairs with the existing minimalist logo formula, design the canonical mascot using that, then run this prompt to populate the system around it. Drop --v 8 and keep --cref / --sref if running on Nano Banana Pro, which supports the same parameter family.

You are generating a COMPLETE BRAND ASSET SET in ONE call using
gpt-image-2 with Thinking Mode enabled, the model can produce up
to 8 coherent images from a single prompt with consistent character, object placement, brand color palette, and typography feel across
the full set. This is the unlock the 8-panel batch capability
makes possible; do not split into 8 separate calls, the consistency
breaks the moment the model forgets it's working on a system.

ASSET SET, 8 panels max. Pick the subset you need; do not exceed 8:
- Primary logo (square, transparent background)
- Wordmark variant (horizontal lockup)
- Favicon / app icon (square, simplified for small sizes)
- Business card front
- Social card / Instagram story (9:16 OR 1:1)
- Website hero (16:9)
- Packaging mockup (specify carton / pouch / box / label)
- Email signature lockup

INVARIANTS, restate these at the START of the prompt AND repeat
them as the LAST line. gpt-image-2 drifts on cross-panel
consistency when invariants are stated once at the top; restating
at the bottom is the field-tested fix:

- COLOR PALETTE: exactly {2-3 hex codes, e.g. "#0F2940 navy, #F59E0B amber accent, #FAFAFA near-white background"}. No
  other colors. Accent color ONLY on {what gets highlighted}.
- TYPOGRAPHY FEEL: {one family description, e.g. "geometric
  sans-serif, IBM Plex Sans / Inter weight 600 for marks, weight 400 for body"}. ONE family across all 8 panels.
- MOTIF: {one repeated visual element, e.g. "an abstract wave
  shape that appears at different scales in every asset"}.
  Same shape, different size and crop per panel.
- ASPECT RATIO PER PANEL: state explicitly per asset. Do NOT
  ask the model to "pick the right ratio."

CONTRACT TEXT, every panel that contains text must have that
text in QUOTED STRINGS, exactly as it should appear. gpt-image-2
text rendering is strongest when each label is quoted:
- Business card: "{Person Name}" / "{Title}" / "{email}"
- Website hero headline: "{Headline}"
- Packaging label: "{Product Name}" / "{Tagline}"
For brand names with uncommon spellings, spell letter-by-letter
in a comment: "spell as L-U-X-I-O not LEXIO", the model
otherwise auto-corrects toward common spellings.

STYLE LOCK: flat vector, {2-3 color palette restated}, no
shadows, no gradients, no skeuomorphism, no stock-photo
overlays, no decorative illustrations beyond the named motif, no people unless explicitly listed in the asset description.

OUTPUT: 8 panels in ONE batch. Label each panel with its asset
name as a caption underneath (gpt-image-2 caption rendering is
reliable in 2026).

VARIANT WORKFLOW, for iteration, vary ONE dimension at a
time across batches:
- Batch A: palette variant, same layout, three palette options
- Batch B: typography variant, same palette, three type-feel
  options
- Batch C: motif variant, same palette and type, three motif
  shapes
Apples-to-apples comparison is what makes brand-direction
decisions tractable. NEVER vary 3 dimensions at once, you
can't tell which change drove the improvement.

INPUTS:
- Brand name: {name}
- Brand archetype / vibe: {1 sentence, e.g. "premium outdoor
  gear for cold-climate hikers, technical and quiet"}
- Color palette (hex): {2-3 colors with semantic role}
- Typography feel: {one family description}
- Motif: {one repeated visual element}
- Required assets (pick from list above, max 8): {list}
- Contract text per asset: {labeled list}

REPEAT INVARIANTS HERE AS LAST LINE:
Palette: {hex codes}. Type: {family}. Motif: {shape}. One
family, no extra colors, named motif at varied scale, flat
vector across all 8 panels.

Why: Three things make this the killer paste-ready prompt for the gpt-image-2 launch in April 2026 and a genuine new entry rather than overlap with the existing logo entries: (1) the 8-panel batch with Thinking Mode is a NEW primitive that didn't exist in DALL·E / GPT Image 1.5, generating a logo, business card, IG story, and website hero in ONE call with locked palette/type/motif was previously a 2-day Figma exercise; this formula encodes the discipline (restate invariants at top AND bottom; vary one dimension per batch; spell uncommon brand names letter-by-letter) that turns the capability into a reliable workflow rather than a coin flip. (2) The restate-invariants-at-the-end rule targets the specific failure mode of gpt-image-2, the model holds palette/type across panels 1-4 cleanly and then drifts on panels 5-8 if invariants are stated only at the top; restating at the bottom is the field-tested fix from the OpenAI cookbook + Atlas Cloud / Mew Design practitioner reports. (3) The "vary one dimension at a time across batches" iteration discipline is what makes brand-direction decisions tractable instead of an endless "I changed three things, which one helped?" cycle. Distinct from the existing Logos & Branding entries: minimalist is single abstract logo, monogram is single text mark, healthcare is single service logo, mascot consistency is ONE CHARACTER across scenes, this fills the *brand system across asset types* slot the section completely missed and which gpt-image-2 is the first model that can deliver in one shot. | Use when: Standing up brand identity for a new product/startup, refreshing an existing brand and need to see logo + signage + business card + web + social in one comparable batch before committing to a direction, generating launch collateral fast where consistency matters more than pixel-perfection (designer can polish the chosen direction in Figma after), or producing client pitch decks with three palette variants of the same asset set side-by-side. Pairs with the existing minimalist logo formula (use that to design the canonical mark first, then run this to populate the system around it) and the mascot system consistency formula (this handles the wordmark/lockup/asset side; that handles the character side).

I have a prompt that isn't producing reliable output. Rewrite it. Do NOT
just polish the wording, apply the four mechanical upgrades that move a
prompt from "vibes" to "spec":

1. STRUCTURAL CLARITY. Split into labeled sections: role, context, task, constraints, output format. Every sentence belongs in exactly one
   section, delete any that doesn't. Put input variables in {curly
   braces} so the prompt is reusable, not single-use.

2. CHAIN-OF-THOUGHT SCAFFOLD. Add an explicit <thinking> block before
   the answer where the model walks through what it knows, what it's
   assuming, and the steps it will take. For decision tasks: enumerate
   the criteria and apply each one in order. For extraction tasks:
   name the fields and the source span each one came from. Invisible
   reasoning is the #1 silent failure mode, make it visible.

3. PREFILL THE ASSISTANT TURN. If the output must follow a format
   (JSON, table, specific section headers), prefill the first line of
   the assistant message: `{` for JSON, `| header |` for a markdown
   table, `## Section 1` for a structured report. Prefill stops
   format drift in its tracks.

4. EXAMPLE STANDARDIZATION. If examples are present, every example
   must demonstrate the same thinking structure as the output you
   want. If examples are absent and the task has any ambiguity, add
   1-3. Wrap each in <example>...</example>. Match naming, capitalization, punctuation, and section headers EXACTLY to the
   target output, the model replicates trivial formatting choices
   from examples.

For EACH upgrade, state in one sentence WHY (what failure mode it
kills). If an upgrade doesn't apply, say "not needed" and why. Final
output: the rewritten prompt PLUS a numbered diff list of what changed.

Original prompt:
{paste the prompt that isn't working}

Observed symptoms (optional but valuable):
{e.g. "format drifts after example 3" / "leaves the JSON unclosed" /
"refuses to answer when input is empty" / "ignores the no-markdown rule"}

Why: These four mechanical upgrades, structural clarity, CoT scaffold, prefill, example standardization, are exactly the levers Anthropic's official prompt improver pulls in Console (the tool that lifted accuracy 30% on multilabel classification and brought word-count adherence to 100% on summarization in their published tests). Distinct from the CRTSE structure entry above: CRTSE describes the *shape* of a good prompt; this is the *algorithm for getting there from a broken one*, with the diagnostic step that names which failure mode each upgrade kills. The "state WHY per upgrade" rule turns the rewrite into a teaching moment, you see the failure mode, not just the patch. | Use when: A prompt that worked last week is flaky, the model keeps missing one section, output drifts away from your format, or you're about to canonicalize a prompt as a reusable template and want one final pass on structure before committing. Pairs with CRTSE: design with CRTSE, debug with this.

You are running a Chain-of-Verification (CoVe) pass on a draft to reduce
hallucinations. Use the FACTORED + REVISE variant, the verifier must
NOT see the draft, otherwise it copies the draft's hallucinations
instead of catching them. Execute phases strictly in order. Do not
collapse phases to save tokens, collapsing is what makes CoVe fail.

1. CLAIM EXTRACTION. From the draft, list every atomic factual claim, one per line, numbered. Atomic means: a single subject + a single
   asserted fact. If a sentence makes three claims, output three
   numbered lines. Skip claims that restate my premise, only extract
   claims the draft ASSERTS. Do not paraphrase: paraphrased claims
   hide hallucinations inside the rewrite.

2. VERIFICATION QUESTIONS. For each numbered claim, generate ONE
   independently-checkable question that would confirm or refute it.
   Questions must:
   - Be answerable yes/no or with a single fact (not open-ended)
   - NOT quote the draft's wording (forces independent recall, not
     pattern-matching to the draft)
   - Be self-contained (no "as above", no "the same person")

3. INDEPENDENT VERIFICATION, CRITICAL FACTORING STEP. Open a fresh
   context. Forget the draft entirely. Answer each verification
   question one at a time, using ONLY {your training knowledge | the
   attached sources | a web search, pick one and state which}. Output
   a table:
   | # | question | answer | confidence (high/med/low) | source if cited |
   If you find yourself referencing the draft to answer, you've broken
   the factoring, restart that question with the draft excluded.

4. RECONCILE. Compare the original claims to the independent answers.
   Mark each claim:
   - CONFIRMED, verification matches
   - REFUTED, verification contradicts; produce the correct fact
   - UNCERTAIN, verifier couldn't answer or low-confidence; flag for
     human review, do NOT fabricate confidence to close the loop

5. REVISE. Rewrite the draft with REFUTED claims corrected (or
   removed if no correct version exists), UNCERTAIN claims marked
   inline as [UNVERIFIED, {what couldn't be checked}], CONFIRMED
   claims kept verbatim. End with a "Verification notes" section
   listing every correction made and the question that caught it.

HARD RULES:
- Do NOT skip step 1. Atomic claim extraction is what makes step 3
  independent, every shortcut here lets a hallucination through.
- Do NOT answer multiple verification questions in one breath. Per
  the Meta CoVe paper, the FACTORED variant (one question per
  context) catches errors the joint variant misses because the joint
  variant lets earlier hallucinations bias later answers.
- An UNCERTAIN is a feature, not a failure. Flag it. Don't smooth.

Draft to verify:
{paste}

Verification source for step 3:
{training knowledge | attached docs | web search, pick one}

Why: Encodes the FACTORED + REVISE variant from Meta's CoVe paper (arxiv 2309.11495), the variant that delivered the best accuracy across FACTOR / Wikidata / MultiSpanQA in the original benchmarks, because answering verification questions in independent contexts prevents the model from copying its own hallucination. Three things make this distinct from the existing Meta entries: (1) CRTSE describes the *shape* of a good prompt and the meta-prompt rewriter is the *algorithm for fixing a broken prompt*, neither addresses hallucination in *output*, which is the production failure mode that survives a perfectly-structured prompt. (2) The "verifier must not see the draft" rule with a restart-on-violation directive is the operational discipline that turns CoVe from a research technique into a paste-ready workflow, the joint variant (verifier sees the draft) is what most informal "ask the model to double-check itself" prompts default to, and it's the variant the paper showed *fails to reduce hallucinations* because the model just confirms whatever it already said. (3) The UNCERTAIN tier with the "do NOT fabricate confidence" rule preserves the actual signal, most self-check prompts let the model collapse uncertainty into a confident-sounding final answer, which is worse than the original because it now has the appearance of having been verified. | Use when: Any draft that asserts facts you can't immediately verify yourself, research summaries, API reference content the model is improvising, vendor comparisons, anything where the cost of a single wrong fact is high (legal, medical, financial, technical documentation). Pairs with the meta-prompt rewriter above, that one fixes a prompt that produces inconsistent FORMAT; this one verifies the CONTENT of an output that's correct in format but possibly wrong in fact.

You are evaluating whether an assistant's response is FAITHFUL to a
retrieved context passage. Faithful means every factual claim in the
response is directly and explicitly supported by the context. A claim
is UNFAITHFUL if it is added, modified, paraphrased into something
stronger, or drawn from outside the context.

Steps, execute in order, do not skip:

1. ENUMERATE EVERY CLAIM. List each factual claim in the response on
   its own line, numbered. Treat each of these as a SEPARATE claim:
   numbers, rules, entity names, negations ("X does not Y"), comparisons ("X is larger than Y"), conditions ("if A then B"), and any evaluative or comparative phrase about a quantifiable
   property ("the refund window is generous" is a claim that the
   underlying quantity must support).

2. SUPPORT CHECK PER CLAIM. For each numbered claim, locate the
   SPECIFIC sentence in the context that supports it. Quote the
   sentence. If no sentence supports the claim, say so explicitly, do NOT paraphrase the context to make it fit.

3. EDGE CASES, apply each rule deterministically:
   - TRUNCATED CONTEXT (ends mid-sentence): counts as zero support
     for any claim that would have required the cut-off material.
   - EMPTY CONTEXT: every external claim is unfaithful by definition.
   - REFUSAL ("I cannot answer that from the provided context"):
     faithful if the context genuinely does not contain the answer.
   - CROSS-DOCUMENT ATTRIBUTION: a claim that is true elsewhere but
     not in THIS retrieved passage is unfaithful, the unsupported_claims
     list MUST surface it; do NOT smooth.

4. VERDICT RULE, mechanical, no judgment:
   - If ANY enumerated claim has no direct support, verdict = "unfaithful".
   - Otherwise verdict = "faithful".

Return JSON exactly:
{
  "verdict": "faithful" | "unfaithful", "unsupported_claims": ["", ...], "reason": ""
}

HARD RULES, these prevent the failure modes calibration runs surface:
- Enumerate BEFORE scoring. Reverse order lets the model commit to a
  verdict and rationalise backward.
- Run at temperature=0. Non-zero temperature on a verdict task adds
  variance you cannot interpret.
- Do NOT evaluate relevance, fluency, or format here, those are
  separate judges. Mixing dimensions produces correlated scores you
  cannot attribute to a regression.
- Do NOT copy any generator system-prompt persona ("you are a helpful
  assistant…") into this judge. The judge has one job: apply the rubric.
- "Use your judgment" appears nowhere, every step is a deterministic rule.

CONTEXT:
{context}

RESPONSE:
{response}

Why: Three things make this distinct from the existing Prompt Engineering Meta entries: (1) CRTSE describes the *shape* of a good prompt, Meta-prompt rewriter is the *algorithm for fixing a broken prompt*, and Chain-of-Verification has the model verify its OWN output for hallucinations, none address the LLM-as-JUDGE failure mode, where a model is used as an automated third-party grader to gate other LLM features (RAG faithfulness, agent tool correctness, format compliance, relevance) in production. That's the gating loop every production LLM team has to build by mid-2026 and the entry the Meta section was missing. (2) The 4-part structure (criterion definition in domain vocabulary / explicit reasoning that ENUMERATES discrete units before scoring / deterministic scoring rule / edge case handling for the cases retrieval pipelines actually produce, truncated context, empty retrieval, refusals, cross-document attribution) is the load-bearing skeleton Galtea identified through calibration against multi-customer gold sets, skip any of the four and the judge falls back to "does this look faithful?" plausibility checks that miss the failures that matter. (3) The unsupported_claims list in the output schema is the kill-shot for cross-document attribution, the most common faithfulness-judge failure mode where a fact is true elsewhere but not in THIS retrieved passage; a judge returning only `{"verdict": "unfaithful", "reason": "..."}` papers over it, but a judge that has to populate the list surfaces it. The "enumerate BEFORE scoring" rule kills the post-hoc-rationalisation failure mode where the model commits to a verdict and constructs reasoning to fit. The "strip the generator persona" and "no 'use your judgment'" rules kill the two most common silent calibration-killers. Distinct from Chain-of-Verification: CoVe is the model checking ITS OWN output and asking "did I just make this up?"; this is a separate model scoring a third party against a rubric and gating deploys on the verdict. | Use when: Building an automated eval/scoring system that gates LLM features in production, RAG faithfulness gates, agent tool-call correctness scoring, format-compliance checks beyond what JSON schema can catch, relevance scoring for chat/QA. Adapt the same 4-part skeleton (criterion / enumerate / verdict rule / edge cases) for relevance (decompose query into intents, including NEGATIVE constraints; mark each intent addressed/not-addressed), format compliance (list required and prohibited elements; do NOT evaluate aspects not listed), and agent tool correctness (score selection, arguments, and trajectory coherence as THREE separate judges, not one mega-judge). Pairs with the existing Chain-of-Verification entry (CoVe is for the producer-side hallucination check on a draft; this is the consumer-side gate that decides whether a system's outputs ship) and with the LLM provider snapshot rollout discipline in Workflow & Automation (the behavioral-eval slice that prompt's Phase 1 requires is exactly the kind of judge this template produces).

You are a senior engineer with 15+ years in {language}. Review the code below.
Walk through it function-by-function using chain-of-thought.
For each issue, output: severity (blocker / major / minor / nit), category
(bug / security / perf / readability / api design), the exact line(s), the problem stated in one sentence, and the fix as a code diff.
Do not rewrite the whole file. Do not be polite, be precise.

Why: Forces structured output you can actually action. The severity tag makes triage trivial. | Use when: Pre-merge review on a non-trivial PR, or before pushing your own work.

Build a {METHOD} {path} endpoint in {Node|Python|Go} on {framework}.
Output THREE separate files: route handler, service, repository.
Requirements: input validation with {zod|pydantic|...}, {JWT|API key|session} auth, typed return values, error responses follow RFC 7807, structured logging at
boundaries, no business logic in the handler. End with a 5-line README block
explaining where to add each new piece.

Why: Most AI scaffolds smash everything into one file. This enforces real layering from the start. | Use when: Spiking a new endpoint you'll keep, not just prototyping.

I want to {goal}. Don't write code yet. Output:
1. Acceptance criteria (bulleted, testable).
2. The plan as a numbered list of small diffs (each <100 lines).
3. The riskiest step and why.
4. What you'd test first.
Then stop. Wait for me to approve before writing any code.

Why: The single biggest unlock for senior-quality output is forcing a plan before code. Anthropic's internal data: unguided attempts succeed ~33%; planned attempts much higher. | Use when: Anything non-trivial. Default to this for new features.

You just finished implementing {feature}. Before I commit, review this diff
not as the author but as an attacker trying to break it in production.
Answer each question against the actual code, citing line numbers:
1. What happens if this runs twice concurrently? Where's the lock or idempotency key?
2. What if every input is null, empty string, negative, or wildly oversized?
3. Which assumptions am I making about external services (DB, API, queue) that
   could be wrong? What's the failure mode for each?
4. Is there any hard-coded value (string, magic number, env var) that should
   be a constant, enum, or config?
5. Would I be embarrassed if this broke on a Saturday at 2am?
For each issue: severity (blocker/major/minor), the exact line, and the
minimal fix as a diff. If you find nothing, say so, don't manufacture issues.

Why: Forces the model into attacker mode against its OWN output, catches the race conditions, null derefs, and hard-coded strings that tests miss. The "2am on a Saturday" framing surfaces operational risk the rest of the checklist misses. | Use when: After the AI says "done" but before you actually commit. Especially for anything touching state transitions, money, or auth.

Here is a system design: {paste or describe}. Critique it on:
- Separation of concerns
- Scalability bottlenecks (identify the first 3 to hit)
- Single points of failure
- Testability
- Operational complexity vs. the value it delivers
For each issue: state the problem, the blast radius, and 2 alternative designs
with trade-offs. Rank issues by impact, not by where they appear in the doc.

Why: Forces ranked, comparative critique instead of a generic "looks good". | Use when: Reviewing an ADR or a design doc before sign-off.

Generate {Jest|pytest|...} tests for the function below. Rules:
- Test behavior, not implementation.
- Cover happy path, every error branch, and at least 3 edge cases
  (empty input, max boundary, malformed type).
- Mock external IO; do not hit the network.
- Follow the existing test style in this file: {paste a sample test}.
- No snapshot tests. No tests that just assert "function was called".
End with a list of cases you *didn't* write and why.

Why: "List what you didn't test and why" is the killer line, surfaces coverage gaps you'd otherwise miss. | Use when: Adding tests to legacy code or freshly written functions.

I have this bug: {symptom}. Stack trace: {paste}. Recent changes: {paste git log}.
Do not propose a fix yet. First:
1. Smallest reproduction you can describe.
2. Three hypotheses for the root cause, ranked by likelihood, each with the
   single experiment that would confirm or refute it.
3. The piece of evidence you would most want to see next.
Then stop.

Why: Stops the AI from leaping to a "fix" that papers over the real bug. | Use when: The cause isn't obvious in the first 5 minutes.

Generate reference docs for this endpoint: {paste handler}. Output:
- One-sentence purpose
- Request: method, path, headers, body schema with field-by-field meaning
- Response: success shape + every error shape with status code and when it fires
- Auth requirements
- Side effects (DB writes, queued jobs, emails)
- One copy-pasteable curl example for the happy path
- One example for each error case
Tone: terse, no marketing voice.

Why: "Side effects" and "tone: terse, no marketing voice" are the bits most generators miss. | Use when: Closing the docs ticket that always slips.

You are running unattended. Each run:
1. Pull the diff since the last successful run from {branch}.
2. Flag: new TODO/FIXME, new dependency additions, changes to auth/crypto code, any new env vars without a default.
3. If nothing notable, output a one-line "no findings" log and exit.
4. If findings exist, open/update an issue titled "Nightly audit: {date}"
   with sections per flag type.
Never modify code. Never push. Output only.

Why: The hard part of headless work is *not* doing more than you should. This bakes in restraint. | Use when: Nightly CI-adjacent jobs, dependency monitoring, repo hygiene.

You are the supervisor. The task: {goal}.
Decompose into subtasks. For each subtask, decide whether to do it yourself
or delegate to one of: {researcher, coder, reviewer, tester}.
Before delegating, write the subagent's prompt as if it has no memory of this
conversation: include the goal, the inputs, the output format you want back, and the success criteria. Then call the subagent. Aggregate results. If two
subagents disagree, surface the disagreement with both arguments before
resolving.

Why: The "write the subagent's prompt as if it has no memory" rule prevents the most common multi-agent failure. | Use when: Building anything agentic where work fans out.

{Shot type + angle} of {subject + descriptor} {action/posture} in {environment}, {lighting direction + quality}, {atmospheric element: fog/dust/rain/god rays}, {color grade: e.g. teal-and-orange / blue-hour / golden-hour}, shot on {focal length} lens at f/{aperture}, {composition rule}.
--ar 16:9 --style raw --s 200

Why: Forces all 5 slots a real DP would think about, shot, lighting, atmosphere, grade, lens, instead of vibes. The `--style raw` + `--s 200` floor on MJ v7 keeps it photographic rather than drifting to illustration. | Use when: Hero images, header art, story-driven shots. Works on MJ v7, Nano Banana Pro, and ChatGPT image gen (drop the MJ flags for the latter two).

{Subject} {action} in {environment}. {Composition: e.g. centered close-up, rule of thirds}.
Three-point softbox lighting, {key light direction}, soft shadows.
Shot on {camera body} with {35mm|50mm|85mm} lens at f/{1.8|2.8|4}, shallow depth of field, {ISO}, {time of day}.
Photorealistic, sharp focus on {focal point}, natural skin texture, no plastic look.
--style raw --s 100 --ar 4:5

Why: The "three-point softbox", explicit f-stop, and "no plastic look" disclaimer are the three lines that actually push Nano Banana / MJ from "AI render" to "looks like a product shoot". The Subject + Action + Scene + camera + realism-trigger order is Google's official formula for Nano Banana Pro. | Use when: Product photography, headshots, anything where the eye needs to read it as a real photograph, not an illustration.

Minimalist vector logo of {subject}, {style adjective: geometric / organic / brutalist}, flat design, {2-3 color palette}, white background, {designer reference, e.g. Paul Rand
/ Saul Bass / Massimo Vignelli} style, simple lines, no shading, no text, vector illustration --ar 1:1 --no realistic photo details, photography, gradients

Why: Five parts that actually matter for logos: type + subject + style + palette + reference. The `--no` clause is critical, without it MJ drifts to "art" not "logo". | Use when: First-pass logo exploration. Output is raster; vectorize via Vectorizer.ai or Illustrator's Image Trace.

Minimalist {industry} logo for a {sub-vertical}, {abstract concept} symbol, flat vector style, clean lines, {color palette: e.g. soft blue and white}, modern and professional mood, centered composition --ar 1:1

Why: Drops in cleanly for any service-business logo. The "abstract concept" slot is where the brief lives. | Use when: Client work where the symbol needs to feel meaningful but not literal.

Context: {one paragraph of what's true about the world this lives in}
Role: {who the model is acting as}
Task: {the single deliverable}
Standards: {bulleted constraints, style, length, what to avoid}
Examples: {1-3 input/output pairs if format matters}

Why: When a prompt isn't working, run it through this checklist, usually you're missing Standards or Examples. | Use when: Building a reusable prompt template or debugging a flaky one.