Integration Test

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Generate/review integration tests using real DI (no mocks) across 5 modes (from-changes · from-prompt · review · diagnose · verify-traceability) that exercise real production paths and assert specific DB field values — so every test protects a traceable business behavior (TC), survives repeated runs without reset, and fails only when the protected intent actually breaks.

Summary:

• Three things make or break a test here: read handler/entity/event source first and assert specific changed fields (never smoke/DI-resolution-only), wrap EVERY DB assertion in async polling (not just async handlers), and drive state through real command/query/seeder paths — never direct repository writes that fabricate invalid state.
• TC traceability is the spine: each test method carries a TC-{FEATURE}-{NNN} test-spec annotation; one business TC maps to MANY tests (1:N, integration + unit), so cover with as many tests as needed — never split a TC to force 1:1, and auto-create a TC in feature-doc Section 8 only for genuinely uncovered business behavior.
• Always search existing tests in the SAME service and read references/integration-test-patterns.md before writing; match local conventions (collection, base class, helpers, unique-name generators) and organize files by domain feature, never by Queries//Commands/ CQRS type.
• Done means repeatable, not green-once: the suite must pass 2 consecutive /integration-test-verify runs WITHOUT a DB reset; the in-skill review/verify modes are lightweight inline passes, distinct from the heavier standalone /integration-test-review and /integration-test-verify skills.
• Main steps (MANDATORY order): (1) FIRST — for business-visible behavior, verify/upsert each TC-{FEATURE}-{NNN} in feature-doc Section 8 (create if missing, update if stale, output TC→method mapping); for technical-only behavior, record TECHNICAL-ONLY — no business TC and use a technical annotation instead; (2) MIDDLE — implement test files with the appropriate annotation, following the project's existing base classes/helpers; (3) FINAL — verify traceability bidirectionally, feature-area-WIDE, across integration AND unit suites (business tests → exactly one doc TC; technical-only tests → TechnicalSpec; every §8 TC in the feature area → ≥1 test, not only TCs this run touched; flag orphans). Per-mode loop: Detect mode → Find targets → Gather context → Execute → Report.
• MANDATORY "Validate: no missing integration tests" task — non-skippable whenever inside a workflow, current git changes exist, or by user request (essentially every run): every changed file has a covering test AND every §8 TC in the feature area has a covering test; zero-GAP table required before marking done.

Workflow: Detect mode → Find targets → Gather context → Execute → Report

Key Rules:

• NEVER write smoke-only tests — read handler/entity/event source first, assert specific field values
• ALWAYS wrap ALL DB assertions in async polling — no exceptions, not just async handlers
• NEVER create invalid test state by direct repository writes; use real use-case paths (commands, queries, production consumers/messages) or valid seeded fixtures
• MUST ATTENTION apply the Real-World Fidelity Gate BEFORE writing setup — a sequence, pacing, or data shape production can never reach proves nothing when green; fix the SCENARIO, never the assertion
• MUST ATTENTION search existing patterns FIRST before generating any test
• MUST ATTENTION READ references/integration-test-patterns.md before writing
• Organize by domain feature NEVER by CQRS type — NEVER create Queries/ or Commands/ folders
• Every test method MUST have a traceability annotation: TestSpec for business §8 coverage or TechnicalSpec for technical-only regression coverage. Auto-create in Section 8 only for genuinely uncovered business behavior.
• Minimum 3 tests per command
• NEVER mark done until the relevant suite passes 2 consecutive /integration-test-verify runs without DB reset

Prerequisites — MUST ATTENTION READ before executing:

references/integration-test-patterns.md — canonical test templates: collection attributes, base class usage, TC annotation format, async polling helpers, unique name generators, DB assertion patterns. Read before writing ANY test.

docs/specs/ — existing TCs by module: read to verify test-to-spec traceability and get TC IDs before generating.

• references/integration-test-patterns.md — canonical test templates (MUST READ before writing any test)
• docs/project-reference/domain-entities-reference.md — domain entity catalog, relationships, cross-service sync
• docs/specs/ — existing TCs by module (read before generating tests; verify test-to-spec traceability)

