5 added, 1 removed. Audit A to A.
---
name: "wow-debug"
- description: "Diagnose observed Wow failures, hangs, missing handlers, incorrect sourced state, retry or wait problems, runtime failures, and failing tests by reproducing and locating the failing stage. Use only when the failure involves Wow framework pipeline behavior — commands, sourcing, event processing, projection, or runtime stages — for diagnosis-only and diagnose-and-fix requests; remain read-only until a fix is explicitly requested. Do not use for proactive diff review, planned feature development, failures in projects that do not use the Wow framework, or failures inside a breaking migration or storage/data cutover centered on migration, reconciliation, rollout, or rollback."
+ description: "Diagnose observed Wow pipeline failures in downstream apps, optionally fixing with authorization. Activate only for explicit failing Wow behavior or scoped me.ahoo.wow imports/wow-* dependencies; generic DDD/CQRS or checkout-wide markers do not qualify. Exclude the Wow framework repository, non-Wow scopes, proactive review/development, and migration/data-cutover failures."
---
# Debug Wow Failures
+
+ ## Scope gate
+
+ Use only to diagnose a downstream application's failure; the Wow framework repository and its modules never qualify. Require the failing path to involve Wow, shown by scoped `me.ahoo.wow` imports, `wow-*` dependencies, or explicit failing Wow behavior. Checkout-wide markers, negated/comparative mentions, and generic DDD/CQRS vocabulary do not qualify. Otherwise state that this Skill does not apply and stop using it.
Own the complete diagnosis or diagnose-and-fix task. Do not route to another Wow Skill.
## Contract
- Keep diagnosis-only requests read-only.
- Attempt the narrowest safe, non-mutating reproduction before explaining. If reproduction is unavailable, unsafe, or outside authorization, state that limit and use the strongest available evidence.
- Prefer one falsifiable hypothesis over a list of speculative causes.
- Compare with a working path in the same checkout.
- Do not add retries, relax assertions, or change annotations before proving where the pipeline breaks.
## Diagnostic workflow
1. **Capture**: record the exact command, request, event, test, configuration, log, stack trace, timing, and expected behavior.
2. **Reproduce**: run the narrowest safe, non-mutating reproducer and preserve its exact result. If that is impossible or unauthorized, record the constraint and continue from logs, traces, source, tests, and configuration without inventing a reproducer.
3. **Locate**: use `references/pipeline-map.md` to identify the first incorrect stage.
4. **Discover**: inspect definitions, metadata generation, registration, routing, delivery, invocation, persistence, and observation only as far as the symptom requires.
5. **Hypothesize**: state “stage X fails because Y” and identify evidence that would falsify it.
6. **Test**: run the smallest diagnostic or focused test that distinguishes the hypothesis.
7. **Conclude**: name the confirmed failing stage, cause, affected boundary, and remaining unknowns.
Load `references/handler-discovery.md` only when a handler is missing, unregistered, unmatched, or unselected. Do not run its metadata/JAR discovery path for ordinary configuration, Query DSL, lifecycle, or assertion failures.
## Diagnose-and-fix
Only when the user requests a fix:
1. Preserve the reproducer or add a failing regression test.
2. Make the smallest change that addresses the confirmed cause.
3. Run the focused reproducer and relevant regression checks.
4. Inspect the resulting diff for altered contracts or adjacent pipeline risk.
Do not combine independent hypotheses into one patch.
## Completion
For diagnosis-only work, report the reproducer or the precise reason it was unavailable, the failing stage, confirmed evidence, affected scope, and unknowns without claiming a fix. For an authorized fix, also report pre-fix evidence, changed files and behavior, exact verification commands and results, and residual operational risk.