| name | wow-code-review |
| description | Use when reviewing Wow framework code, PR diffs, or pre-merge changes involving aggregates, commands, events, sourcing, sagas, projections, command gateway, Query DSL, starter configuration, or Wow tests |
Wow Code Review
Review Wow code for framework semantics first, style second. The goal is to catch event-sourcing, CQRS, routing, and test-coverage mistakes before they become production behavior.
Iron Laws
- No aggregate behavior without focused
AggregateSpec or verifier coverage.
- No saga branch without trigger and no-command coverage when conditions branch.
- No command handler may mutate aggregate state directly.
- No sourcing handler may perform side effects or non-deterministic work.
- No configuration claim without checking current
@ConfigurationProperties.
- No approval without exact verification evidence.
Review Flow
- Scope the diff: list touched modules and files. Resolve module names from
settings.gradle.kts.
- Load context: use
../wow/SKILL.md as router. Load only the relevant reference files such as ../wow/references/modeling.md, ../wow/references/annotations.md, or ../wow/references/testing.md.
- Find working examples: use
rg to compare with nearby aggregate, saga, projection, query, or configuration code.
- Review by semantics: check the lists below before naming style or formatting issues.
- Verify tests: identify the narrowest Gradle command that proves the changed behavior.
Semantic Checklist
| Area | Check |
|---|
| Aggregate | Command handlers return events, enforce invariants, and do not mutate state. |
| State | State changes are deterministic and sourced from events. |
| Events | Event payloads are sufficient to rebuild state and preserve compatibility. |
| API metadata | Commands and domain events include @Summary and @Description; long descriptions use raw string annotation syntax. |
| Field contracts | Important repeated domain fields are extracted into <FieldName>Capable interfaces when reuse improves the model. |
| Routing | Aggregate ID, owner, tenant, and command route rules are explicit and tested. |
| Polymorphic returns | Any or multi-event returns declare metadata when current APIs require it. |
| Saga | Trigger, no-command, multi-command, and dependency branches are tested. |
| Projection/EventProcessor | Side effects stay outside aggregates; retry behavior is intentional and annotation-driven. |
| Query DSL | Uses current condition, pagination, projection, and sort APIs. |
| Configuration | Examples match current @ConfigurationProperties classes. |
| Tests | Use .assert(), cover error paths, lifecycle paths, and branch conditions. |
Red Flags
- "This aggregate is simple, tests can come later."
- A command handler sets state fields directly.
- Sourcing calls services, clocks, random IDs, databases, or buses.
- Saga has only happy-path tests.
- Projection updates are not idempotent enough for retries.
- Review accepts a config key without checking source properties.
- Verification says "should pass" instead of showing the command.
Findings Format
Lead with findings, ordered by severity. Use file and line references.
Critical: breaks correctness or event-sourcing guarantees.
Important: likely bug, missing behavior coverage, or framework misuse.
Minor: clarity, maintainability, naming, or follow-up improvement.
If there are no findings, say that directly and name residual risks or test gaps.