CRITICAL: Search existing patterns FIRST. Before generating ANY test, grep existing integration test files in same service. Read ≥1 existing test file to match conventions (namespace, usings, collection name, base class, helper usage). NEVER generate tests contradicting established codebase patterns.

CRITICAL: NO Smoke/Fake/Useless Tests. Every test MUST execute actual commands/handlers and verify DB data state. NO DI-resolution-only tests. NO exception-check-only tests. Before writing assertions: READ handler/entity/event source — understand WHAT fields change, WHAT entities created/updated/deleted, WHAT event handlers fire. Assert specific field values.

CRITICAL: Async Polling for ALL Data Assertions. ALWAYS wrap data state assertions in async polling/retry helper. DEFAULT for ALL data verification — not just async handlers. Data persistence may be delayed by event handlers, message bus consumers, background jobs, DB write latency. Rule: If asserting data in DB → use async polling. No exceptions.

For test specifications and test case generation from PBIs, use /spec [mode=tests] skill instead.

Spec-Loop Discipline (property + mutation bar). Where a rule is universal — a [HARD] §4 rule or a §5 invariant that holds for ALL inputs, not just one example — generate a property/metamorphic test (see references/integration-test-patterns.md → Pattern 9) plus a boundary counter-case, and trace each to a §8 Invariant/Property TC (not just an example-scenario TC). The assertion-quality bar is MUTATION-KILL, not line-coverage %: a mutant that survives on the covered core-logic = a missing invariant → write the killing test. (Example-only scenarios stay valid for non-universal behaviors; this is additive for the universal ones.)

External Memory: Complex/lengthy work → write findings to plans/reports/ — prevents context loss.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim requires file:line proof or traced evidence with confidence percentage (>80% act, <80% verify first).

First Principle — Easy to Change

The success metric of every coding decision is future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique exists to serve one goal: making the next change cheaper.

When evaluating code, a refactor, a test, or an abstraction, ask: does this make the next change cheaper or more expensive?

• Reject "best practices" that raise change cost (premature abstraction, speculative generality, leaky indirection, ceremony without payoff).
• Name the real enemies in findings: coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early.
• A simpler design that is easy to change beats a sophisticated design that isn't.

Apply this lens before invoking any specific rule, pattern, or checklist below — if a downstream rule would raise change cost, this principle wins.

Project Pattern Discovery

Before implementation, search codebase for patterns:

• Search: IntegrationTest, TestFixture, TestUserContext, IntegrationTestBase
• Look for: existing test projects, collection definitions, service-specific base classes

MANDATORY IMPORTANT MUST ATTENTION plan task to READ integration-test-reference.md for project-specific patterns and code examples. If not found, continue with search-based discovery.

Workflow:

1. Detect mode — See Mode Detection below
2. Find targets — Identify test/command/query files
3. Gather context — Read relevant files for detected mode
4. Execute — Generate, review, diagnose, or verify
5. Report — Build check (generate), quality report (review), root cause (diagnose)

Key Rules:

