From e366ce9fcd0b8c53a581ede7ac3ed303a470b6ad Mon Sep 17 00:00:00 2001
From: Younggi Choi <74581798+choiyounggi@users.noreply.github.com>
Date: Sat, 22 Aug 2026 00:24:55 +0900
Subject: [PATCH] wiki: transplant methodology from retired
 superpowers/compound-engineering plugins

8 new pages, 3 amended, 4 domain indexes + root INDEX updated.

New: testing/strategy/failing-test-first, testing/strategy/cross-layer-effect-tests,
qa/process/completion-claims, qa/process/evaluating-review-feedback,
qa/process/adversarial-change-review,
infrastructure/agent-orchestration/autonomous-decision-rulings,
backend/common/llm/binding-instructions-for-agents,
backend/common/api-design/agent-tool-granularity.

Amended: debugging/methodology/hypothesis-testing (+2 edge rows),
databases/data-survey/surveying-live-data-for-a-rule (+1 edge row),
debugging/methodology/verify-the-fix (repairs dangling failing-test-first pointer).

Gap-analyzed against full skill inventories of superpowers 6.3.0 and
compound-engineering 2.63.1 before ingest; already-covered triggers were not
duplicated (see log.md entry for the skip list). Lint: prohibitions 71/71,
structure 260 pages / 13 indexes / 0 findings. Independent format/source
review passed (3/3 spot-checked citations accurate).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YVRX97mdBwFtyMwK44viEd
---
 INDEX.md                                      |  8 +--
 log.md                                        |  1 +
 .../api-design/agent-tool-granularity.md      | 67 +++++++++++++++++
 .../llm/binding-instructions-for-agents.md    | 67 +++++++++++++++++
 wiki/backend/index.md                         |  2 +
 .../surveying-live-data-for-a-rule.md         |  2 +
 .../methodology/hypothesis-testing.md         |  3 +
 wiki/debugging/methodology/verify-the-fix.md  |  4 +-
 .../agent-facing-tool-surfaces.md             |  4 +-
 .../autonomous-decision-rulings.md            | 62 ++++++++++++++++
 .../control-signals-vs-primary-artifacts.md   |  2 +-
 .../unattended-worker-questions.md            |  2 +-
 wiki/infrastructure/index.md                  |  1 +
 wiki/qa/index.md                              |  8 ++-
 wiki/qa/process/adversarial-change-review.md  | 66 +++++++++++++++++
 wiki/qa/process/completion-claims.md          | 61 ++++++++++++++++
 .../defect-class-resweep-after-review.md      |  4 +-
 wiki/qa/process/evaluating-review-feedback.md | 70 ++++++++++++++++++
 wiki/testing/index.md                         |  9 ++-
 .../testing/quality/tests-that-cannot-fail.md |  2 +-
 .../strategy/cross-layer-effect-tests.md      | 56 +++++++++++++++
 wiki/testing/strategy/failing-test-first.md   | 71 +++++++++++++++++++
 wiki/testing/strategy/test-level-choice.md    |  2 +-
 23 files changed, 555 insertions(+), 19 deletions(-)
 create mode 100644 wiki/backend/common/api-design/agent-tool-granularity.md
 create mode 100644 wiki/backend/common/llm/binding-instructions-for-agents.md
 create mode 100644 wiki/infrastructure/agent-orchestration/autonomous-decision-rulings.md
 create mode 100644 wiki/qa/process/adversarial-change-review.md
 create mode 100644 wiki/qa/process/completion-claims.md
 create mode 100644 wiki/qa/process/evaluating-review-feedback.md
 create mode 100644 wiki/testing/strategy/cross-layer-effect-tests.md
 create mode 100644 wiki/testing/strategy/failing-test-first.md

diff --git a/INDEX.md b/INDEX.md
index 8f59d1a..75ed45f 100644
--- a/INDEX.md
+++ b/INDEX.md
@@ -12,11 +12,11 @@ follow the cross-pointers in their index or take the next matching seeded domain
 | Domain | Status | Route here when |
 |--------|--------|-----------------|
 | [databases](wiki/databases/index.md) | **seeded** | Designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior, surveying live data to derive a rule, verifying additive migrations |
-| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), MAPE-aligned point-prediction calibration, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
+| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), authoring agent-facing artifacts (binding instruction text, agent tool-surface granularity/parity), MAPE-aligned point-prediction calibration, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
 | [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility, agent-facing tool surfaces (WebMCP) |
-| [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting), per-environment/path-valued config, multi-agent orchestration (worker liveness signals, shared run state, tmux pane delivery, completion gates, worktree-isolated workers) |
-| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, cases/assertions, test data, mock decisions, flaky tests (release-process quality → qa) |
-| [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, exploratory testing (guarded-path coverage, override matrices), scope-purity gates, sourcing deliverable documents from generated artifacts, verifying the quantitative claims in a document before publishing it, automated verification of document deliverables (spec/RFC gates) (writing automated test code → testing) |
+| [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting), per-environment/path-valued config, multi-agent orchestration (worker liveness signals, shared run state, tmux pane delivery, completion gates, worktree-isolated workers, autonomous ask-vs-rule decisions) |
+| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, test-before-code ordering, cases/assertions, cross-layer effect scoping, test data, mock decisions, flaky tests (release-process quality → qa) |
+| [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, evidence for completion claims, acting on code-review feedback, adversarial review of high-risk diffs, exploratory testing (guarded-path coverage, override matrices), scope-purity gates, sourcing deliverable documents from generated artifacts, verifying the quantitative claims in a document before publishing it, automated verification of document deliverables (spec/RFC gates) (writing automated test code → testing) |
 | [debugging](wiki/debugging/index.md) | **seeded** | Diagnosing a failure — finding what is wrong and why: reproducing, bisection, hypothesis testing, traces/logs, intermittent failures (fixing the diagnosed fault → its owning domain) |
 | [security](wiki/security/index.md) | **seeded** | Trust-boundary decisions: input validation, session-vs-token auth choice, per-resource authorization (IDOR), secrets hygiene, dependency trust, PII handling, in-session agent tool exposure (prompt-injection blast radius), the author identity a commit publishes to a public repository, host-compromise triage / incident response (verifying assumed security agents, identifying masquerading processes) (XSS rendering → frontend; CI secrets → infrastructure; JWT implementation → backend/frontend auth) |
 | [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning |
diff --git a/log.md b/log.md
index 2def3c4..1247435 100644
--- a/log.md
+++ b/log.md
@@ -95,3 +95,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-08-20] ingest | Frontend visual-design knowledge (2 new pages, NEW category frontend/design). frontend/design/anti-slop-visual-design (field-tested — distilled from hallmark skill v1.1.0, which encodes Anthropic's frontend-design skill + Claude cookbook frontend-aesthetics consensus: decision order with structure-before-visuals as the core claim — the AI tell is structural repetition, not color choice; OKLCH token discipline with the one-accent ≤3% rule and no-pure-extremes; roman-headings + display/body pairing typography; transform/opacity-only motion with the 8-state interactive floor; fabricated-metrics honesty rule; a tells table covering gradient heroes, equal 3-column grids, 100vh centered heroes, genre-blind nav/footer fingerprints, redrawn browser/phone chrome, Lottie/Three.js shortcuts, lazy-loaded LCP, and eyebrow-label decoration). frontend/design/html-in-canvas (verified — WICG html-in-canvas draft: layoutsubtree / drawElementImage / texElementImage2D / copyElementImageToTexture / paint-event API surface, the mandatory returned-transform hit-test sync, the dual DOM+pixels model, and a progressive-enhancement-only stance; status live-checked this session against the WICG repo and the blink-dev intent thread — behind chrome://flags/#canvas-draw-element since Chrome 138 (Dec 2025) dev trial, Origin Trial since Chrome 148 (May 2026)). frontend/index.md routing intro extended with visual-design scope and a new design section. Prohibition-lint directive count unchanged at 71; structure checks 244 pages / 13 indexes / 0 findings.
 ## [2026-08-21] ingest | frontend/design/responsive-layout (verified — 1 new page). Mobile-responsive layout contract for viewport-range UI: exact viewport meta with zoom left enabled (~980px virtual-viewport mechanism; user-scalable=no blocks the ≥2× WCAG zoom and iOS ignores it — MDN Viewport_meta_element), mobile-first min-width layering with content-driven breakpoints (web.dev responsive-web-design-basics), intrinsic grids repeat(auto-fit, minmax()) before media queries (web.dev patterns) and @container with intrinsic fallback (MDN), touch targets 24px AA SC 2.5.8 / 44px AAA SC 2.5.5 with the 24px-circle spacing exception (W3C Understanding docs), clamp() fluid type gated on a 200%-zoom check (1.4.4, web.dev min-max-clamp), srcset/sizes + width/height CLS reservation (MDN img), the min-width:auto→min-content overflow mechanism fixed by minmax(0,1fr) (MDN min-width), and edge cases for 100vh-vs-dvh/svh, hover:none long-tap emulation, and viewport-fit=cover + env(safe-area-inset) (WebKit blog). 320px no-horizontal-scroll final gate = SC 1.4.10. All 14 cited URLs live-fetched and verified this session by a research subagent; Apple HIG 44pt / Material 48dp figures deliberately NOT cited (JS-rendered pages unverifiable — WCAG carries the target-size claims); rem-vs-px media-query sub-claim omitted as unverified. related links added both ways (anti-slop-visual-design, accessibility/interactive-elements, performance/bundle-and-assets). frontend/index.md design section +1 row, routing intro extended with responsive-layout scope.
 ## [2026-08-21] revise | frontend/design/anti-slop-visual-design +2 sources / +5 directive rows / +1 edge case (theme-defaults reinforcement). Primary source added: Anthropic Engineering "Improving frontend design through Skills" (claude.com/blog, 2025-11-12; live-fetched — the velog.io/@xxziiko post the contributor supplied is its Korean translation, cross-checked as matching). New Anthropic-backed material: named avoid-list of training-data default fonts (Inter/Roboto/Open Sans/Lato/system) with the distributional-convergence mechanism, feel-category font taxonomy (code/editorial/technical), second-order convergence warning (Space Grotesk as "the new Inter" — vary the escape choice per project), quantified extreme-contrast thresholds (weight 100–200 vs 800–900, 3×+ size jumps), dominant-field + sharp-accent palette framing with IDE-theme/cultural-aesthetic inspiration, domain-derived aesthetic direction folded into the tone-extreme step (non-generic direction reframed as the DEFAULT), motion-budget allocation (one staggered page-load orchestration over scattered micro-interactions), and a right-altitude edge case for writing reusable design guidance (axes + decision logic, no hex hardcoding, no "make it look good"). Aurora-blob Instead-of row reconciled with Anthropic's atmospheric-background endorsement: the tell is ungrounded decoration on a neutral page, theme-earned depth passes. Impeccable README (github.com/pbakaus/impeccable, live-fetched) adds gray-text-on-colored-background and bounce/elastic-easing anti-patterns; tistory.com/1624's deeper Impeccable quotes NOT ingested (cited SKILL.md path 404s — repo restructured; command vocabulary unstable 17→23, only README-level rules taken). Also deliberately skipped: 16px body floor and "adapt don't delete" (third-party, no mechanism, unverifiable primary). frontend/index.md load-when extended (theme direction as default, LLM design-guidance authoring). Prohibition directives unchanged at 71; structure 252/13/0; body 85 lines.
+## [2026-08-22] ingest | Methodology transplant from two retired plugins (superpowers 6.3.0, compound-engineering 2.63.1) — 8 new pages, 3 amended pages, 4 domain indexes + root INDEX updated. Both plugins were disabled locally for context-budget reasons; their full skill/agent inventories were read and gap-analyzed against the wiki before ingest, so only triggers the wiki did not already own were taken (systematic-debugging's phases, verify-RED mutation proof, and status-vs-artifact distrust were all found already covered — by debugging/methodology, testing/quality/tests-that-cannot-fail, and infrastructure/agent-orchestration/control-signals-vs-primary-artifacts respectively — and were NOT duplicated). New: testing/strategy/failing-test-first (Canon TDD ordering, verify-RED for the expected reason, mirror-assertion ban, delete-code-written-before-its-test; also repairs verify-the-fix's previously unresolvable "failing-test-first rule: wiki/testing/" pointer), testing/strategy/cross-layer-effect-tests (CE "System-Wide Test Check": trace two levels out, real-chain requirement, orphaned-state case, sibling-surface parity, error-strategy alignment, explicit skip condition), qa/process/completion-claims (fresh-evidence gate, claim→evidence table incl. subagent self-report distrust routed to control-signals, hedge-word markers), qa/process/evaluating-review-feedback (verify-findings-before-implementing, clarify-all-before-any, YAGNI usage grep, performative-agreement replacement, resweep handoff; Google eng-practices cited for facts-over-opinion and over-engineering vigilance), qa/process/adversarial-change-review (depth calibration by size/risk; four scenario-construction techniques — assumption violation, composition, cascade, abuse; scenario-named findings; advisory-to-human routing), infrastructure/agent-orchestration/autonomous-decision-rulings (four stop-and-ask categories vs rule-and-record with cost-if-wrong ledger; ledger-over-memory resume), backend/common/llm/binding-instructions-for-agents (baseline-fails-first wording tests, form-matched-to-failure table incl. the measured prohibition-backfire result for wrong-shape failures, nuance-clause degradation, description-as-trigger-only), backend/common/api-design/agent-tool-granularity (UI/agent parity capability map, tools-as-primitives vs workflow-shaped tools, CRUD completeness, explicit completion signal, shared data space, composition test). Amended: debugging/methodology/hypothesis-testing +2 edge rows (3-failed-fixes architecture circuit breaker; instrument-every-boundary-then-run-once) + superpowers source; databases/data-survey/surveying-live-data-for-a-rule +1 edge row (hand-transcribed mapping tables verified entry-by-entry — transposed entries survive spot checks) + CE data-migration-expert source; debugging/methodology/verify-the-fix regression-test row now links [testing-strategy-failing-test-first], related +failing-test-first +completion-claims. Related links added both ways (tests-that-cannot-fail, test-level-choice, unattended-worker-questions, control-signals-vs-primary-artifacts, defect-class-resweep-after-review, frontend agent-facing-tool-surfaces). Deliberately skipped as already-covered or out-of-layer: superpowers brainstorming/writing-plans/executing-plans (workflow layer — wiki-plan/loop-implement own it), using-git-worktrees mechanics (partially covered by worktree-isolated-workers; native-tool preference is harness-specific), dispatching-parallel-agents (orchestrate skill), CE frontend-design (frontend/design/anti-slop-visual-design already ingested from hallmark), CE ce:compound/ce:review pipeline mechanics (dev-loop's ingest/review skills own the equivalent), CE Rails-specific personas.
diff --git a/wiki/backend/common/api-design/agent-tool-granularity.md b/wiki/backend/common/api-design/agent-tool-granularity.md
new file mode 100644
index 0000000..79f285a
--- /dev/null
+++ b/wiki/backend/common/api-design/agent-tool-granularity.md
@@ -0,0 +1,67 @@
+---
+id: backend-common-api-design-agent-tool-granularity
+domain: backend
+category: api-design
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/EveryInc/compound-engineering-plugin
+  - https://www.anthropic.com/engineering/building-effective-agents
+last_verified: 2026-08-22
+related: [frontend-agent-interfaces-agent-facing-tool-surfaces, backend-common-llm-binding-instructions-for-agents]
+---
+
+# Choosing the Tool Surface an In-App LLM Agent Calls
+
+## When this applies
+
+Adding agent capabilities to an application — an MCP server, a
+function-calling tool list, plugin tools; deciding between exposing a
+workflow function and exposing primitives; an agent cannot perform an action
+the UI offers; reviewing a tool list for an agent feature.
+
+## Do this
+
+1. Build a capability map — every UI action paired with its agent-tool
+   equivalent — and close the gaps: an action reachable in the UI but not by
+   the agent caps the agent at chatbot, answering questions about work it
+   cannot do.
+2. Expose atomic primitives (create/read/update/delete/list, send, search)
+   and implement features as prompts that compose them in an agent loop.
+   Business workflow baked into one tool (`process_feedback` doing
+   categorize + prioritize + store + notify in code) fixes every decision at
+   build time — expose `store_item` and `send_message`, and let the prompt
+   own the workflow.
+3. Complete each resource's CRUD: a tool set that can create but not list,
+   update, or delete strands the agent mid-task, in a state only a human can
+   clean up.
+4. End agent tasks with an explicit completion tool (`complete_task`) rather
+   than heuristic detection (silence, phrase matching) — heuristics
+   misclassify pauses as completions and completions as pauses.
+5. Run the agent in the user's own data space, and reflect agent-caused
+   changes in the UI as they happen — a sandboxed copy or a silent mutation
+   both read as "the agent is broken" to the user watching the screen.
+6. Before shipping, run the composition test: ask the agent for an in-domain
+   outcome you never explicitly built. With primitives and parity in place it
+   composes a path or fails visibly; with workflow-shaped tools it can only
+   do what was anticipated.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The upstream API is large or changes often | Generate the tool list from the API's schema instead of hand-maintaining a static mapping that drifts |
+| A composed flow is frequent and latency-sensitive | Add a domain-level tool for that observed pattern, and keep the primitives it composes — the shortcut is an optimization, not a replacement |
+| An action is dangerous to run autonomously | Gate it behind an approval step that states its reason in the tool result — an unexplained refusal reads as a bug and invites workarounds |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Bolt a chat agent onto a finished UI as a router to hardcoded flows | Build the capability map and primitive tools alongside the feature | A router caps capability at exactly the flows someone anticipated |
+| Add one convenience tool per product feature | Expose primitives; ship features as prompts | With workflow-shaped tools every new feature needs new code; with primitives it needs a new prompt |
+
+## Sources
+
+- https://github.com/EveryInc/compound-engineering-plugin — agent-native-architecture skill: parity capability map, tools-as-primitives with the `process_feedback` counter-example, CRUD completeness, explicit completion signal, named anti-patterns (agent-as-router, sandbox isolation, silent actions); field-tested in the plugin authors' shipped products
+- https://www.anthropic.com/engineering/building-effective-agents — agent-computer interface guidance: invest in tool definitions and keep tools simple and composable
diff --git a/wiki/backend/common/llm/binding-instructions-for-agents.md b/wiki/backend/common/llm/binding-instructions-for-agents.md
new file mode 100644
index 0000000..17897a5
--- /dev/null
+++ b/wiki/backend/common/llm/binding-instructions-for-agents.md
@@ -0,0 +1,67 @@
+---
+id: backend-common-llm-binding-instructions-for-agents
+domain: backend
+category: llm
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/obra/superpowers
+last_verified: 2026-08-22
+related: [backend-common-api-design-agent-tool-granularity]
+---
+
+# Instruction Text That Must Bind an LLM Agent's Behavior
+
+## When this applies
+
+Authoring or editing a skill, system prompt, hook message, or CLAUDE.md/
+AGENTS.md rule that must change an agent's behavior under pressure; an
+existing instruction keeps getting rationalized around; writing the
+description or trigger line that decides when an instruction loads.
+
+## Do this
+
+1. Test wording like code. Run the pressure scenario without the instruction
+   and require the baseline to fail — a compliant baseline means there is
+   nothing to fix. Then run with the instruction and require compliance. Use
+   5+ fresh-context repetitions per variant; a verdict that varies across
+   repetitions means the wording does not bind.
+2. Match the instruction's form to the observed failure:
+
+| Observed failure | Form that fixes it |
+|------------------|--------------------|
+| Rule skipped under pressure ("just this once", "too simple to count") | Prohibition plus the specific rationalizations countered by name, plus a red-flag phrase list |
+| Output compliant in letter but wrong in shape | A positive recipe or template of the wanted shape — in head-to-head wording tests, adding prohibitions to a wrong-shape failure produced MORE of the unwanted content than no guidance |
+| A required element omitted | A structural template with the element as a REQUIRED slot |
+| Behavior that depends on the situation | Predicate-keyed rules ("when X, do A; when Y, do B") — a blanket rule with exemption clauses leaves the boundary to per-run improvisation |
+
+3. Close loopholes from actual transcripts: quote the rationalization the
+   agent produced and counter it by name; add counters only for observed
+   workarounds, because speculative counters bloat the rule without binding
+   anything.
+4. Keep nuance out of the rule sentence: a single appended "unless it
+   matters" clause degraded a previously consistent wording to noisy in
+   repeated tests — encode each exception as its own predicate row instead.
+5. Write description/trigger fields as loading conditions only ("use when
+   ..."). A description that summarizes the workflow gets followed as the
+   workflow — the agent acts on the summary and skips the body's steps.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The instruction must hold across models or versions | Re-run the baseline+instruction pair per model — binding wording is model-specific, and an upgrade can un-bind it |
+| Two instruction sources conflict (a skill vs a project rule) | State the precedence inside the artifact itself; unstated precedence gets resolved differently per run |
+| The instruction is a one-off for a single session | Skip the test harness and state the rule directly — the testing cost is justified by reuse, and a session instruction is consumed once |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Stack a third prohibition after two were ignored | Rewrite as a recipe or predicate rules, then retest | Prohibition stacking measured worse than no guidance for wrong-shape failures |
+| Ship a wording after one clean test run | Run 5+ repetitions plus a no-guidance control | A single run samples the good tail of the distribution; the control proves the instruction is doing the work |
+| Write "never do X" on its own | Pair it with the replacement action that makes it unnecessary | A bare prohibition invites improvisation at the boundary — the same rule this wiki's AGENTS.md enforces on its own pages |
+
+## Sources
+
+- https://github.com/obra/superpowers — writing-skills skill and its testing references: baseline-fails-first discipline, form-matched-to-failure table with head-to-head wording measurements, nuance-clause degradation, description-as-trigger-only rule; field-tested across the framework's own skill suite
diff --git a/wiki/backend/index.md b/wiki/backend/index.md
index 81e97e1..0ac4f51 100644
--- a/wiki/backend/index.md
+++ b/wiki/backend/index.md
@@ -28,6 +28,7 @@ Match your situation to a "load when" line; load only matching pages.
 | [unenforced-declarations](common/api-design/unenforced-declarations.md) | Your system accepts declarative input (config file, DSL/manifest, policy block, schema annotation) and part of what a caller may write is unimplemented — an unknown key, a verb outside your vocabulary, or a knob recorded but never acted on; a user reports "I declared X and nothing happened"; choosing between reject/warn/ignore and where that strictness is selected |
 | [cors-and-preflight](common/api-design/cors-and-preflight.md) | A browser-based caller on a different origin fails with a CORS error in the console (a direct curl to the same endpoint works); deciding whether a change to an endpoint's method/headers/content-type will trigger an OPTIONS preflight; designing `Access-Control-*` headers for a credentialed vs public endpoint; allowlisting more than one origin |
 | [api-versioning-and-breaking-changes](common/api-design/api-versioning-and-breaking-changes.md) | An API has external callers you cannot enumerate or force-upgrade and you need to add/remove/rename/retype a field or endpoint; classifying a change as backward-compatible vs breaking; choosing a versioning mechanism (header vs URL); deprecating an old version (internal-only contract changes → [backend-common-change-impact-call-site-enumeration]) |
+| [agent-tool-granularity](common/api-design/agent-tool-granularity.md) | Adding agent capabilities to an app (MCP server, function-calling tools, plugin tools); choosing between exposing a workflow function and exposing primitives; an agent cannot perform an action the UI offers; reviewing a tool list for CRUD completeness, completion signaling, or UI/agent parity |
 
 ### change-impact
 
@@ -93,6 +94,7 @@ Match your situation to a "load when" line; load only matching pages.
 |------|-----------|
 | [completion-response-validation](common/llm/completion-response-validation.md) | Consuming OpenAI-compatible `/chat/completions` output as a final artifact (summary, document, notification); LLM responses coming back empty or truncated while HTTP status is 200; a reasoning-family model may be routed onto the alias you call |
 | [context-window-budget](common/llm/context-window-budget.md) | Repointing an LLM client or agent CLI at a different model, a self-hosted server (vLLM/Ollama), or a gateway (LiteLLM); setting `max_tokens` for a client whose default was sized for a larger model; the first request after such a switch returns 400 with a context-window error; deciding where to set the cap (request body vs client env var vs gateway config) and how to point the base URL at a proxy; handling truncation that arrives as a normal 200 |
+| [binding-instructions-for-agents](common/llm/binding-instructions-for-agents.md) | Authoring or editing a skill, system prompt, hook message, or CLAUDE.md/AGENTS.md rule that must change an agent's behavior under pressure; an instruction keeps getting rationalized around; choosing between prohibition, recipe, template-slot, and predicate-rule forms; writing a skill's description/trigger line |
 
 ### ml
 
diff --git a/wiki/databases/data-survey/surveying-live-data-for-a-rule.md b/wiki/databases/data-survey/surveying-live-data-for-a-rule.md
index 49baaa6..2d4c93b 100644
--- a/wiki/databases/data-survey/surveying-live-data-for-a-rule.md
+++ b/wiki/databases/data-survey/surveying-live-data-for-a-rule.md
@@ -62,6 +62,7 @@ what comes back.
 | Rows exist but every value in the surveyed column is `NULL` | `GROUP BY` returns one group whose key is `NULL`; the rule needs a `NULL` branch, and the non-`NULL` shape still has to come from code |
 | The count is small but non-zero (a handful of rows) | Treat it as a sample, not a census: cross-check against the writers before closing the value set, and say in the artifact that the set is open |
 | Writers disagree with each other about the stored shape | That disagreement is the finding — record every producer's shape and route the normalization decision to the owner rather than picking one |
+| The mapping table was hand-transcribed (from a spec, another system, or this survey) and a migration/backfill will apply it | Verify each entry individually against live data before the migration runs — transposed (copy-paste-swapped) entries are the dominant defect class in hand-built ID/enum mappings, and they survive spot checks because most entries are right |
 
 ## Instead of
 
@@ -76,3 +77,4 @@ what comes back.
 - https://www.postgresql.org/docs/current/functions-aggregate.html — "except for `count`, these functions return a null value when no rows are selected. In particular, `sum` of no rows returns null, not zero as one might expect, and `array_agg` returns null rather than an empty array"
 - https://greatexpectations.io/blog/exploring-data-quality-volume/ — volume (row count) as a first-class data-quality dimension; undetected volume anomalies "skew analyses and lead to flawed decision-making"
 - Reproduced 2026-08-05 (`sqlite3 :memory:`, empty table): `SELECT area_nm, count(*) … GROUP BY area_nm` → 0 rows; `SELECT count(*)` → one row `0`; `SELECT max(area_nm)` → one row `NULL`
+- https://github.com/EveryInc/compound-engineering-plugin — data-migration-expert agent: swapped/inverted ID-enum mapping entries named the single most common and dangerous migration bug; verify each mapping entry against production data individually
diff --git a/wiki/debugging/methodology/hypothesis-testing.md b/wiki/debugging/methodology/hypothesis-testing.md
index 818f770..7b55e97 100644
--- a/wiki/debugging/methodology/hypothesis-testing.md
+++ b/wiki/debugging/methodology/hypothesis-testing.md
@@ -51,6 +51,8 @@ applies when several suspects compete and you must pick what to investigate next
 | The fix "works" but you never confirmed the mechanism | Verify before closing: re-introduce the original condition and confirm the failure returns, or trace the mechanism end-to-end in evidence (logs/values). A fix that works for unknown reasons masks symptoms and leaves the cause live |
 | Experiment is inconclusive (failure is intermittent) | Make the observation statistical — N runs per arm, per [debugging-concurrency-intermittent-failures] — before drawing any conclusion |
 | Every hypothesis you can think of is falsified | Your model of the system is wrong somewhere upstream. Return to evidence gathering: widen what you observe ([debugging-signals-logs-and-correlation]) or bisect to relocate the fault ([debugging-methodology-isolate-by-bisection]) |
+| Three or more successive fixes have failed, each revealing new coupling somewhere else | Stop generating fix-level hypotheses — the failing hypothesis is the design itself. Escalate to an architecture-level review of the component's boundaries before attempting a fourth fix; a pattern of fixes that each surface new breakage elsewhere is evidence of a structural cause no local patch reaches |
+| The failure spans several components and no single suspect stands out | Instrument every component boundary in one pass — log the data entering and leaving each seam — run the reproduction once, and read which layer the data goes wrong in; then form hypotheses inside that one layer only |
 | Testing the hypothesis requires touching prod | Prefer a read-only prediction (something already in logs/metrics that must be true if the hypothesis holds); active prod experiments require owner approval and a rollback plan |
 | Hypothesis confirmed but the fix belongs to another domain (slow query, infra limit) | Record the confirmed mechanism, then route the fix to the owning domain — e.g. a slow SQL statement goes to wiki/databases/query-optimization/reading-execution-plans.md |
 | One suspect is a mechanism designed to be invisible to you (silent moderation, shadowban, silent spam-drop, a filter that returns success) | An explicit error message refutes that suspect: concealment is the mechanism's defining property, so a system that told you it refused you is a different system. Test the visible-refusal suspects first — they are the ones with readable evidence |
@@ -69,5 +71,6 @@ applies when several suspects compete and you must pick what to investigate next
 
 - https://www.debuggingbook.org/html/Intro_Debugging.html — scientific method for debugging: hypothesis → prediction → experiment → repeat
 - https://sre.google/sre-book/effective-troubleshooting/ — hypothetico-deductive troubleshooting; test causes, treat the confirmed one
+- https://github.com/obra/superpowers — systematic-debugging skill: the 3-failed-fixes architecture circuit breaker and instrument-every-boundary-then-run-once for multi-component failures; field-tested across agentic debugging sessions
 - https://news.ycombinator.com/newsfaq.html — a killed post is marked `[dead]` and "aren't displayed by default"; the FAQ documents no notification to the author, i.e. the suppression carries no message to the affected party — which is why receiving an explicit refusal falsifies the silent-suppression hypothesis
 - Field application 2026-08-06: a submission was assumed silently suppressed; the account had in fact received an explicit restriction notice, and a search API returning zero hits for the item was shown to be uninformative by a control query on the same endpoint returning 8,462 hits — the control separated "endpoint broken" from "item absent"
diff --git a/wiki/debugging/methodology/verify-the-fix.md b/wiki/debugging/methodology/verify-the-fix.md
index c8d7fc9..fcbc92b 100644
--- a/wiki/debugging/methodology/verify-the-fix.md
+++ b/wiki/debugging/methodology/verify-the-fix.md
@@ -8,7 +8,7 @@ sources:
   - https://www.debuggingbook.org/html/Intro_Debugging.html
   - https://sre.google/sre-book/effective-troubleshooting/
 last_verified: 2026-07-10
-related: [debugging-methodology-reproduce-first, debugging-methodology-hypothesis-testing, backend-common-change-impact-call-site-enumeration]
+related: [debugging-methodology-reproduce-first, debugging-methodology-hypothesis-testing, backend-common-change-impact-call-site-enumeration, testing-strategy-failing-test-first, qa-process-completion-claims]
 ---
 
 # Verifying a Fix Before Closing the Bug
@@ -29,7 +29,7 @@ with a stated mechanism. Work through every row:
 | Flip both directions | The repro must fail on the pre-fix build/commit and pass on the post-fix one; where feasible, re-introduce the faulty condition and watch the failure return — the mechanism confirmation from [debugging-methodology-hypothesis-testing] |
 | Eliminate state pollution | Run the verification from a clean state: clear caches (build cache, HTTP/browser cache, dependency cache), remove stale artifacts and hot-reload state, reset leftover DB rows — clean build, fresh session |
 | Intermittent bug | Run the repro the SAME amplified number of times that reliably failed before (amplification: wiki/debugging/concurrency/intermittent-failures.md) — one green run of a 1-in-20 bug proves nothing |
-| Pin with a regression test | Encode the repro as an automated test that fails without the fix and passes with it, so the bug cannot silently return (failing-test-first rule: wiki/testing/) |
+| Pin with a regression test | Encode the repro as an automated test that fails without the fix and passes with it, so the bug cannot silently return ([testing-strategy-failing-test-first]) |
 | Clean up the investigation | Remove debug logging/prints, temporary config/flags, commented-out experiments; diff the final change against the intent — everything not serving the fix reverts |
 | Scope check | List the other inputs/paths the confirmed mechanism implies (same root cause elsewhere) and confirm the fix covers them; re-run the edge cases of the touched code that worked before the fix |
 
diff --git a/wiki/frontend/agent-interfaces/agent-facing-tool-surfaces.md b/wiki/frontend/agent-interfaces/agent-facing-tool-surfaces.md
index 677b4a5..8e9ea68 100644
--- a/wiki/frontend/agent-interfaces/agent-facing-tool-surfaces.md
+++ b/wiki/frontend/agent-interfaces/agent-facing-tool-surfaces.md
@@ -10,7 +10,7 @@ sources:
   - https://developer.chrome.com/docs/ai/webmcp/declarative-api
   - https://webmachinelearning.github.io/webmcp/
 last_verified: 2026-08-18
-related: [security-agent-exposure-in-session-tool-exposure, frontend-accessibility-interactive-elements]
+related: [security-agent-exposure-in-session-tool-exposure, frontend-accessibility-interactive-elements, backend-common-api-design-agent-tool-granularity]
 ---
 
 # Exposing Site Actions as Tools for AI Agents (WebMCP)
@@ -55,7 +55,7 @@ registers browser-native agent tools.
    each field from, in priority order: its `toolparamdescription` attribute,
    its associated `<label>` content, its `aria-description`. Give every field
    a real `<label>`, correct input `type`, and `required` where applicable —
-   the same work [frontend-accessibility-interactive-elements] already
+   the same work [frontend-accessibility-interactive-elements, backend-common-api-design-agent-tool-granularity] already
    requires — and add `toolparamdescription` only where the label alone
    under-specifies the value format.
 
diff --git a/wiki/infrastructure/agent-orchestration/autonomous-decision-rulings.md b/wiki/infrastructure/agent-orchestration/autonomous-decision-rulings.md
new file mode 100644
index 0000000..0cdcd0c
--- /dev/null
+++ b/wiki/infrastructure/agent-orchestration/autonomous-decision-rulings.md
@@ -0,0 +1,62 @@
+---
+id: infrastructure-agent-orchestration-autonomous-decision-rulings
+domain: infrastructure
+category: agent-orchestration
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/obra/superpowers
+last_verified: 2026-08-22
+related: [infrastructure-agent-orchestration-unattended-worker-questions, infrastructure-agent-orchestration-shared-run-state, infrastructure-agent-orchestration-control-signals-vs-primary-artifacts]
+---
+
+# Deciding Without a Human During an Unattended Run
+
+## When this applies
+
+An unattended agent — a worker or its coordinator — hits a decision its plan
+or prompt does not answer and must choose between stopping to ask and
+proceeding; a run stalls on questions a human never needed to see; auditing
+the decisions a finished run made on its own.
+
+## Do this
+
+1. Stop for the human only when the decision falls in one of four categories:
+   (a) an irreversible or destructive operation, (b) a security-sensitive
+   action, (c) a side effect that leaves the workspace — push or merge to a
+   shared branch, publish, an external call with real-world effect — or
+   (d) a plan broken to the point that every path forward is a guess. Route
+   that question through the out-of-band channel of
+   [infrastructure-agent-orchestration-unattended-worker-questions].
+2. Rule on every other open decision and keep going — recording each ruling
+   durably as `Ruling: <decision> — <why> — <cost if wrong>` in the run's
+   ledger (the progress file of
+   [infrastructure-agent-orchestration-shared-run-state], or the PR
+   description).
+3. After an interruption, compaction, or resume: re-read the ledger and the
+   git log before dispatching work — memory of "where we were" re-dispatches
+   already-completed task sequences; the ledger and the log do not.
+4. Collect every `Ruling:` line into the final report, so the human audits
+   the run's autonomous decisions in one pass instead of discovering them in
+   the diff.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The same ruling keeps recurring across tasks | Promote it into the plan or the workers' prompt so it stops being re-decided per task |
+| A ruling proves wrong later in the run | Fix forward and record the reversal as its own ruling; the original entry stays — the ledger is append-only history, not current state |
+| A category-(c) action is pre-approved in the plan ("push to the feature branch after each task") | Proceed and cite the plan's written approval in the ruling — the written plan is the human decision |
+| The worker cannot write the ledger (a permission gate blocks the path) | Report the signal as un-emitted and hand it back per [infrastructure-agent-orchestration-control-signals-vs-primary-artifacts], instead of working around the gate |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Stop the run to ask about a low-stakes choice | Rule, record, proceed | An unattended run that stalls on every choice loses the point of being unattended; the ledger preserves auditability |
+| Decide silently and move on | Record the ruling with its cost-if-wrong | Silent decisions resurface as surprises in review, where they cost more than the ruling would have |
+| Reconstruct progress from session memory after a resume | Re-read the ledger and git log | Controllers that trusted memory have re-dispatched entire completed task sequences |
+
+## Sources
+
+- https://github.com/obra/superpowers — subagent-driven-development skill: the four stop categories, the `Ruling:` ledger format with cost-if-wrong, ledger-over-memory recovery; field-tested across multi-agent plan executions
diff --git a/wiki/infrastructure/agent-orchestration/control-signals-vs-primary-artifacts.md b/wiki/infrastructure/agent-orchestration/control-signals-vs-primary-artifacts.md
index cfe0e86..7f739ff 100644
--- a/wiki/infrastructure/agent-orchestration/control-signals-vs-primary-artifacts.md
+++ b/wiki/infrastructure/agent-orchestration/control-signals-vs-primary-artifacts.md
@@ -9,7 +9,7 @@ sources:
   - https://code.claude.com/docs/en/hooks
   - https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html
 last_verified: 2026-08-06
-related: [infrastructure-agent-orchestration-shared-run-state, infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-session-completion-gates, platforms-shells-command-text-inspected-before-execution, platforms-tools-harness-mediated-tool-results, debugging-methodology-hypothesis-testing, infrastructure-agent-orchestration-unattended-worker-questions, debugging-methodology-probe-path-vs-operation-path]
+related: [infrastructure-agent-orchestration-shared-run-state, infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-session-completion-gates, platforms-shells-command-text-inspected-before-execution, platforms-tools-harness-mediated-tool-results, debugging-methodology-hypothesis-testing, infrastructure-agent-orchestration-unattended-worker-questions, debugging-methodology-probe-path-vs-operation-path, qa-process-completion-claims, infrastructure-agent-orchestration-autonomous-decision-rulings]
 ---
 
 # Deciding a Worker Is Done, Alive, or Dead from a Status File or Watcher Verdict
diff --git a/wiki/infrastructure/agent-orchestration/unattended-worker-questions.md b/wiki/infrastructure/agent-orchestration/unattended-worker-questions.md
index 0a0fbbd..35e9d73 100644
--- a/wiki/infrastructure/agent-orchestration/unattended-worker-questions.md
+++ b/wiki/infrastructure/agent-orchestration/unattended-worker-questions.md
@@ -9,7 +9,7 @@ sources:
   - https://github.com/anthropics/claude-code/issues/29530
   - https://man7.org/linux/man-pages/man1/tmux.1.html
 last_verified: 2026-08-08
-related: [infrastructure-agent-orchestration-usage-limit-paused-workers, infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-control-signals-vs-primary-artifacts, infrastructure-agent-orchestration-shared-run-state, infrastructure-agent-orchestration-session-completion-gates, platforms-processes-non-interactive-cli-invocation]
+related: [infrastructure-agent-orchestration-usage-limit-paused-workers, infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-control-signals-vs-primary-artifacts, infrastructure-agent-orchestration-shared-run-state, infrastructure-agent-orchestration-session-completion-gates, platforms-processes-non-interactive-cli-invocation, infrastructure-agent-orchestration-autonomous-decision-rulings]
 ---
 
 # A Worker Agent Asks a Question With No Human at Its Terminal
diff --git a/wiki/infrastructure/index.md b/wiki/infrastructure/index.md
index fe918e3..9555394 100644
--- a/wiki/infrastructure/index.md
+++ b/wiki/infrastructure/index.md
@@ -20,6 +20,7 @@ Match your situation to a "load when" line; load only matching pages.
 | [unattended-worker-questions](agent-orchestration/unattended-worker-questions.md) | A worker agent raises a question through its own interactive UI (a numbered chooser, a confirmation/trust/re-auth screen) with no human at that terminal; a worker is flagged stalled with a live terminal and no task-level error; a worker reports a decision it assumed rather than asked; designing the channel a worker uses to ask its coordinator for a decision |
 | [usage-limit-paused-workers](agent-orchestration/usage-limit-paused-workers.md) | Several workers billed to one account go quiet within minutes of each other while every liveness check passes; a worker's terminal shows a `You've hit your session/weekly/Opus limit · resets …` notice; deciding whether to restart, replace, or wait on a worker with no task-level error; writing the prompt that resumes a worker after a usage window resets |
 | [worktree-isolated-workers](agent-orchestration/worktree-isolated-workers.md) | Authoring the brief/output contract for parallel workers each confined to its own git worktree; workers stall at the same phase with no task-level error; deciding where shared or produced artifacts live and which direction (read vs write) a worktree guardrail stops; a guardrail escalates on read-only access to another worktree; the isolation guard is a Bash-command hook while workers also edit files with native Edit/Write tools |
+| [autonomous-decision-rulings](agent-orchestration/autonomous-decision-rulings.md) | An unattended agent hits a decision its plan does not answer and must choose between stopping to ask and proceeding; a run stalls on questions no human needed to see; deciding which decision categories require a human; recording autonomous decisions for audit; resuming after interruption/compaction without re-dispatching completed work |
 
 ## ci-cd
 
diff --git a/wiki/qa/index.md b/wiki/qa/index.md
index 12f2aca..469ff11 100644
--- a/wiki/qa/index.md
+++ b/wiki/qa/index.md
@@ -2,8 +2,9 @@
 
 Route here for: release-quality process — acceptance criteria, gates,
 regression scoping, test-environment parity, post-release verification, bug
-reports, manual/exploratory testing, and automated verification of document
-deliverables (specs/RFCs). Writing automated test code → wiki/testing/;
+reports, manual/exploratory testing, evidence for completion claims, acting on
+code-review feedback, adversarial review of high-risk diffs, and automated
+verification of document deliverables (specs/RFCs). Writing automated test code → wiki/testing/;
 rollout/canary/rollback mechanics → wiki/infrastructure/.
 
 Match your situation to a "load when" line; load only matching pages.
@@ -19,6 +20,9 @@ Match your situation to a "load when" line; load only matching pages.
 | [post-release-verification](process/post-release-verification.md) | A release just deployed to production; defining what "released safely" means; an incident revealed a release was broken for hours before anyone noticed |
 | [scope-purity-checks](process/scope-purity-checks.md) | Proving a change/session/agent run touched nothing outside an allowed path set by filtering `git status --porcelain` output; a purity gate flags `?? dir/` for a directory that is wholly in scope; writing such a gate for an orchestration/CI workflow; a purity check in a permanent test suite fails on unrelated uncommitted files |
 | [defect-class-resweep-after-review](process/defect-class-resweep-after-review.md) | Addressing review findings when the remediation itself adds code (a new function, branch, call site, formatter); about to hand that diff to a verifier, an audit, or CI as "review comments addressed"; deciding whether a bot's acknowledged/resolved thread means the class is closed; reporting fix completeness as a class-with-method count rather than a per-finding list |
+| [completion-claims](process/completion-claims.md) | About to report work as done, fixed, or passing — to a human, a coordinator, a PR, or a commit message; about to write "should work" or "tests pass" without a fresh run; deciding what evidence a completion claim requires; relaying a subagent's success report |
+| [evaluating-review-feedback](process/evaluating-review-feedback.md) | Review findings arrived (human, bot, or reviewer agent) and you are deciding what to implement; a finding is unclear; a reviewer proposes robustness or features nothing uses; you disagree with a finding and are deciding how to respond |
+| [adversarial-change-review](process/adversarial-change-review.md) | Reviewing a diff ≥50 changed lines or one touching auth/payments/migrations/external APIs; a checklist review found nothing on a high-blast-radius change; deciding review depth for a risky diff; constructing failure scenarios (assumption violation, composition, cascade, abuse) |
 
 ## deliverables
 
diff --git a/wiki/qa/process/adversarial-change-review.md b/wiki/qa/process/adversarial-change-review.md
new file mode 100644
index 0000000..b4c5a59
--- /dev/null
+++ b/wiki/qa/process/adversarial-change-review.md
@@ -0,0 +1,66 @@
+---
+id: qa-process-adversarial-change-review
+domain: qa
+category: process
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/EveryInc/compound-engineering-plugin
+last_verified: 2026-08-22
+related: [qa-process-evaluating-review-feedback, qa-process-regression-scope, qa-process-post-release-verification]
+---
+
+# Constructing Failure Scenarios for a High-Risk Diff
+
+## When this applies
+
+Reviewing a diff that is large (≥50 changed lines) or touches auth, payments,
+data migrations, or external-API consumption; a checklist review returned
+nothing on a change whose blast radius is high; deciding how deep a review
+must go before merge.
+
+## Do this
+
+1. Set the depth from the diff, before reviewing:
+
+| Diff | Review depth |
+|------|--------------|
+| <50 changed lines, no high-risk domain | Standard checklist review only |
+| 50–199 lines, or one minor risk signal | Techniques 1–2 below |
+| ≥200 lines, or any auth/payment/migration/money path | All four techniques, with multi-step traces |
+
+2. Construct scenarios with the four techniques — each produces concrete
+   inputs traced through the code, not pattern labels:
+
+| Technique | Construct |
+|-----------|-----------|
+| 1. Assumption violation | List the diff's data-shape, timing, ordering, and value-range assumptions; build one violating input per assumption and trace it through |
+| 2. Composition failure | Pair components that are correct alone: contract mismatches at their boundary, shared state mutated without coordination, thrower/catcher error-type divergence |
+| 3. Cascade construction | Chain failures across steps: timeout → retry → added load → more timeouts; partial write → wrong downstream decision → compounding corruption; recovery that fails (a retry duplicating a side effect, a rollback stranding state, a circuit breaker blocking its own recovery probe) |
+| 4. Abuse cases | Legitimate-looking misuse: the 1000th identical submission, a request landing mid-deploy or mid-cache-invalidation, two actors racing one resource, inputs walking the exact boundary (max size, exactly at the rate limit) |
+
+3. Name each finding as a scenario — input/state → consequence ("payment
+   timeout triggers unbounded retry loop") — a scenario can be checked and
+   reproduced; a pattern label cannot.
+4. Route adversarial findings to human judgment rather than autofix, and
+   confirm a scenario (run it, or trace it with line references) before it
+   blocks a merge; label unconfirmed scenarios with their confidence.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| A scenario needs prod-only conditions to trigger | Record it as a post-release monitoring item with the signal to watch ([qa-process-post-release-verification]) |
+| All four techniques return nothing on a high-risk diff | State the null result with what was searched (techniques × assumptions listed) — a stated null and an omitted one read the same to the merge decision, so state it |
+| The diff is high-risk and also very large | Partition by risk surface (auth paths first, then money paths) and run the techniques per partition, so depth lands where the blast radius is |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Clear a payment/auth diff with a style-and-correctness checklist alone | Run the four techniques at the depth the table sets | Checklists find known single-point patterns; constructed scenarios find interactions between correct-looking parts |
+| Report "potential race condition" as a finding | Construct the interleaving: which two operations, which shared state, what wrong outcome | An unconstructed finding cannot be verified, prioritized, or fixed |
+
+## Sources
+
+- https://github.com/EveryInc/compound-engineering-plugin — adversarial-reviewer persona: depth calibration by size/risk, the four scenario-construction techniques, scenario-oriented finding titles, advisory-to-human routing; field-tested in the plugin's shipped review workflow
diff --git a/wiki/qa/process/completion-claims.md b/wiki/qa/process/completion-claims.md
new file mode 100644
index 0000000..6ddcfc6
--- /dev/null
+++ b/wiki/qa/process/completion-claims.md
@@ -0,0 +1,61 @@
+---
+id: qa-process-completion-claims
+domain: qa
+category: process
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/obra/superpowers
+last_verified: 2026-08-22
+related: [debugging-methodology-verify-the-fix, infrastructure-agent-orchestration-control-signals-vs-primary-artifacts, testing-quality-tests-that-cannot-fail, qa-process-release-gates]
+---
+
+# Claiming Work Is Done, Fixed, or Passing
+
+## When this applies
+
+About to report completion, success, or a green status — to a human, a
+coordinator, a PR description, or a commit message; about to write "should
+work now", "probably fixed", or "tests pass" without a run in front of you.
+
+## Do this
+
+1. Identify the command whose output proves the claim, run it fresh against the
+   state you are reporting on, read the complete output and exit code, and
+   claim exactly what the output shows — a claim without a same-session run
+   behind it is a prediction, and gets labeled as one.
+2. Match each claim to its evidence:
+
+| Claim | Required evidence | Not evidence |
+|-------|-------------------|--------------|
+| "Tests pass" | A fresh run: zero failures and the expected total count | An earlier run; "should pass"; a subset run reported as the whole suite |
+| "Bug fixed" | The recorded reproduction re-run per [debugging-methodology-verify-the-fix] | "The code changed"; the symptom gone after unrelated restarts |
+| "Feature works" | The feature executed end-to-end with its observable output | A clean build; unit tests of the parts |
+| "Worker/subagent finished its task" | Its diff and artifacts inspected per [infrastructure-agent-orchestration-control-signals-vs-primary-artifacts] | The worker's own completion report |
+| "Regression test added" | The red-green flip: test fails with the fix reverted, passes with it ([testing-quality-tests-that-cannot-fail]) | A test written once and seen green once |
+
+3. Treat hedge words in a completion sentence — "should", "probably", "seems
+   to" — as markers of an unverified claim: run the proving command, or
+   downgrade the sentence to a status report naming what remains unverified.
+4. Report outcomes symmetrically: failures with their output attached, skipped
+   steps named as skipped — a stated failure and an omitted one read the same
+   to the next reader only when both are written down.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| Full verification is expensive (multi-hour suite) | Run the targeted subset now and name it in the claim ("auth tests pass; full suite pending"); run the full suite at the merge gate ([qa-process-release-gates]) |
+| The current environment cannot run the proving command | State the claim as unverified and hand over the exact command that would verify it |
+| The proving run is green but its total dropped from the baseline | Read a dropped total as a lost module or import, not a pass — compare totals before claiming ([testing-quality-tests-that-cannot-fail]) |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Write "everything works now" after a round of edits | Run the proving command and paste its result | Edits change code; only execution changes knowledge |
+| Relay a subagent's "task completed successfully" | Inspect its diff and artifacts, then report what you saw | Self-reports over-claim systematically; artifacts cannot |
+
+## Sources
+
+- https://github.com/obra/superpowers — verification-before-completion skill: fresh-evidence gate, claim/evidence table, hedge-word red flags, distrust of delegated self-reports; field-tested across agentic coding sessions
diff --git a/wiki/qa/process/defect-class-resweep-after-review.md b/wiki/qa/process/defect-class-resweep-after-review.md
index 079bfa2..892dc30 100644
--- a/wiki/qa/process/defect-class-resweep-after-review.md
+++ b/wiki/qa/process/defect-class-resweep-after-review.md
@@ -8,7 +8,7 @@ sources:
   - https://www.eecg.utoronto.ca/~yuan/papers/incorrect_fix_abstract.html
   - https://dl.acm.org/doi/10.1145/2025113.2025121
 last_verified: 2026-08-11
-related: [qa-process-regression-scope, backend-common-change-impact-call-site-enumeration, testing-quality-tests-that-cannot-fail]
+related: [qa-process-regression-scope, backend-common-change-impact-call-site-enumeration, testing-quality-tests-that-cannot-fail, qa-process-evaluating-review-feedback]
 ---
 
 # Re-Sweeping the Reviewed Defect Class Across Your Own Remediation Diff
@@ -44,7 +44,7 @@ Choosing what to *re-test* for the release around it →
 4. **Turn a class with two or more sites into one shared helper plus one test that
    asserts the property at every site**, so the next round's new site inherits the
    fix instead of needing to be found again
-   ([testing-quality-tests-that-cannot-fail] for making that assertion able to
+   ([testing-quality-tests-that-cannot-fail, qa-process-evaluating-review-feedback] for making that assertion able to
    fail).
 
 5. **Read the remediation diff as unreviewed code.** It was written under time
diff --git a/wiki/qa/process/evaluating-review-feedback.md b/wiki/qa/process/evaluating-review-feedback.md
new file mode 100644
index 0000000..7e757a9
--- /dev/null
+++ b/wiki/qa/process/evaluating-review-feedback.md
@@ -0,0 +1,70 @@
+---
+id: qa-process-evaluating-review-feedback
+domain: qa
+category: process
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/obra/superpowers
+  - https://google.github.io/eng-practices/review/reviewer/standard.html
+  - https://google.github.io/eng-practices/review/reviewer/looking-for.html
+last_verified: 2026-08-22
+related: [qa-process-defect-class-resweep-after-review, qa-process-adversarial-change-review]
+---
+
+# Acting on Code Review Feedback
+
+## When this applies
+
+Review findings arrived — from a human, a bot, or a reviewer agent — and you
+are deciding what to implement; a finding is unclear; a reviewer proposes new
+robustness or supporting features; you disagree with a finding.
+
+## Do this
+
+1. Read every finding before changing anything, and restate each in your own
+   words — implementing while reading optimizes the first finding at the
+   expense of the ones coupled to it.
+2. Verify each finding against the code before editing: open the cited lines
+   and confirm the defect exists and the suggestion is correct for this
+   codebase — reviewers, human and agent alike, work from partial context.
+3. When any finding is unclear, get every unclear finding clarified before
+   implementing any of them — related findings implemented from partial
+   understanding produce fixes that contradict each other.
+4. When a reviewer proposes supporting code ("handle X properly", "make this
+   configurable"): search for actual usage first; when nothing uses the
+   capability, propose removing the dead surface instead of building it —
+   solve the problem that exists now, not the speculated one.
+5. On disagreement, push back with evidence — cited code, observed behavior, a
+   failing case — and accept the resolution; technical facts and data override
+   opinion in both directions.
+6. Implement in this order: clarifications → correctness-blocking findings →
+   simple fixes → complex fixes; test each finding's fix individually before
+   moving to the next.
+7. Acknowledge with the fix itself: the commit or reply states what changed
+   and why. Replace agreement or praise phrasing ("great catch!") with that
+   statement — the fix carries the information; the phrase does not.
+8. When your fix wave adds new code, re-sweep the whole diff for the same
+   defect class per [qa-process-defect-class-resweep-after-review].
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| You pushed back and turn out to be wrong | State the correction factually and implement the fix — the correction is the apology |
+| Two findings conflict with each other | Surface the conflict to the reviewer(s) and get a resolution before implementing either |
+| A reviewer agent flagged pre-existing code outside the diff | Verify it, then file it as separate work — expanding the current change silently mixes concerns for every later reader |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Implement findings top-to-bottom as you read | Read all, verify all, then fix in dependency order | Later findings change what the earlier fixes should be |
+| Reply "You're absolutely right!" and start editing | Verify the claim against the code, then let the fix speak | Performative agreement commits you before verification, and adds noise for the next reader |
+| Build the "proper" version a reviewer sketched | Grep for real usage first; propose removal when unused | Unused robustness is dead weight that still has to be maintained and reviewed |
+
+## Sources
+
+- https://github.com/obra/superpowers — receiving-code-review skill: verify-before-implementing, clarify-all-before-any, performative-agreement ban, YAGNI usage check; field-tested across agentic coding sessions
+- https://google.github.io/eng-practices/review/reviewer/standard.html — technical facts and data overrule opinions and personal preferences
+- https://google.github.io/eng-practices/review/reviewer/looking-for.html — reviewers guard against over-engineering: solve the known problem, not the speculated future one
diff --git a/wiki/testing/index.md b/wiki/testing/index.md
index 270c2cc..be81c36 100644
--- a/wiki/testing/index.md
+++ b/wiki/testing/index.md
@@ -1,9 +1,10 @@
 # testing — Domain Index
 
 Route here for: writing or structuring automated tests — choosing the test
-level, selecting cases and assertions, test data and isolation, mock/fake
-decisions, fixing flaky tests, verifying tests can actually fail, validating a
-check before its target exists, testing
+level, selecting cases and assertions, test-before-code ordering (failing test
+first), scoping tests for changes whose execution reaches other layers, test
+data and isolation, mock/fake decisions, fixing flaky tests, verifying tests
+can actually fail, validating a check before its target exists, testing
 async code (promises/timers/events), and browser E2E selector/wait/setup
 strategy. Release-process quality (gates, manual testing, bug triage) →
 wiki/qa/.
@@ -19,6 +20,8 @@ Match your situation to a "load when" line; load only matching pages.
 | [test-level-choice](strategy/test-level-choice.md) | Deciding at which level (unit/integration/e2e) to test new or changed behavior; reviewing a test plan's level distribution; logic buried in a controller or framework wiring needs coverage; a "pure" function's module runs I/O at import so its "unit" test needs a DB (and a function-level skip can't prevent it) |
 | [signal-delivery-to-a-process-under-test](strategy/signal-delivery-to-a-process-under-test.md) | Testing a program's SIGINT/Ctrl-C shutdown path; a `kill -INT` on a `&`-backgrounded PID is silently ignored and `wait` hangs to the harness timeout; the signal test passes by hand in a terminal but hangs in CI; choosing between a shell script and a subprocess driver for delivering signals |
 | [orm-generated-test-schema](strategy/orm-generated-test-schema.md) | Planning a regression test for a defect caused by the ORM model and the real database disagreeing (nullability, type, length, index); checking what a test profile's `ddl-auto`/schema source makes reproducible; choosing between a migration-built test database with `validate` and an `information_schema` comparison gate; reviewing a plan that promises to "add a test that reproduces" a drift-shaped defect |
+| [failing-test-first](strategy/failing-test-first.md) | Implementing new behavior or a bug fix and deciding the order of test and production code; a test passed on its first-ever run; production code exists that no test required; expected values are about to be copied from the code's own output; encoding a bug repro as a regression test |
+| [cross-layer-effect-tests](strategy/cross-layer-effect-tests.md) | About to mark a change tested when its tests exercise only the changed unit; the changed path fires callbacks/middleware/hooks/jobs/DB triggers; the change persists state in more than one step; several surfaces (API, CLI, job) expose the same changed logic; deciding whether unit-level coverage suffices for a change |
 
 
 ## quality
diff --git a/wiki/testing/quality/tests-that-cannot-fail.md b/wiki/testing/quality/tests-that-cannot-fail.md
index 0480420..307c012 100644
--- a/wiki/testing/quality/tests-that-cannot-fail.md
+++ b/wiki/testing/quality/tests-that-cannot-fail.md
@@ -16,7 +16,7 @@ sources:
   - https://git-scm.com/docs/git-checkout
   - https://git-scm.com/docs/git-restore
 last_verified: 2026-08-12
-related: [testing-quality-minimum-case-set, testing-quality-behavior-not-implementation, testing-mocking-what-to-mock, testing-async-async-testing, testing-quality-checks-that-cannot-pass, testing-quality-spec-artifact-checks, testing-quality-harness-reverse-controls, testing-quality-schema-additions-under-a-golden-gate, testing-quality-differential-run-agreement, testing-quality-completion-predicates, testing-quality-guard-shape-vs-consequence, testing-quality-injected-clock-duration-assertions, testing-quality-write-path-assertions, testing-quality-value-preserving-refactor-assertions, testing-quality-unasserted-return-fields, testing-quality-stale-artifact-baselines, backend-common-change-impact-call-site-enumeration, platforms-shells-portable-shell-scripts, qa-document-verification-spec-document-gates, testing-quality-surviving-mutant-equivalence-triage, testing-quality-source-text-wiring-assertions, testing-quality-default-values-under-test, testing-mocking-captured-call-arguments, testing-quality-captured-log-message-assertions]
+related: [testing-quality-minimum-case-set, testing-quality-behavior-not-implementation, testing-mocking-what-to-mock, testing-async-async-testing, testing-quality-checks-that-cannot-pass, testing-quality-spec-artifact-checks, testing-quality-harness-reverse-controls, testing-quality-schema-additions-under-a-golden-gate, testing-quality-differential-run-agreement, testing-quality-completion-predicates, testing-quality-guard-shape-vs-consequence, testing-quality-injected-clock-duration-assertions, testing-quality-write-path-assertions, testing-quality-value-preserving-refactor-assertions, testing-quality-unasserted-return-fields, testing-quality-stale-artifact-baselines, backend-common-change-impact-call-site-enumeration, platforms-shells-portable-shell-scripts, qa-document-verification-spec-document-gates, testing-quality-surviving-mutant-equivalence-triage, testing-quality-source-text-wiring-assertions, testing-quality-default-values-under-test, testing-mocking-captured-call-arguments, testing-quality-captured-log-message-assertions, testing-strategy-failing-test-first]
 ---
 
 # Proving a Test Can Fail
diff --git a/wiki/testing/strategy/cross-layer-effect-tests.md b/wiki/testing/strategy/cross-layer-effect-tests.md
new file mode 100644
index 0000000..82d81db
--- /dev/null
+++ b/wiki/testing/strategy/cross-layer-effect-tests.md
@@ -0,0 +1,56 @@
+---
+id: testing-strategy-cross-layer-effect-tests
+domain: testing
+category: strategy
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/EveryInc/compound-engineering-plugin
+last_verified: 2026-08-22
+related: [testing-strategy-test-level-choice, testing-mocking-what-to-mock, testing-quality-write-path-assertions, testing-quality-minimum-case-set]
+---
+
+# Testing a Change Whose Execution Reaches Other Layers
+
+## When this applies
+
+About to mark a change tested when its tests exercise only the changed unit;
+the changed path fires framework callbacks, middleware, event handlers,
+enqueued jobs, or DB triggers; the change persists state in more than one step;
+or more than one surface (API, CLI, job, admin UI) exposes the changed logic.
+
+## Do this
+
+Answer five questions before declaring the change tested; each question carries
+its own action:
+
+| Question | Action |
+|----------|--------|
+| What else fires when this runs? | Trace two levels outward from the change — callbacks, middleware, lifecycle hooks, DB triggers, enqueued jobs — and write the list down; the list is the test surface |
+| Do the tests exercise the real chain? | Keep at least one test that runs the real collaborators through the integration seam ([testing-strategy-test-level-choice]); a chain where every collaborator is mocked verifies the mocks ([testing-mocking-what-to-mock]) |
+| Can a failure leave orphaned state? | Add the partial-failure case: fail the later step and assert the earlier one rolled back or compensates ([testing-quality-write-path-assertions]) |
+| Which sibling surfaces expose the same behavior? | Enumerate every surface that reaches the changed logic; cover each one, or route them all through one shared, tested path |
+| Do error strategies align across layers? | Check that thrower and catcher agree on error type and contract — a layer catching by message string under a layer that changed its error class drifts silently |
+
+Skip condition: when the change is a leaf node — nothing fires beyond it, no
+multi-step state, a single surface — unit-level tests suffice; record that
+reasoning in the PR so the reviewer sees a decision, not an omission.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The framework chain is implicit (ORM lifecycle hooks, global middleware) | Read the model's/app's registered hook list before concluding the trace is empty |
+| The two-level trace reveals a fan-out too large to cover | Test first-level effects directly and pin the second level with one integration test through the production entry point |
+| The fired effect is asynchronous (job, event) | Assert on the effect's own observable (job enqueued with expected args, event payload), then test the consumer separately at its level |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Declare done because the changed function's unit tests pass | Answer the five questions first | Unit tests cannot see cascade effects, orphaned state, or sibling-surface drift |
+| Mock the whole chain "to keep the test fast" | Mock only the slow external boundary; keep one real-chain test | An all-mock chain stays green while the real wiring is broken |
+
+## Sources
+
+- https://github.com/EveryInc/compound-engineering-plugin — ce:work "System-Wide Test Check": trace two levels out, real-chain requirement, orphaned-state and interface-parity questions; field-tested in the plugin's shipped review workflow
diff --git a/wiki/testing/strategy/failing-test-first.md b/wiki/testing/strategy/failing-test-first.md
new file mode 100644
index 0000000..2554a44
--- /dev/null
+++ b/wiki/testing/strategy/failing-test-first.md
@@ -0,0 +1,71 @@
+---
+id: testing-strategy-failing-test-first
+domain: testing
+category: strategy
+applies_to: [general]
+confidence: verified
+sources:
+  - https://newsletter.kentbeck.com/p/canon-tdd
+  - https://martinfowler.com/bliki/TestDrivenDevelopment.html
+  - https://github.com/obra/superpowers
+last_verified: 2026-08-22
+related: [testing-quality-tests-that-cannot-fail, testing-quality-minimum-case-set, testing-quality-behavior-not-implementation, debugging-methodology-verify-the-fix]
+---
+
+# Writing the Failing Test Before the Code That Passes It
+
+## When this applies
+
+Implementing new behavior or a bug fix and deciding the order of test and
+production code; production code already exists that no test ever required;
+encoding a bug reproduction as the regression test that
+[debugging-methodology-verify-the-fix] requires.
+
+## Do this
+
+1. Turn the requirement into a test list first: expected behaviors, boundary
+   values, and error paths, chosen per [testing-quality-minimum-case-set] —
+   before writing any test or code.
+2. Write ONE failing test from the list, run it, and read the failure. The
+   first run decides what you do next:
+
+| First run shows | Read as | Do |
+|-----------------|---------|-----|
+| Assertion failure on the missing behavior | RED confirmed | Implement |
+| Import/name/type/setup error | Test-infrastructure defect, not RED | Fix the test setup and rerun until the failure is the behavioral one |
+| Immediate pass | The test pins existing behavior or asserts nothing | For new behavior, rewrite the test until it is red; for existing behavior, prove it can fail by mutation per [testing-quality-tests-that-cannot-fail] |
+
+3. Derive expected values from the requirement, not by running the code under
+   test — an expectation copied from the code's own output inherits the code's
+   bugs as specification ([testing-quality-behavior-not-implementation]).
+4. Write the minimum code that turns the test green; run the new test and the
+   rest of the suite; require both green before the next list item.
+5. Refactor only while green, in behavior-preserving steps, rerunning the suite
+   after each step.
+6. Production code you wrote before its test: delete it and restart from step 2
+   — a test written while the implementation exists gets shaped by what the
+   code does instead of what it should do (large inherited diffs: see Edge
+   cases).
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| Throwaway spike answering a feasibility question | Write it without tests while it cannot ship; when the answer is "build it", delete the spike and rebuild test-first |
+| The fix is config/infra with no code seam to test | Verify by toggling the config both ways against the recorded repro — the config row of [debugging-methodology-verify-the-fix] |
+| A large untested implementation already exists (inherited branch, generated code) | Retrofit proof instead of deleting: write the test list, then prove each test catches a defect by mutation per [testing-quality-tests-that-cannot-fail] |
+| The "new" behavior turns out to already exist (test green on first run) | Confirm by mutation that the test can fail, then drop the duplicate implementation from the plan |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Implement now and add tests after | Write the failing test first | Tests-after describe what the code does; tests-first define what it should do — after-the-fact tests adopt implementation bugs as expectations |
+| Keep pre-test code around "as reference" while writing its tests | Delete it, go red, reimplement | The reference version anchors both test and reimplementation to its own behavior, bugs included |
+| Paste the function's actual output into the assertion | Compute the expectation from the requirement | A mirror assertion passes for any implementation, broken ones included |
+
+## Sources
+
+- https://newsletter.kentbeck.com/p/canon-tdd — Kent Beck's canonical TDD loop: test list → one failing test → make it pass → refactor
+- https://martinfowler.com/bliki/TestDrivenDevelopment.html — write the test first, watch it fail, write the simplest passing code
+- https://github.com/obra/superpowers — test-driven-development skill: verify-RED for the expected reason, delete code written before its test, mirror-assertion ban; field-tested across agentic coding sessions
diff --git a/wiki/testing/strategy/test-level-choice.md b/wiki/testing/strategy/test-level-choice.md
index c7f93f5..504305d 100644
--- a/wiki/testing/strategy/test-level-choice.md
+++ b/wiki/testing/strategy/test-level-choice.md
@@ -9,7 +9,7 @@ sources:
   - https://testing.googleblog.com/2017/04/where-do-our-flaky-tests-come-from.html
   - https://docs.pytest.org/en/stable/how-to/skipping.html
 last_verified: 2026-08-04
-related: [testing-quality-minimum-case-set, testing-mocking-what-to-mock, testing-data-test-data-and-isolation, testing-strategy-import-time-side-effects]
+related: [testing-quality-minimum-case-set, testing-mocking-what-to-mock, testing-data-test-data-and-isolation, testing-strategy-import-time-side-effects, testing-strategy-cross-layer-effect-tests]
 ---
 
 # Choosing the Test Level for a Behavior