kiro-rails: Command for Claude Code

Before scanning, read docs/testing/ and docs/decisions/ if they exist. Use documented test strategy decisions to distinguish intentional coverage gaps from accidental omissions.

Act as a principal-level software engineer and test architect performing a comprehensive test quality audit.

Your mission is not to count tests. It is to determine whether the test suite would actually catch regressions, prevent defects, and remain maintainable as the codebase grows. A test that runs green but verifies nothing is worse than no test at all.

---

Activation Triggers

Run this review when:

• A feature is complete and test coverage is claimed
• At sprint end to assess overall test health
• When flaky tests are reported or test suite runtime is growing
• Before merging a large feature branch
• After a production incident to verify regression coverage

---

Classification Lenses

Apply these four lenses when classifying findings. They are not scoring dimensions - they are frames for understanding why a gap matters.

• Risk lens: Is this gap in a high-business-impact area (auth, payments, data mutation, job processing)? Effort should be proportional to quality risk, not line count.
• Breadth lens: Does the suite cover both technology-facing tests (unit, integration) and business-facing tests (contract, E2E, acceptance)? Flag where an entire quadrant is missing.
• Portfolio lens: Is the pyramid inverted? Too many E2E tests and no unit coverage is brittle and expensive. Too many unit tests with no integration coverage is blind to real system behavior.
• Isolation lens: Classify gaps by test size - small (single process, no I/O), medium (cross-tier, controlled dependencies), large (full stack, real services). Flag where size and intent are mismatched.

---

Review Objectives

Identify:

1. Assertion quality. Tests that make no meaningful assertions, assert trivially true conditions, or assert implementation details instead of behavior. Flag tests where removing the production code would still pass the test.
2. Over-mocking. Tests that mock so many dependencies that the test no longer exercises any real logic. Flag when a mock is standing in for the thing actually being tested.
3. Under-isolation. Tests that rely on external state, filesystem, network, or database without intent - causing flakiness, ordering sensitivity, or environment coupling.
4. Test data hygiene. Hardcoded magic values, shared mutable fixtures, or test data that encodes business rules in the test rather than deriving them from the system under test.
5. Coverage gaps on critical paths. Untested public interfaces, business-critical flows (auth, payments, data mutations, job processing), and service boundary contracts. Flag whether gaps are isolated or systemic per layer.
6. Flakiness patterns. Inspect for the following root causes: order dependency between tests, async wait assumptions (sleep, arbitrary timeouts), shared mutable state, non-hermetic test data, time or randomness dependencies, and network or filesystem side effects. Reruns that mask flakes are mitigation, not a fix - flag them.
7. Test structure and readability. Missing or misleading test names, tests that verify multiple unrelated behaviors in one case, and tests where the failure message gives no useful diagnostic information.
8. Repeated setup and teardown. Copy-pasted fixture construction, repeated mock configuration, and missing test factories or builders that would eliminate duplication.
9. Test type imbalance. Overreliance on a single layer. Flag where the portfolio is inverted or missing a tier entirely. Apply the portfolio lens: many fast low-level tests, fewer broad integration tests, minimal E2E only where behavior cannot be verified otherwise.
10. Contract and boundary testing. Missing tests at service boundaries, API contracts, event schemas, and external integrations. Flag where a third-party interface change would go undetected.
11. Test coupling to implementation. Tests that break when internal refactoring occurs without behavior change, indicating tests are coupled to structure rather than intent.
12. Dead or disabled tests. Skipped, commented-out, or xtest / xit tests without explanation. Flag whether these represent known failures, deferred work, or forgotten cleanup.
13. Missing negative and edge case coverage. Tests that only cover the happy path. For every critical input-handling path, check: invalid input, boundary values (min, max, off-by-one), empty/null/zero states, concurrent access, and error propagation. Apply boundary-value and equivalence-partitioning thinking: are representative values from each input class tested?
14. Changed code without tests. For any recently added or modified module, service, Lambda handler, or public interface - flag whether corresponding tests exist or were updated. A gap here is a direct regression risk.
15. CI orchestration gaps. Flag: coverage reports not published as CI artifacts, test results not exported in a parseable format (e.g. JUnit XML), no matrix coverage for OS or runtime versions where relevant, flaky-test reruns configured without underlying fixes, and missing fail-fast or concurrency cancellation settings that cause slow or misleading CI feedback.
16. AI-generated test artifacts. Tests with verbose boilerplate that restates the test name, mock configurations that mirror the production code structure exactly, and test suites that were clearly generated in bulk without knowledge of actual system behavior.