• MUST ATTENTION search existing test patterns in same service BEFORE generating
• MUST ATTENTION READ references/integration-test-patterns.md before writing any test
• Organize by domain feature, NEVER by type — command + query tests for same domain → same folder (e.g., Orders/OrderCommandIntegrationTests.*). NEVER create Queries/ or Commands/ folder.
• Use project's unique name generator for ALL string test data
• Use project's entity assertion helpers for DB verification with async polling
• CRITICAL MUST ATTENTION: Test setup MUST mirror real workflows. Do not create or edit domain data through repositories when a command/query/seeder path exists; invalid shortcut data is a test bug.
• CRITICAL MUST ATTENTION: ALWAYS wrap ALL DB assertions in async polling/retry — DEFAULT for ALL assertions, not just async handlers. If asserting data in DB → use async polling. No exceptions.
• CRITICAL MUST ATTENTION: Before writing assertions, READ handler/entity/event source. Understand WHAT fields change, WHAT entities created/updated/deleted, WHAT event handlers fire. Smoke-only FORBIDDEN unless side effect truly unobservable.
• CRITICAL MUST ATTENTION: Verification requires 2 consecutive successful runs of the relevant integration suite/project without resetting data. One green run proves only the current run, not repeatability.
• Minimum 3 test methods: happy path, validation failure, DB state check
• Authorization tests: Multiple user contexts — authorized succeeds AND unauthorized rejected
• Every business test method MUST have // TC-{FEATURE}-{NNN}: Description comment + TestSpec annotation before the method, outside the body. Every technical-only test method MUST have a TechnicalSpec annotation and MUST NOT invent a business TC. Many test methods MAY carry the same TC (one business TC → many tests across components/services); the test-spec annotation is the join key, so cover a TC with as many tests as the implementation needs without inventing extra business TCs.
• No TC in feature docs → auto-create in Section 8 before generating test (auto-create a TC only for genuinely uncovered business behavior — never create a TC just to mirror a new test method when an existing TC already covers that behavior)
• For comprehensive spec generation before coding → /spec [mode=tests] first

Mandatory Task Ordering (MUST ATTENTION FOLLOW)

ALWAYS create and execute tasks in this exact order:

1. FIRST: Verify/upsert test specs in feature docs

   • Read feature doc Section 8 (docs/specs/{App}/README.{Feature}.md) for target domain
   • For each test case: verify matching TC-{FEATURE}-{NNN} exists
   • TC MISSING → create entry in Section 8 with Priority, Status, GIVEN/WHEN/THEN, Evidence
   • TC INCORRECT → update to reflect current behavior
   • Output: TC mapping list (TC code → test method name(s)) — one TC may map to many test methods (across components/services); the mapping is 1 TC : N tests, joined by the TestSpec annotation

2. MIDDLE: Implement integration tests

   • Generate test files using TC mapping from task 1
   • Each test method gets the TC annotation before it (outside the method body) using the configured test framework's attribute/decorator/tag/marker syntax.
   • Follow existing patterns from project's test base classes

3. FINAL: Verify traceability (cardinality: 1 TC : N tests) — scope: WHOLE current feature area, not only this run's TCs

   • Grep test-spec annotations across all test projects/suites for the stack — integration and unit (a TC may be covered by tests in either — grep only the integration project and unit-only-covered TCs falsely look uncovered)
   • Grep every TC-{FEATURE}-{NNN} in Section 8 of all feature doc(s) implicated by this run — doc(s) covering changed files' domain, or user-named feature/domain — including TCs this run did NOT touch. TC pre-dating this run in scope same as one created in step 1.
   • Verify: every business test method → exactly one doc TC (its TestSpec annotation); every technical-only test method → a TechnicalSpec annotation; every doc TC → ≥1 covering test method. One TC may be covered by many test methods (integration + unit, across components/services) — that is the expected one-to-many shape. NEVER require one test per TC, and NEVER split/technicalize a business TC to make tests map 1:1 (breaks the spec's business/user-story orientation, M1/M5 — see tc-format.md → TC ↔ Test Code Cardinality).
   • Flag orphans: tests whose TestSpec TC is absent from §8; technical-only tests that still carry business TestSpec; doc TCs with zero covering tests. (Many tests sharing one TC is NOT an orphan and NOT a duplicate.)
   • Update the CoveredBy field in feature doc TCs with the covering tests — {File}::{MethodName} comma-separated on one line, or a test-filter expression when the set is large (the field is representative; the annotation in code is authoritative). The covering set MAY include unit tests, not only integration tests. Legacy IntegrationTest: is migration input only.

   MANDATORY task — "Validate: no missing integration tests" (non-skippable — three trigger conditions: inside workflow, current git changes present (staged/unstaged), or direct user request — essentially every run; ONLY exception: narrow read-only single-TC lookup, no test generation intended). Create as OWN named TaskCreate item, not folded silently into step 3. Subsumes same bidirectional logic as VERIFY-TRACEABILITY mode below, run every time — not only when user types verify — scoped to feature area:

   1. Every changed command/query/handler/entity/event-handler file in this run has ≥1 covering test (grep + read; name match alone NOT coverage).
   2. Every TC-{FEATURE}-{NNN} in Section 8 of implicated feature doc(s) — FULL set, not only TCs this run created/touched — has ≥1 covering test.
   3. Emit result as table; require zero GAP rows before marking run done:

   TC / Changed File	Covering Test(s)	Status
   TC-{FEATURE}-{NNN} or {file:line}	{file}::{method}[, …] / NONE	COVERED / GAP

   Any GAP row → generate missing test (loop back to Step 3: Generate Test File) before task marked completed. Do NOT report done with open GAP row.

Module Abbreviation Registry

TC Code Numbering Rules

Creating new TC-{FEATURE}-{NNN} codes:

1. Check feature doc first — docs/specs/{App}/README.{Feature}.md has existing codes. New codes must not collide.
2. Decade-based grouping — e.g., OM: 001-004 (CRUD), 011-013 (validation), 021-023 (permissions), 031-033 (events). Find next free decade.
3. Unavoidable collision → renumber in doc only. Keep test-spec annotation unchanged; add renumbering note in doc.
4. Feature doc = canonical registry. Test-spec annotation = traceability only, not numbering source.

Integration Test Generation

Mode Detection

Args = command/query name (e.g., "/integration-test CreateOrderCommand")
  → FROM-PROMPT mode: generate tests for the specified command/query

No args (e.g., "/integration-test")
  → FROM-CHANGES mode: detect changed command/query files from git

Args = "review" (e.g., "/integration-test review Orders")
  → REVIEW mode: audit existing test quality, find flaky patterns, check best practices

Args = "diagnose" (e.g., "/integration-test diagnose OrderCommandIntegrationTests")
  → DIAGNOSE mode: analyze why tests fail — determine test bug vs code bug

Args = "verify" (e.g., "/integration-test verify {Service}")
  → VERIFY-TRACEABILITY mode: check test code matches specs and feature docs

Modes vs. sibling skills (name-collision note). The review and verify modes above are lightweight branches inside this skill — quick, inline audits run during generation. They are NOT the same as the standalone skills /integration-test-review (deep test-quality review) and /integration-test-verify (full spec-traceability verification), which are separate, heavier workflow steps. When the refactor workflow sequences /integration-test → /integration-test-review → /integration-test-verify, those are the standalone skills, not these in-skill modes. Use a mode for a fast pass mid-generation; invoke the sibling skill for a thorough, standalone gate.

Step 1: Find Targets

From-Changes Mode (default)

Run via Bash tool:

git diff --name-only; git diff --cached --name-only

Filter for command/query files using project naming conventions (e.g., *Command.*, *Query.*). Path patterns from docs/project-config.json → modules or backendServices. Extract service from path:

Search codebase for existing *.IntegrationTests.* projects to find correct mapping.

If no test project exists: inform user "No integration test project for {service}. See CLAUDE.md Integration Testing section to create one."

If test file already exists: ask user overwrite or skip.

From-Prompt Mode

User specifies command/query name. Use Grep tool (NOT bash grep):

Grep pattern="{CommandName}" path="{configured-source-root}" glob="{configured-source-glob}"

Step 2: Gather Context

For each target, read in parallel:

1. Command/query file — extract: class name, result type, DTO properties, entity type
2. Existing test files in same service — Glob {Service}.IntegrationTests/**/*IntegrationTests.*, read ≥1 for conventions (collection/suite name, test annotations, namespace/imports, base class)
3. Service integration test base class — grep: class.*ServiceIntegrationTestBase
4. references/integration-test-patterns.md — canonical templates (adapt {Service} placeholders)

Step 2b: Look Up TC Codes

For each target domain, read:

• docs/specs/{App}/README.{Feature}.md Section 8 (primary source)

Build mapping: test case description → TC code (e.g., "create valid order" → TC-OM-001).

• No TC exists → CREATE IT in Section 8 before generating test. NOT optional.
• TC outdated/incorrect → UPDATE IT first.
• Section 8 missing → run /spec [mode=tests] first.

Step 2c: Real-World Fidelity Check (BEFORE any test code is written)

MUST ATTENTION answer this BEFORE the Arrange block exists — never after a failure:

"Can this sequence, timing, and data actually occur in production?"

For each planned test, state:

• Sequence — can a real actor reach these steps, in this order, through the paths under test?
• Pacing — how far apart does production separate consecutive actor actions (milliseconds, seconds, minutes, hours)? Firing two distinct actor actions back-to-back in the same millisecond is a fidelity defect, NOT a test speed-up.
• Data shape — is every seeded value reachable through a real use-case path (see the direct-repository-write ban above)?
• Barrier — for each gap between actor actions, name the observable that proves the prior step settled (persisted state change, audit/version stamp, queue/worker idle marker, completion event) and poll it in ARRANGE.

Any "no" → fix the SCENARIO before writing the test; NEVER compensate afterwards by widening an assertion timeout. Full contract: SYNC:real-world-fidelity-testing below; barrier shape: references/integration-test-patterns.md → Pattern 10.

Step 3: Generate Test File

File path: {project-test-dir}/{Service}.IntegrationTests/{Domain}/{CommandName}IntegrationTests{ext} (adapt path/extension per docs/project-config.json → integrationTestVerify.testProjectPattern)

Folder = domain feature. {Domain} = business domain (Orders, Inventory, Notifications, UserProfiles), NOT CQRS type. Command and query tests for same domain live in same folder.

Structure: adapt file layout, imports, fixture setup, assertion style, and test markers from existing tests in the configured test project.

namespace {Service}.IntegrationTests.{Domain};

[Collection({Service}IntegrationTestCollection.Name)] [Trait("Category", "Command")] // or "Query" public class {CommandName}IntegrationTests : {Service}ServiceIntegrationTestBase { // Minimum 3 tests: happy path, validation failure, DB state verification }

**Test method naming:** `{CommandName}_When{Condition}_Should{Expectation}`

**Required patterns per command type:**

| Command type | Required tests                                     |
| ------------ | -------------------------------------------------- |
| Save/Create  | Happy path + validation failure + DB state         |
| Update       | Create-then-update + verify updated fields in DB   |
| Delete       | Create-then-delete + `AssertEntityDeletedAsync`    |
| Query        | Filter returns results + pagination + empty result |
| **Owns a [HARD] §4 rule or §5 invariant** (orthogonal to the rows above — applies to the same command/query) | **+ Pattern 9 property/metamorphic test** tied to a §8 Invariant/Property TC: the example tests above guard fixed points; the property test guards the rule across its whole input domain (see `references/integration-test-patterns.md` → Pattern 9). FORCED, not optional — a `>`/`>=` flip on the invariant line must fail an assertion. |

> **[FORCED BRANCH — property apparatus]** Pattern 9 is not a "nice-to-have reference". For ANY command/query whose handler enforces a `[HARD]` §4 business rule or a §5 entity invariant, the example-based rows are NOT sufficient on their own — generate the Pattern 9 property test alongside them, carrying the `TestSpec` annotation of the §8 Invariant/Property TC (decade `071–079`). This is the test-side mirror of the spec-side invariant-coverage gate (`spec [mode=tests]` → property TC count ≥ count([HARD] BR) + count(§5 invariants)). Skipping it = a fakeable, over-fitted suite that passes while the rule can be broken across the unenumerated space.

## Step 4: Verify

Build test project via project's build tool (see `/integration-test-verify` for config-driven build).

MUST ATTENTION verify ALL of the following:

- Test collection/group attribute present with correct collection name
- Test category annotation present
- All string test data uses project's unique name generator
- User context created via project's user context factory
- DB assertions use project's entity assertion helpers with async polling
- No mocks — real DI only
- Every test method has `// TC-{FEATURE}-{NNN}: Description` comment + test-spec annotation

## Example Files to Study

Search codebase for existing integration test files:

```bash
find . -name "*IntegrationTests.*" -type f
find . -name "*IntegrationTestBase.*" -type f
find . -name "*IntegrationTestFixture.*" -type f

How to Use for Each Case

Case: Generate tests from existing test specs (feature docs Section 8)

/integration-test CreateOrderCommand

→ Reads Section 8 TCs, generates test file with TC annotations

Case: Generate tests from git changes (default)

/integration-test

→ Detects changed command/query files, checks Section 8 for matching TCs, generates tests

Case: Generate tests after /spec [mode=tests] created new TCs

/spec [mode=tests] → /integration-test

→ spec [mode=tests] writes TCs to Section 8, then integration-test generates tests from those TCs

Case: Review existing tests for quality

/integration-test review Orders

→ Audits test quality, finds flaky patterns, checks best practices

Case: Diagnose test failures

/integration-test diagnose OrderCommandIntegrationTests

→ Analyzes failures, determines test bug vs code bug

Case: Verify test-spec traceability

/integration-test verify {Service}

→ Checks test code matches specs and feature docs bidirectionally

REVIEW Mode — Test Quality Audit

Mode = REVIEW: audit existing integration tests for quality, flaky patterns, best practices.

Sub-Agent Routing

Sub-Agent Type Override

MANDATORY: Integration test REVIEW mode spawns integration-tester sub-agent (subagent_type: "integration-tester"), NOT code-reviewer. Rationale: integration-tester specializes in test spec generation, TC traceability, CQRS test patterns, async-polling / eventual-consistency assertion correctness, and cross-service integration context — areas code-reviewer does not cover at depth.

Fresh Eyes Protocol: Run Round 1 inline. If findings are LOW confidence or contradictory → spawn fresh integration-tester sub-agent (zero memory of Round 1) for Round 2. Main agent reads report, NEVER filters findings. Max 2 rounds, then escalate.

Review Workflow

1. Find test files — Glob {Service}.IntegrationTests/{Domain}/**/*IntegrationTests.*
2. Read each test file — analyze for quality issues (persist findings after each file per SYNC:incremental-persistence)
3. Generate quality report — categorized findings with severity
4. Round 2 (if low confidence): Spawn fresh sub-agent with report path — NEVER re-examine with main context

Review Dimensions

Dimension 1: Reliability — Think: What causes intermittent failures?

• MUST ATTENTION flag missing async polling — DB assertions after async handlers without an await-until-condition poll (the project's async-assertion helper) → WILL flake
• MUST ATTENTION flag missing retry for eventual consistency — message bus / event handler / background job state without polling wrapper
• MUST ATTENTION flag hardcoded delays — Thread.Sleep(), Task.Delay() instead of condition-based polling
• MUST ATTENTION flag race conditions — tests modifying shared state without isolation (same entity ID, same user context)
• MUST ATTENTION flag shared mutable data (see SYNC:test-data-isolation) — assertions hung off a shared mutable entity another test can change, OR off a parent a bulk re-sync/recompute/rebuild/cascade consumer can wipe → not parallel-safe, even without your test mutating it
• MUST ATTENTION flag non-unique test data — hardcoded strings/IDs instead of unique generators
• MUST ATTENTION flag time-dependent assertions — DateTime.Now without time abstraction

Dimension 2: Assertion Value — Think: Does the test actually verify anything?

• MUST ATTENTION flag DI-resolution-only tests — smoke tests that just resolve services → HIGH severity
• MUST ATTENTION flag exception-check-only tests — exception.Should().BeNull() alone → HIGH severity
• MUST ATTENTION verify test reads handler/entity/event source and asserts specific field values
• MUST ATTENTION verify minimum 3 tests per command (happy path, validation failure, DB state)

Dimension 3: Conventions — Think: Does test follow project patterns?

• MUST ATTENTION verify collection/group attribute — correct collection name for shared fixture
• MUST ATTENTION verify category annotation or equivalent test-category marker when the project uses one
• MUST ATTENTION verify TC annotation — every test method has a TC code comment + the test-spec annotation
• MUST ATTENTION verify no mocks — real DI only
• MUST ATTENTION verify unique test data — all string data uses unique generators
• MUST ATTENTION verify user context — via factory, not hardcoded
• MUST ATTENTION verify DB assertions — uses entity assertion helpers, not raw DB queries

Dimension 4: Code Quality — Think: Maintainability and isolation?

• MUST ATTENTION verify method naming — {Action}_When{Condition}_Should{Expectation}
• MUST ATTENTION verify Arrange-Act-Assert — clear separation
• MUST ATTENTION flag logic in tests — conditionals, loops, complex setup in test methods
• MUST ATTENTION verify test independence — each test runs in isolation

Review Report Format

# Integration Test Quality Report — {Domain}

## Summary

- Tests scanned: {N}
- Issues found: {N} (HIGH: {n}, MEDIUM: {n}, LOW: {n})
- Overall quality: {GOOD|NEEDS_WORK|CRITICAL}

## HIGH Severity Issues (Flaky Risk)

| Test         | Issue                                            | Fix                                    |
| ------------ | ------------------------------------------------ | -------------------------------------- |
| {MethodName} | DB assertion without polling after async handler | Wrap in project's async polling helper |

## MEDIUM Severity Issues (Best Practice)

| Test | Issue | Fix |
| ---- | ----- | --- |

## LOW Severity Issues (Style)

| Test | Issue | Fix |
| ---- | ----- | --- |

## Recommendations

1. {Prioritized fix suggestions}

DIAGNOSE Mode — Test Failure Root Cause Analysis

Mode = DIAGNOSE: analyze failing tests to determine test bug vs application code bug.

Diagnose Workflow

1. Identify failing tests — User provides test class name or run test suite to collect failures
2. Read test code — understand what test expects
3. Read application code — trace the command/query handler path
4. Compare expected vs actual — determine root cause
5. Classify — Test bug vs code bug vs infrastructure issue
6. Report — Root cause + recommended fix

Root Cause Decision Tree

Test fails
├── Compilation error?
│   ├── Missing type/method → Code changed, test not updated → TEST BUG
│   └── Wrong import/namespace → TEST BUG
├── Timeout/hang?
│   ├── Missing async/await → TEST BUG
│   ├── Deadlock in handler → CODE BUG
│   └── Infrastructure down → INFRA ISSUE
├── Assertion failure?
│   ├── Expected value wrong?
│   │   ├── Test hardcoded old behavior → TEST BUG
│   │   └── Business logic changed → CODE BUG (if unintended) or TEST BUG (if intended change)
│   ├── Null/empty result?
│   │   ├── Entity not found → Check if create step succeeded → TEST BUG (setup) or CODE BUG (handler)
│   │   └── Query returns empty → Check filters/predicates → CODE BUG
│   ├── Intermittent (passes sometimes)?
│   │   ├── Async assertion without polling → TEST BUG (add async polling/retry)
│   │   ├── Non-unique test data collision → TEST BUG (use unique name generator)
│   │   └── Race condition in handler → CODE BUG
│   └── Wrong/empty count when path under test is provably innocent?
│       ├── Test data leak from other tests → TEST BUG (isolation: own fresh per-test data, not a shared mutable entity)
│       ├── Shared parent wiped by cross-cutting consumer (bulk re-sync, recompute, cascade) → TEST BUG (isolation) — suspect FIRST, grep other tests + consumers before blaming code
│       └── Logic error in query → CODE BUG
├── Validation error (expected success)?
│   ├── Test sends invalid data → TEST BUG
│   └── Validation rule too strict → CODE BUG
└── Exception thrown?
    ├── Known exception type in handler → CODE BUG
    └── DI/config error → INFRA ISSUE

Diagnose Report Format

# Test Failure Diagnosis — {TestClass}

## Failing Tests

| Test Method | Error Type        | Root Cause    | Classification              |
| ----------- | ----------------- | ------------- | --------------------------- |
| {Method}    | {AssertionFailed} | {Description} | TEST BUG / CODE BUG / INFRA |

## Detailed Analysis

### {MethodName}

**Error:** {error message}
**Expected:** {what test expected}
**Actual:** {what happened}
**Root Cause:** {explanation with code evidence}
**Classification:** TEST BUG | CODE BUG | INFRA ISSUE
**Evidence:** `{file}:{line}` — {what the code does}
**Recommended Fix:** {specific fix with code location}

## Summary

- Test bugs: {N} — fix in test code
- Code bugs: {N} — fix in application code
- Infra issues: {N} — fix in configuration/environment

VERIFY-TRACEABILITY Mode — Test ↔ Spec ↔ Feature Doc Verification

Mode = VERIFY: bidirectional traceability check between test code, test specs, feature docs.

Relationship to Mandatory "no missing integration tests" task (Mandatory Task Ordering, step 3). That task already runs SAME bidirectional logic, feature-area-scoped, EVERY run (workflow / git-changes-present / user-request) — not only when user explicitly types verify. This standalone VERIFY mode exists for on-demand, potentially broader (multi-feature-doc or whole-service) traceability sweep user invokes by name — not a separate, narrower obligation. Both apply same run → audit once, satisfy both.

Verify Workflow

1. Collect test methods — Grep for test-spec annotations across all test projects/suites (integration and unit)
2. Collect doc TCs — Read feature doc Section 8 for all TC entries
3. Build 3-way matrix — Test code ↔ specs/ ↔ feature doc Section 8
4. Identify mismatches — Orphans, stale references, behavior drift
5. Classify mismatches — Which source is correct?
6. Report — Traceability matrix + recommended fixes

Mismatch Classification

Rule: Passing code or tests NEVER automatically outrank canonical product/spec intent. NEVER update spec, test, or code on a behavior-changing mismatch until it reaches adjudication-required status with explicit evidence. — why: a green test can encode a regression, so code agreement alone cannot ratify a spec change.

Verification Requirements

MUST ATTENTION verify ALL of the following:

• Every test method has matching TC in feature doc Section 8
• Every TC in Section 8 has matching test method (or marked Status: Untested)
• TC descriptions in docs match what test actually validates
• Evidence file paths in TCs point to current (not stale) code locations
• Business TestSpec annotations match TC IDs (no typos, no orphaned IDs); technical-only tests use TechnicalSpec and do not create §8 obligations
• Priority levels in docs match test categorization
• docs/specs/ dashboard is in sync with feature doc Section 8

Verify Report Format

# Traceability Report — {Service}

## Summary

- TCs in feature docs: {N}
- Test methods with TC annotations: {N}
- Fully traced (both directions): {N}
- Orphaned tests (no matching TC): {N}
- Orphaned TCs (no matching test): {N}
- Mismatched behavior: {N}

## Traceability Matrix

| TC ID     | Feature Doc? | Test Code? | Dashboard? | Status       |
| --------- | ------------ | ---------- | ---------- | ------------ |
| TC-OM-001 | ✅           | ✅         | ✅         | Traced       |
| TC-OM-005 | ✅           | ❌         | ✅         | Missing test |
| TC-OM-010 | ❌           | ✅         | ❌         | Missing spec |

## Orphaned Tests (no matching TC in docs)

| Test File | Method   | Annotation | Action                   |
| --------- | -------- | ---------- | ------------------------ |
| {file}    | {method} | TC-OM-010  | Create TC in feature doc |

## Orphaned TCs (no matching test)

| TC ID     | Doc Location | Priority | Action                              |
| --------- | ------------ | -------- | ----------------------------------- |
| TC-OM-005 | Section 8    | P0       | Generate test via /integration-test |

## Behavior Mismatches

| TC ID | Doc Says | Test Does | Correct Source | Action |
| ----- | -------- | --------- | -------------- | ------ |

## Recommendations

1. {Prioritized actions}

Test Data Setup Guidelines

| Pattern | When to Use | Example

…(truncated)