ronce-racine 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/AGENTS.md +90 -0
  2. package/LICENSE +21 -0
  3. package/README.md +281 -0
  4. package/agents/code-reviewer.md +33 -0
  5. package/agents/qa-tester.md +28 -0
  6. package/dist/hooks/README.md +182 -0
  7. package/dist/hooks/bash-npm-silent.mjs +81 -0
  8. package/dist/hooks/session-inject.mjs +53 -0
  9. package/dist/hooks/session-precompact.mjs +36 -0
  10. package/dist/hooks/session-writer.mjs +142 -0
  11. package/dist/hooks/skill-reminder.mjs +89 -0
  12. package/dist/hooks/truncate-bash-output.mjs +46 -0
  13. package/dist/hooks/truncate-output.mjs +88 -0
  14. package/dist/hooks/worktree-env-setup.mjs +123 -0
  15. package/dist/install.js +962 -0
  16. package/docs/adopting-a-repo.md +80 -0
  17. package/docs/architecture.md +76 -0
  18. package/docs/decisions.md +72 -0
  19. package/docs/developing.md +143 -0
  20. package/docs/evaluating-skills.md +41 -0
  21. package/docs/git-worktrees.md +62 -0
  22. package/docs/rules/clean-architecture-deps.md +66 -0
  23. package/docs/rules/commits.md +59 -0
  24. package/docs/rules/detection-gap-protocol.md +55 -0
  25. package/docs/rules/error-handling-discipline.md +62 -0
  26. package/docs/rules/minimal-code.md +58 -0
  27. package/docs/rules/no-raw-sql-interpolation.md +57 -0
  28. package/docs/rules/pre-commit-secret-detection.md +54 -0
  29. package/docs/rules/secure-logging.md +53 -0
  30. package/docs/rules/sql-migrations-discipline.md +58 -0
  31. package/docs/rules/subscription-cleanup.md +63 -0
  32. package/docs/rules/test-discipline.md +66 -0
  33. package/docs/rules/ui-states-complete.md +52 -0
  34. package/docs/templates/SKILL.template.md +66 -0
  35. package/docs/templates/rule.template.md +16 -0
  36. package/docs/writing-a-rule.md +43 -0
  37. package/docs/writing-a-skill.md +118 -0
  38. package/package.json +45 -0
  39. package/rules/clean-architecture-deps.md +20 -0
  40. package/rules/commits.md +16 -0
  41. package/rules/detection-gap-protocol.md +35 -0
  42. package/rules/error-handling-discipline.md +23 -0
  43. package/rules/minimal-code.md +32 -0
  44. package/rules/no-raw-sql-interpolation.md +20 -0
  45. package/rules/pre-commit-secret-detection.md +14 -0
  46. package/rules/secure-logging.md +16 -0
  47. package/rules/sql-migrations-discipline.md +18 -0
  48. package/rules/subscription-cleanup.md +22 -0
  49. package/rules/test-discipline.md +20 -0
  50. package/rules/ui-states-complete.md +23 -0
  51. package/scripts/subscription-leak-scan.ts +53 -0
  52. package/skills/adversarial-feature-challenge/README.md +65 -0
  53. package/skills/adversarial-feature-challenge/SKILL.md +96 -0
  54. package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
  55. package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
  56. package/skills/api-contract-versioning/README.md +62 -0
  57. package/skills/api-contract-versioning/SKILL.md +76 -0
  58. package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
  59. package/skills/audit-architecture/README.md +56 -0
  60. package/skills/audit-architecture/SKILL.md +97 -0
  61. package/skills/audit-architecture/reference/ar-architecture.md +275 -0
  62. package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
  63. package/skills/audit-architecture/reference/im-incidents.md +217 -0
  64. package/skills/audit-architecture/reference/pa-pannes.md +362 -0
  65. package/skills/audit-architecture/reference/re-recuperation.md +300 -0
  66. package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
  67. package/skills/audit-architecture/reference/su-support.md +180 -0
  68. package/skills/audit-ci-cd/README.md +54 -0
  69. package/skills/audit-ci-cd/SKILL.md +124 -0
  70. package/skills/audit-ci-cd/reference/artefacts.md +39 -0
  71. package/skills/audit-ci-cd/reference/deploiement.md +100 -0
  72. package/skills/audit-ci-cd/reference/dora.md +94 -0
  73. package/skills/audit-ci-cd/reference/iac.md +40 -0
  74. package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
  75. package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
  76. package/skills/audit-compliance/README.md +69 -0
  77. package/skills/audit-compliance/SKILL.md +176 -0
  78. package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
  79. package/skills/audit-compliance/reference/finops.md +318 -0
  80. package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
  81. package/skills/audit-industrialisation/README.md +53 -0
  82. package/skills/audit-industrialisation/SKILL.md +251 -0
  83. package/skills/audit-observability/README.md +64 -0
  84. package/skills/audit-observability/SKILL.md +134 -0
  85. package/skills/audit-observability/reference/alerting.md +214 -0
  86. package/skills/audit-observability/reference/logging.md +114 -0
  87. package/skills/audit-observability/reference/metriques.md +166 -0
  88. package/skills/audit-observability/reference/traces-dashboards.md +90 -0
  89. package/skills/audit-performance-frontend/README.md +91 -0
  90. package/skills/audit-performance-frontend/SKILL.md +194 -0
  91. package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
  92. package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
  93. package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
  94. package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
  95. package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
  96. package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
  97. package/skills/audit-quality/README.md +85 -0
  98. package/skills/audit-quality/SKILL.md +126 -0
  99. package/skills/audit-quality/reference/qa-devops.md +539 -0
  100. package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
  101. package/skills/audit-report/README.md +72 -0
  102. package/skills/audit-report/SKILL.md +241 -0
  103. package/skills/audit-report/reference/scoring-model.md +45 -0
  104. package/skills/audit-security/README.md +72 -0
  105. package/skills/audit-security/SKILL.md +140 -0
  106. package/skills/audit-security/reference/auth-identite.md +98 -0
  107. package/skills/audit-security/reference/autorisation.md +66 -0
  108. package/skills/audit-security/reference/chiffrement-tls.md +97 -0
  109. package/skills/audit-security/reference/detection-patching.md +67 -0
  110. package/skills/audit-security/reference/incident-response.md +98 -0
  111. package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
  112. package/skills/audit-security/reference/secrets.md +36 -0
  113. package/skills/audit-testing/README.md +82 -0
  114. package/skills/audit-testing/SKILL.md +131 -0
  115. package/skills/audit-testing/reference/golden-dataset.md +65 -0
  116. package/skills/audit-testing/reference/resilience-chaos.md +93 -0
  117. package/skills/audit-testing/reference/tests-contractuels.md +65 -0
  118. package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
  119. package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
  120. package/skills/bug-ticket-root-cause/README.md +67 -0
  121. package/skills/bug-ticket-root-cause/SKILL.md +86 -0
  122. package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
  123. package/skills/bug-triage-structured/README.md +63 -0
  124. package/skills/bug-triage-structured/SKILL.md +104 -0
  125. package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
  126. package/skills/ci-pipeline-orchestration/README.md +55 -0
  127. package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
  128. package/skills/commit-readiness-review/README.md +66 -0
  129. package/skills/commit-readiness-review/SKILL.md +82 -0
  130. package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
  131. package/skills/comprehensive-test-strategy/README.md +64 -0
  132. package/skills/comprehensive-test-strategy/SKILL.md +108 -0
  133. package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
  134. package/skills/daily-workflow-optimization/README.md +56 -0
  135. package/skills/daily-workflow-optimization/SKILL.md +80 -0
  136. package/skills/database-schema-evolution/README.md +54 -0
  137. package/skills/database-schema-evolution/SKILL.md +107 -0
  138. package/skills/ddd-backend-implementation/README.md +63 -0
  139. package/skills/ddd-backend-implementation/SKILL.md +95 -0
  140. package/skills/design-system-component-lifecycle/README.md +56 -0
  141. package/skills/design-system-component-lifecycle/SKILL.md +97 -0
  142. package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
  143. package/skills/detection-sweep/README.md +58 -0
  144. package/skills/detection-sweep/SKILL.md +93 -0
  145. package/skills/detection-sweep/scripts/sweep.ts +80 -0
  146. package/skills/domain-modeling-design/README.md +57 -0
  147. package/skills/domain-modeling-design/SKILL.md +83 -0
  148. package/skills/frontend-fullstack-implementation/README.md +60 -0
  149. package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
  150. package/skills/frontend-spec-call-site-audit/README.md +66 -0
  151. package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
  152. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
  153. package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
  154. package/skills/merge-request-review/README.md +60 -0
  155. package/skills/merge-request-review/SKILL.md +77 -0
  156. package/skills/merge-request-review/templates/mr-review-report.md +29 -0
  157. package/skills/production-incident-diagnostic/README.md +63 -0
  158. package/skills/production-incident-diagnostic/SKILL.md +103 -0
  159. package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
  160. package/skills/qa-session-intake/README.md +56 -0
  161. package/skills/qa-session-intake/SKILL.md +78 -0
  162. package/skills/recording-decisions/README.md +91 -0
  163. package/skills/recording-decisions/SKILL.md +84 -0
  164. package/skills/recurring-bug-root-cause/README.md +64 -0
  165. package/skills/recurring-bug-root-cause/SKILL.md +93 -0
  166. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
  167. package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
  168. package/skills/refactoring-shared-component-api/README.md +50 -0
  169. package/skills/refactoring-shared-component-api/SKILL.md +84 -0
  170. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
  171. package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
  172. package/skills/validating-features-end-to-end/README.md +50 -0
  173. package/skills/validating-features-end-to-end/SKILL.md +90 -0
  174. package/skills/visual-regression-check/README.md +51 -0
  175. package/skills/visual-regression-check/SKILL.md +89 -0
  176. package/skills/writing-robust-tests/README.md +53 -0
  177. package/skills/writing-robust-tests/SKILL.md +88 -0
  178. package/templates/.adopted.example +8 -0
  179. package/templates/anti-drift.gitlab-ci.yml +23 -0
@@ -0,0 +1,93 @@
1
+ # Resilience & chaos section
2
+
3
+ Questions: te-04 (Chaos testing), te-05 (Third-party API outage simulation), te-06 (Historical batch replay).
4
+
5
+ ## Table of contents
6
+
7
+ - [te-04 - Chaos testing](#te-04--chaos-testing--could)
8
+ - [te-05 - Third-party API outage simulation](#te-05--third-party-api-outage-simulation--should)
9
+ - [te-06 - Historical batch replay](#te-06--historical-batch-replay--could)
10
+
11
+ ---
12
+
13
+ ### te-04 - Chaos testing - `could`
14
+
15
+ **Analyze:** Chaos Monkey, Litmus, Gremlin configs, failure-simulation scripts, game days
16
+
17
+ **Commands:**
18
+ - `grep -ri "chaos\|gremlin\|litmus\|chaos.monkey\|toxiproxy" package.json docker-compose*.yml 2>/dev/null` → chaos-testing tools
19
+ - `find . -name "*chaos*" -o -name "*resilience*" 2>/dev/null | grep -v node_modules | head -10` → chaos-related files
20
+ - `grep -ri "game.day\|disaster.recovery\|chaos" docs/ 2>/dev/null | head -5` → chaos/resilience documentation
21
+ - `grep -ri "circuit.breaker\|fallback\|timeout\|retry" src/ lib/ 2>/dev/null | head -10` → resilience patterns in the code
22
+ - `grep -ri "steady.state\|hypothesis" docs/ 2>/dev/null | head -5` → documented resilience hypotheses
23
+
24
+ **Check:**
25
+ - Chaos-engineering practice (even basic)
26
+ - Failure simulation (kill service, network latency, DB loss)
27
+ - Planned game days
28
+ - Documented resilience hypotheses (steady-state)
29
+
30
+ **Levels:**
31
+ | Level | Criteria |
32
+ |-------|----------|
33
+ | 0 | No chaos testing. Weaknesses discovered in production. |
34
+ | 1 | Occasional manual service-kill tests. |
35
+ | 2 | Basic chaos monkey in a non-prod environment. Limited scenarios. |
36
+ | 3 | Chaos test suite (Gremlin, LitmusChaos). Quarterly game days. Documented hypotheses. |
37
+ | 4 | Chaos engineering in production (controlled). Automated steady-state verification. Continuous chaos. |
38
+
39
+ ---
40
+
41
+ ### te-05 - Third-party API outage simulation - `should`
42
+
43
+ **Analyze:** API resilience tests, fault proxies (Toxiproxy, WireMock), circuit breakers, fallbacks, timeout tests
44
+
45
+ **Commands:**
46
+ - `grep -ri "toxiproxy\|wiremock\|mockserver\|nock\|msw\|mock.service.worker" package.json 2>/dev/null` → simulation tools
47
+ - `grep -ri "circuit.breaker\|circuitbreaker\|fallback\|resilience4j\|polly\|opossum" . --include="*.ts" --include="*.js" --include="*.java" --include="*.php" 2>/dev/null | grep -v node_modules | head -10` → resilience patterns
48
+ - `grep -ri "timeout\|TIMEOUT\|connectTimeout\|readTimeout" . --include="*.ts" --include="*.js" --include="*.env*" --include="*.php" 2>/dev/null | grep -v node_modules | head -10` → timeout configuration
49
+ - `grep -ri "fault.*inject\|inject.*fault\|chaos.*mesh" . 2>/dev/null | grep -v node_modules | head -5` → fault injection
50
+ - `grep -ri "mock.*api\|stub.*api\|fake.*api" . --include="*.test.*" --include="*.spec.*" 2>/dev/null | grep -v node_modules | head -10` → API mocks in the tests
51
+
52
+ **Check:**
53
+ - Simulation of third-party API outages (latency, errors, timeout)
54
+ - Circuit breakers configured and tested
55
+ - Fallbacks functional and validated
56
+ - Automated tests of degradation scenarios
57
+
58
+ **Levels:**
59
+ | Level | Criteria |
60
+ |-------|----------|
61
+ | 0 | Never simulated. Behavior unknown if an API is down. |
62
+ | 1 | Occasional manual test (unplug the network). |
63
+ | 2 | API mocking with fault injection. Basic automated tests. |
64
+ | 3 | Systematic fault injection (latency, errors, timeouts). Fallback validation. |
65
+ | 4 | Toxiproxy/Chaos Mesh integrated. Tests of every failure combination. Automated recovery validation. |
66
+
67
+ ---
68
+
69
+ ### te-06 - Historical batch replay - `could`
70
+
71
+ **Analyze:** Ability to replay past processing, shadow traffic, result comparison, data pipelines
72
+
73
+ **Commands:**
74
+ - `grep -ri "replay\|rejeu\|shadow\|reprocess" . --include="*.sh" --include="*.py" --include="*.ts" --include="*.php" 2>/dev/null | grep -v node_modules | head -10` → replay scripts
75
+ - `grep -ri "batch\|etl\|cron\|schedule\|queue\|job" . --include="*.php" --include="*.ts" --include="*.py" 2>/dev/null | grep -v node_modules | head -10` → batch/cron processing
76
+ - `find . -name "*batch*" -o -name "*etl*" -o -name "*migration*" -o -name "*replay*" 2>/dev/null | grep -v node_modules | head -10` → batch-related files
77
+ - `grep -ri "idempoten\|deterministic\|replayable" . 2>/dev/null | grep -v node_modules | head -5` → replayability patterns
78
+ - `grep -ri "temporal\|airflow\|flink\|dbt" package.json docker-compose*.yml 2>/dev/null` → orchestration tools
79
+
80
+ **Check:**
81
+ - Ability to replay past processing with the original data
82
+ - Anonymized historical data available for replay
83
+ - Automatic result comparison (old vs new)
84
+ - Idempotency of batch processing
85
+
86
+ **Levels:**
87
+ | Level | Criteria |
88
+ |-------|----------|
89
+ | 0 | No replay capability. Tests with synthetic data only. |
90
+ | 1 | Manual replay possible but complex. No process. |
91
+ | 2 | Replay capability on a dedicated environment. Anonymized data. |
92
+ | 3 | Automated replay pipeline. Comparison against expected results. Performance metrics. |
93
+ | 4 | Shadow traffic in production. A/B testing of changes. Automatic regression detection. |
@@ -0,0 +1,65 @@
1
+ # Contract testing section
2
+
3
+ Questions: te-01 (Contract testing with third-party APIs), te-01a (Coverage of tested contracts).
4
+
5
+ ## Table of contents
6
+
7
+ - [te-01 - Contract testing with third-party APIs](#te-01--contract-testing-with-third-party-apis--could)
8
+ - [te-01a - Coverage of tested contracts](#te-01a--coverage-of-tested-contracts--could)
9
+
10
+ ---
11
+
12
+ ### te-01 - Contract testing with third-party APIs - `could`
13
+
14
+ **Analyze:** Pact tests, contract tests, external API mocks, `.pact/` files, contract-testing configs, OpenAPI schema validation
15
+
16
+ **Commands:**
17
+ - `grep -r "pact\|contract" package.json 2>/dev/null` → detect Pact or contract testing
18
+ - `find . -path "*/.pact/*" -o -name "*contract*test*" -o -name "*pact*" 2>/dev/null | grep -v node_modules | head -10` → contract test files
19
+ - `grep -ri "spring.cloud.contract\|contract.verifier" pom.xml build.gradle 2>/dev/null` → Spring Cloud Contract
20
+ - `grep -ri "consumer.*driven\|provider.*verification" . --include="*.ts" --include="*.js" 2>/dev/null | head -5` → CDC patterns
21
+ - `grep -ri "openapi\|swagger\|json.schema\|spectral\|prism" . --include="*.json" --include="*.yaml" --include="*.yml" 2>/dev/null | grep -v node_modules | head -5` → API schema validation
22
+
23
+ **Check:**
24
+ - Presence of contract tests (Pact, Spring Cloud Contract)
25
+ - Consumer-Driven Contracts for consumed APIs
26
+ - Schema validation (OpenAPI, JSON Schema)
27
+ - Bidirectional tests (provider + consumer)
28
+
29
+ **Levels:**
30
+ | Level | Criteria |
31
+ |-------|----------|
32
+ | 0 | No contract tests. Breaking changes discovered in production. |
33
+ | 1 | Occasional manual tests against the APIs. No CI. |
34
+ | 2 | Versioned API-response snapshots. Manual or semi-automated comparison. |
35
+ | 3 | Contract testing (Pact, Spring Cloud Contract) integrated into CI. Drift alerts. |
36
+ | 4 | Consumer-driven contracts. Bidirectional tests. Automatic breaking-change prevention. |
37
+
38
+ ---
39
+
40
+ ### te-01a - Coverage of tested contracts - `could`
41
+
42
+ **Condition:** Applies if te-01 ≥ 2 (contract testing in place).
43
+
44
+ **Analyze:** Coverage matrix of third-party APIs, integration inventory, prioritization by business criticality
45
+
46
+ **Commands:**
47
+ - `grep -ri "pact\|contract\|api.*test" . --include="*.test.*" --include="*.spec.*" 2>/dev/null | grep -v node_modules | wc -l` → number of contract tests
48
+ - `grep -ri "http\|fetch\|axios\|guzzle\|curl" . --include="*.ts" --include="*.js" --include="*.php" --include="*.py" 2>/dev/null | grep -v node_modules | grep -v test | head -20` → API calls in the source code
49
+ - `find . -name "*.pact.json" -o -name "*contract*.json" 2>/dev/null | grep -v node_modules | head -10` → published contracts
50
+ - `grep -ri "can.i.deploy\|pactflow\|pact.broker" . 2>/dev/null | head -5` → contract broker and can-i-deploy
51
+
52
+ **Check:**
53
+ - Percentage of third-party APIs covered by contract tests
54
+ - Maintained coverage matrix (APIs vs tests)
55
+ - Risk-based prioritization (critical APIs covered first)
56
+ - Auto-discovery of new uncovered integrations
57
+
58
+ **Levels:**
59
+ | Level | Criteria |
60
+ |-------|----------|
61
+ | 0 | No API covered. |
62
+ | 1 | Critical APIs only (payment, auth). |
63
+ | 2 | Main APIs (>50% of traffic). |
64
+ | 3 | All APIs with an SLA. Coverage matrix maintained. |
65
+ | 4 | 100% of integrations. Auto-discovery of new endpoints. |
@@ -0,0 +1,67 @@
1
+ # E2E & flaky tests section
2
+
3
+ Questions: te-03 (Full-injection E2E tests), te-03a (Flaky test management).
4
+
5
+ ## Table of contents
6
+
7
+ - [te-03 - Full-injection E2E tests](#te-03--full-injection-e2e-tests--should)
8
+ - [te-03a - Flaky test management](#te-03a--flaky-test-management--should)
9
+
10
+ ---
11
+
12
+ ### te-03 - Full-injection E2E tests - `should`
13
+
14
+ **Analyze:** Playwright, Cypress, Selenium files, e2e configs, e2e scripts in package.json
15
+
16
+ **Commands:**
17
+ - `ls playwright.config.* cypress.config.* 2>/dev/null` → detect the E2E framework
18
+ - `find . -name "*.e2e.*" -o -name "*.e2e-spec.*" 2>/dev/null | grep -v node_modules | wc -l` → count the E2E tests
19
+ - `find . -name "*.e2e.*" -o -name "*.e2e-spec.*" 2>/dev/null | grep -v node_modules | head -10` → list the E2E tests
20
+ - `grep -E "e2e|playwright|cypress|selenium" package.json 2>/dev/null` → E2E scripts in package.json
21
+ - `grep -E "e2e|playwright|cypress" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → E2E in CI
22
+ - `grep -ri "visual.*regress\|screenshot\|toMatchSnapshot\|toHaveScreenshot" . --include="*.ts" --include="*.js" 2>/dev/null | grep -v node_modules | head -5` → visual regression testing
23
+
24
+ **Check:**
25
+ - E2E framework configured (Playwright, Cypress)
26
+ - Coverage of critical journeys (happy path + error paths)
27
+ - Execution in the CI pipeline
28
+ - Prod-like test environment
29
+
30
+ **Levels:**
31
+ | Level | Criteria |
32
+ |-------|----------|
33
+ | 0 | No automated E2E tests. Manual validation only. |
34
+ | 1 | A few documented manual E2E tests. Run before a major release. |
35
+ | 2 | Automated E2E suite for happy paths. Dedicated environment. Frequent flaky tests. |
36
+ | 3 | Complete E2E (happy + error paths). Stable. Integrated into CI/CD. Detailed reporting. |
37
+ | 4 | E2E in a prod-like environment. Canary testing. Visual regression. Performance baselines. |
38
+
39
+ ---
40
+
41
+ ### te-03a - Flaky test management - `should`
42
+
43
+ **Condition:** Applies if te-03 ≥ 2 (automated E2E suite in place).
44
+
45
+ **Analyze:** Retry configs (jest.retryTimes, Playwright retries), test reports, quarantine, flakiness metrics
46
+
47
+ **Commands:**
48
+ - `grep -r "retry\|retries\|flaky" vitest.config.* playwright.config.* jest.config.* 2>/dev/null` → retry configuration
49
+ - `grep -rn "\.skip\|xdescribe\|xit\|test\.skip\|it\.skip" . --include="*.test.*" --include="*.spec.*" 2>/dev/null | grep -v node_modules | wc -l` → count skipped tests
50
+ - `grep -ri "quarantine\|flaky\|unstable" . --include="*.test.*" --include="*.spec.*" 2>/dev/null | grep -v node_modules | head -10` → tests marked flaky/quarantine
51
+ - `grep -ri "retryTimes\|jest.retryTimes" . --include="*.test.*" --include="*.spec.*" 2>/dev/null | grep -v node_modules | head -5` → test-level retry
52
+ - `grep -ri "buildpulse\|flaky.*detect\|flaky.*track" . 2>/dev/null | head -5` → flakiness-tracking tools
53
+
54
+ **Check:**
55
+ - Flaky-test detection mechanism
56
+ - Quarantine policy (isolation vs immediate fix)
57
+ - Flakiness rate measured and tracked
58
+ - Systematic root-cause analysis
59
+
60
+ **Levels:**
61
+ | Level | Criteria |
62
+ |-------|----------|
63
+ | 0 | Flaky tests ignored or disabled. |
64
+ | 1 | Automatic retry. No root-cause analysis. |
65
+ | 2 | Flaky tests quarantined. Fix prioritized but not systematic. |
66
+ | 3 | Mandatory fix process. Flakiness metrics. Resolution SLA. |
67
+ | 4 | Near-zero flakiness (<1%). Automatic detection. Systematic root-cause analysis. |
@@ -0,0 +1,125 @@
1
+ # Unit, integration & CI tests section
2
+
3
+ Questions: te-07 (Unit test structure), te-08 (Integration test structure), te-09 (Test execution in CI), te-09a (Test feedback loop).
4
+
5
+ ## Table of contents
6
+
7
+ - [te-07 - Unit test structure](#te-07--unit-test-structure--must)
8
+ - [te-08 - Integration test structure](#te-08--integration-test-structure--must)
9
+ - [te-09 - Test execution in CI](#te-09--test-execution-in-ci--must)
10
+ - [te-09a - Test feedback loop](#te-09a--test-feedback-loop--should)
11
+
12
+ ---
13
+
14
+ ### te-07 - Unit test structure - `must`
15
+
16
+ **Analyze:** Test files (`*.test.ts`, `*.spec.ts`, `*_test.go`, `test_*.py`), Jest/Vitest/pytest configs
17
+
18
+ **Commands:**
19
+ - `find . -name "*.test.*" -o -name "*.spec.*" | grep -v e2e | grep -v node_modules | wc -l` → count the unit tests
20
+ - `find . -name "*.test.*" -o -name "*.spec.*" | grep -v e2e | grep -v node_modules | head -20` → list the unit tests
21
+ - `ls vitest.config.* jest.config.* pytest.ini pyproject.toml .mocharc.* 2>/dev/null` → detect the test framework
22
+ - `grep -E "coverage|threshold|branches|functions|lines|statements" vitest.config.* jest.config.* package.json 2>/dev/null` → coverage thresholds
23
+ - `grep -E "coverageThreshold|coverageReporters|--coverage" package.json vitest.config.* jest.config.* 2>/dev/null` → coverage configuration
24
+ - `grep -ri "mutation\|stryker\|pitest" package.json 2>/dev/null` → mutation testing
25
+
26
+ **Check:**
27
+ - Naming convention and organization (co-located vs `__tests__` folder)
28
+ - Arrange-Act-Assert pattern respected
29
+ - Isolation (no inter-test dependency)
30
+ - Coverage configured with thresholds
31
+
32
+ **Levels:**
33
+ | Level | Criteria |
34
+ |-------|----------|
35
+ | 0 | No unit tests, or very few (<10% coverage). |
36
+ | 1 | Unit tests present but not maintained. Low coverage (<30%). |
37
+ | 2 | Established test framework. Coverage >50% on critical code. CI-integrated. |
38
+ | 3 | Coverage >80%. Fast tests (<5min). Occasional mutation testing. |
39
+ | 4 | TDD practiced. Coverage >90%. Mutation score >80%. Tests as documentation. |
40
+
41
+ ---
42
+
43
+ ### te-08 - Integration test structure - `must`
44
+
45
+ **Analyze:** Tests against a real database (Testcontainers, docker-compose test), API tests
46
+
47
+ **Commands:**
48
+ - `grep -ri "testcontainers\|docker-compose.*test\|supertest\|httptest" . 2>/dev/null | grep -v node_modules | head -5` → integration-test tools
49
+ - `find . -name "*integration*" -o -name "*integ*" 2>/dev/null | grep -v node_modules | head -10` → integration-test files
50
+ - `grep -ri "request(app)\|supertest\|httptest\|TestClient" . --include="*.test.*" --include="*.spec.*" 2>/dev/null | grep -v node_modules | head -5` → API tests
51
+ - `grep -E "test.*db\|test.*database\|:memory:" docker-compose*.yml vitest.config.* jest.config.* 2>/dev/null` → test DB
52
+ - `find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules | xargs grep -l "import.*prisma\|import.*typeorm\|import.*sequelize\|import.*mongoose" 2>/dev/null | head -5` → tests with an ORM (integration)
53
+
54
+ **Check:**
55
+ - Integration tests against a real DB (not only mocks)
56
+ - Testcontainers or docker-compose for the test environment
57
+ - Coverage of critical component interactions
58
+ - Test pyramid respected (unit > integ > e2e)
59
+
60
+ **Levels:**
61
+ | Level | Criteria |
62
+ |-------|----------|
63
+ | 0 | No dedicated integration tests. |
64
+ | 1 | A few manual integration tests. Shared environment. |
65
+ | 2 | Automated integration suite. Containers for dependencies. CI-integrated. |
66
+ | 3 | Complete integration tests with fixtures. Guaranteed isolation. Parallel execution. |
67
+ | 4 | Contract + integration tests combined. Service virtualization. Performance baselines. |
68
+
69
+ ---
70
+
71
+ ### te-09 - Test execution in CI - `must`
72
+
73
+ **Analyze:** CI pipeline, test stages, quality gates, uploaded coverage reports
74
+
75
+ **Commands:**
76
+ - `grep -E "test|vitest|jest|playwright|pytest|npm run test|yarn test" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → tests in CI
77
+ - `grep -E "coverage|codecov|coveralls|sonar" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → coverage reports in CI
78
+ - `grep -E "quality.gate\|fail\|threshold\|allow_failure" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → quality gates
79
+ - `grep -E "parallel|shard|split" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → test parallelization
80
+ - `grep -E "junit|test-results|test.report|allure" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → test reports
81
+
82
+ **Check:**
83
+ - Tests run automatically in CI (not only locally)
84
+ - Coverage report generated and visible
85
+ - Quality gate (PR blocked if tests fail or coverage drops)
86
+ - Reasonable execution time (< 15 min)
87
+
88
+ **Levels:**
89
+ | Level | Criteria |
90
+ |-------|----------|
91
+ | 0 | No CI, or CI without tests. |
92
+ | 1 | CI with unit tests. Non-blocking. Results sometimes ignored. |
93
+ | 2 | Blocking CI with unit + integration. Build time <15min. |
94
+ | 3 | Complete pipeline (lint, unit, integration, E2E). Quality gates. Detailed reporting. |
95
+ | 4 | Optimized CI/CD (<10min). Parallel testing. Flaky detection. Coverage trends. |
96
+
97
+ ---
98
+
99
+ ### te-09a - Test feedback loop - `should`
100
+
101
+ **Condition:** Applies if te-09 ≥ 2 (blocking CI in place).
102
+
103
+ **Analyze:** CI feedback time, notifications, reports, test dashboards, caching, incremental execution
104
+
105
+ **Commands:**
106
+ - `grep -E "coverage|report|codecov|coveralls|sonar" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → coverage reports
107
+ - `grep -E "slack|teams|notify|webhook|comment" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → notifications
108
+ - `grep -E "cache|Cache|CACHE" .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → caching in the pipeline
109
+ - `grep -E "nx\|turborepo\|bazel\|launchable" package.json .gitlab-ci.yml .github/workflows/*.yml 2>/dev/null` → incremental-execution tools
110
+ - `ls .codecov.yml codecov.yml sonar-project.properties 2>/dev/null` → configured reporting tools
111
+
112
+ **Check:**
113
+ - Fast feedback to developers (< 10 min ideal)
114
+ - Incremental or predictive test execution
115
+ - Effective caching (dependencies, build, test results)
116
+ - Readable test reports accessible on the PR
117
+
118
+ **Levels:**
119
+ | Level | Criteria |
120
+ |-------|----------|
121
+ | 0 | Feedback >30min. Developers do not wait. |
122
+ | 1 | Feedback 15-30min. Waiting but context switch. |
123
+ | 2 | Feedback <15min. Priority tests first. |
124
+ | 3 | Feedback <10min. Incremental testing. Fast feedback. |
125
+ | 4 | Feedback <5min for unit tests. Parallel execution. Predictive test selection. |
@@ -0,0 +1,67 @@
1
+ # `bug-ticket-root-cause`
2
+
3
+ > Turn an observed bug into a ticket that names the actual mechanism at `file:line` and pins down the tests that will prove it fixed - without fixing it now.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `bug` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | [`templates/bug-ticket.md`](templates/bug-ticket.md) |
11
+
12
+ ## What it is
13
+
14
+ `bug-ticket-root-cause` defines the **content** of a good bug ticket, independent of the tracker. It takes an observed defect and produces a ticket that cites the real root cause in the production code, lays out reproduction scenarios, and specifies the confirmation tests that must fail before a fix and pass after. It deliberately stops short of fixing anything.
15
+
16
+ It is a **content** skill: if your repo has a project-specific ticketing skill (e.g. `add-bug`, `jira-bug`), that one owns the **format and tracker** - this one owns what goes inside.
17
+
18
+ ## Why it exists
19
+
20
+ Most bug tickets fail in one of two ways:
21
+
22
+ 1. **No cited cause.** "Login is broken, probably the token refresh" is a design hypothesis dressed up as an analysis. The next person re-investigates from scratch or fixes by trial and error. A ticket must name the *mechanism* and cite `file:line`, or honestly mark the cause `to investigate`.
23
+ 2. **No confirmation tests.** Without a test that fails before the fix and passes after, nothing proves the bug is closed - and nothing stops it regressing. The confirmation-tests table is the heart of the ticket, not an afterthought.
24
+
25
+ The skill also enforces a hard boundary: it produces a ticket, *not* a fix. Mixing the fix into the investigation blurs the trace and defeats the purpose of documenting.
26
+
27
+ ## When it triggers
28
+
29
+ Invoke it when you are documenting an observed bug as a ticket without fixing it now:
30
+
31
+ - "report a bug" / "create a bug ticket" / "it doesn't work"
32
+ - a regression you want to record but not fix in this session
33
+
34
+ Route elsewhere when:
35
+
36
+ - the scope already had 2+ similar recent fixes → `recurring-bug-root-cause` (it's a class)
37
+ - the goal is to fix *now* → `superpowers:systematic-debugging`
38
+ - the source is a recorded QA session with many issues → `qa-session-intake`
39
+ - the bug isn't reproduced or root-caused yet and the fix/ticket decision is still open → `bug-triage-structured`
40
+
41
+ ## How it works
42
+
43
+ The skill moves from symptom to a written ticket without touching a fix: frame the observed-vs-expected symptom, investigate the real production code to name a *mechanism* at a cited `file:line`, then write the ticket (via `templates/bug-ticket.md`) with reproduction scenarios, a confirmation-tests table, and an argued priority. A recurrence check routes to `recurring-bug-root-cause` when the scope is already a repeat offender.
44
+
45
+ Full step-by-step protocol → [`SKILL.md`](SKILL.md).
46
+
47
+ ### Guardrails
48
+
49
+ - Never assert a root cause without citing code.
50
+ - Never create the ticket without the confirmation-tests section.
51
+ - Never fix the bug inside this workflow.
52
+
53
+ ## Worked example
54
+
55
+ > A user reports that saving a profile sometimes clears the avatar.
56
+
57
+ Framing: observed = avatar disappears on save; expected = avatar preserved; where = profile update endpoint; reproducibility = only when the form is submitted without re-selecting the avatar.
58
+
59
+ Investigation: tracing the update handler, the mechanism is that the serializer treats an absent `avatar_url` as an explicit `null` and overwrites the stored value. Cited `services/profile.ts:88`. `git blame` points to the commit that switched to a full-replace update. Hypothesis status: **confirmed**. Existing tests always sent an avatar, so they never exercised the absent-field path.
60
+
61
+ The ticket records that mechanism, three scenarios (submit without avatar → cleared; submit without avatar post-fix → preserved; submit with a new avatar → replaced), and a confirmation-tests table: a UT on the serializer asserting an absent field is not treated as `null` (❌ before / ✅ after), plus an API test on the endpoint. Priority: **high** (data loss, no workaround). No application file is touched.
62
+
63
+ ## Related artifacts
64
+
65
+ - [`bug-triage-structured`](../bug-triage-structured/) - when reproduction and the fix/ticket decision are still open.
66
+ - [`recurring-bug-root-cause`](../recurring-bug-root-cause/) - when the bug is the Nth of its class in the same scope.
67
+ - [`recording-decisions`](../recording-decisions/) - for design choices, not bugs.
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: bug-ticket-root-cause
3
+ description: Use when reporting or documenting an observed bug as a ticket (any tracker - GitLab, Jira, GitHub) - "report a bug", "signale un bug", "create a bug ticket", "crée un ticket de bug", "it doesn't work", "ça ne marche pas", a regression to document without fixing it now.
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: bug
8
+ ---
9
+
10
+ # Bug ticket with root cause
11
+
12
+ > If the current repo has a specific ticketing skill (e.g. acme-app → `add-bug`, beta-app → `jira-bug`), it wins - this skill defines the **content**, the project skill defines the **format/tracker**.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: documenting an observed bug as a ticket, without fixing it now
17
+ - **`recurring-bug-root-cause`** if: the scope has already had 2+ similar recent fixes → it is a class, not an isolated case
18
+ - **`superpowers:systematic-debugging`** if: the goal is to fix now, not to trace
19
+ - **`qa-session-intake`** if: the source is a recorded QA session (several problems to triage)
20
+
21
+ ## Principle
22
+
23
+ - A ticket with no cited root cause is an invitation to fix by trial and error
24
+ - A ticket with no confirmation tests is incomplete
25
+ - **This workflow produces a ticket, not a fix** - fix nothing, modify no application file
26
+
27
+ ## Tooling
28
+
29
+ - `templates/bug-ticket.md` - full ticket skeleton (context, root cause, scenarios, confirmation-tests table, priority)
30
+
31
+ ## Context to gather (before acting)
32
+
33
+ - Tracker + repo format/label conventions (project bug skill if one exists) - do not invent a format
34
+ - Project test commands (`package.json` / `Cargo.toml` / CI config) to fill the confirmation-tests table with real targets
35
+ - Access to production code? If not, mark the cause `to investigate` without disguising it
36
+ - Bug already open? search existing tickets before creating a duplicate
37
+
38
+ ## Workflow
39
+
40
+ ### 1. Frame the symptom
41
+ What (observed vs expected) · Where (page/endpoint/module) · Since when (commit, version) · Reproducibility. If too vague to locate the code: ask 2-3 questions and **stop**.
42
+
43
+ ### 2. Root-cause investigation (if code access)
44
+ - Read the real production code, trace the flow end to end (UI → state → call → handler → data)
45
+ - Git archaeology: `git log`/`git blame` on the suspect files → introducing commit
46
+ - Confront the facts where possible (an existing test that should have failed - why didn't it?, a query, a log)
47
+ - Deliverable: **mechanism** (≠ symptom) + **cited code `file:line`** + introducing commit + hypothesis status (`confirmed` / `strong` / `to validate`)
48
+ - Without code access: say so explicitly and mark the cause `to investigate` - do not disguise a design hypothesis as a root cause
49
+
50
+ ### 3. Ticket content
51
+ - **Context**: symptom, expected behavior, user impact
52
+ - **Root-cause analysis** (section above)
53
+ - **Reproduction scenarios**: (1) reproduce the bug - fails today, (2) nominal behavior post-fix, (3) related edge case
54
+ - **Required confirmation tests**: table Type (UT/E2E/API) · target file · key assertion · ❌ before fix / ✅ after. Each test MUST fail before the fix and pass after
55
+ - **Argued priority** (prod down/data loss → critical ; broken with no workaround → high ; workaround possible → medium ; cosmetic → low)
56
+
57
+ ### 4. Check for recurrence
58
+ If the scope has already had 2+ recent fixes → a "Recurrence" section in the ticket and apply `recurring-bug-root-cause`.
59
+
60
+ ## Traps & rationalizations
61
+
62
+ | Excuse | Reality |
63
+ |--------|---------|
64
+ | "The cause is obvious, no need to cite the code" | "Obvious" with no `file:line` = a design hypothesis. Cite it or mark it `to investigate`. |
65
+ | "I'll note the tests table later, the ticket is urgent" | A ticket with no confirmation tests is unclosable and goes back to trial and error. It is the heart of the ticket. |
66
+ | "While I'm here, I'll fix the bug" | This workflow produces a ticket, not a fix. The fix mixes in with the analysis and blurs the trace. |
67
+ | "Symptom = cause" | The symptom is what you see, the cause is the mechanism. Trace the flow to the point of divergence. |
68
+
69
+ ## Guardrails
70
+
71
+ - **Never** assert a root cause without citing code
72
+ - **Never** create the ticket without the confirmation-tests section
73
+ - **Never** fix the bug in this workflow
74
+
75
+ ## Exit condition
76
+
77
+ - [ ] Root cause = mechanism + cited `file:line` (or explicitly `to investigate` for lack of code access)
78
+ - [ ] Confirmation-tests table filled - each test fails before the fix, passes after
79
+ - [ ] 3 scenarios present (repro, nominal post-fix, related edge case)
80
+ - [ ] Argued priority
81
+ - [ ] No application file modified
82
+ - [ ] Recurrence checked (section added + `recurring-bug-root-cause` if 2+ recent fixes)
83
+
84
+ ## Changelog
85
+
86
+ - 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
@@ -0,0 +1,43 @@
1
+ # [Bug] <short title - symptom, not solution>
2
+
3
+ ## Context
4
+ **Observed**: <observed behavior>
5
+ **Expected**: <correct behavior>
6
+ **Where**: <page / endpoint / module>
7
+ **Since when**: <commit, version, date - or unknown>
8
+ **Reproducibility**: <systematic / intermittent / conditions>
9
+ **User impact**: <who, how often, workaround possible?>
10
+
11
+ ## Root-cause analysis
12
+ **Code access**: yes / no - if no, cause `to investigate`, do not disguise a design hypothesis as a root cause.
13
+
14
+ **Mechanism**: <what actually happens - NOT the symptom>
15
+ **Cited code**: `file:line` - <the faulty code or the missing guard>
16
+ **Introducing commit**: `hash` (<date>) - <context>
17
+ **Hypothesis status**: confirmed / strong / to validate / to investigate
18
+ **Why the existing tests didn't catch the bug**: <honest answer>
19
+
20
+ ## Reproduction scenarios
21
+
22
+ ### Scenario 1: reproduce the bug (fails today)
23
+ **Given** <state> **When** <action> **Then** <the bug>
24
+
25
+ ### Scenario 2: nominal behavior post-fix
26
+ **Given** <same state> **When** <same action> **Then** <expected behavior>
27
+
28
+ ### Scenario 3: related edge case
29
+ <back navigation, multi-tab, boundary data…>
30
+
31
+ ## Required confirmation tests
32
+ | Type | Target file | Key assertion | Before fix | After fix |
33
+ |---|---|---|---|---|
34
+ | UT | | | ❌ FAIL | ✅ PASS |
35
+ | E2E | | | ❌ FAIL | ✅ PASS |
36
+
37
+ > Each test MUST fail before the fix and pass after. A fix with no confirmation test is incomplete.
38
+
39
+ ## Priority
40
+ <critical: prod down, data loss, exploitable flaw · high: broken with no workaround · medium: workaround possible · low: cosmetic> - <justification>
41
+
42
+ ## Recurrence
43
+ <Section present only if the scope has 2+ recent fixes - see the recurring-bug-root-cause skill.>
@@ -0,0 +1,63 @@
1
+ # `bug-triage-structured`
2
+
3
+ > Reproduce a fresh bug, locate its cause at `file:line`, then decide fix-now-vs-ticket on facts - always leaving behind a test that goes red before and green after.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `bug` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | [`templates/bug-triage.md`](templates/bug-triage.md) |
11
+
12
+ ## What it is
13
+
14
+ `bug-triage-structured` is the **full front-to-back triage** of a bug whose reproduction and cause are still unknown. It runs the complete cycle - reproduce, root-cause, decide, confirm - and forces the "fix now vs open a ticket" call to be made on evidence rather than on how urgent the bug feels. Whichever branch it takes, the output includes a confirmation test that fails before and passes after.
15
+
16
+ ## Why it exists
17
+
18
+ The two most common triage failures are opposite mistakes:
19
+
20
+ 1. **Fixing before understanding.** "It's obvious, I'll just fix it" leads to a change on an unconfirmed cause - a trial-and-error patch that may not address the real mechanism and often spawns the next bug of the same class.
21
+ 2. **Deciding by vibe.** Choosing "fix now" or "ticket" on a sense of urgency, before the cause is located, means the decision isn't grounded in anything. The skill turns that into an explicit criteria table: a *confirmed*, localized, in-scope, low-risk cause may be fixed now; anything less becomes a ticket.
22
+
23
+ And in both branches it refuses to let the bug be called "handled" without a red-then-green confirmation test - the only thing that actually proves resolution.
24
+
25
+ ## When it triggers
26
+
27
+ Invoke it when a bug arrives raw and the path forward is undecided:
28
+
29
+ - "reproduce and analyze this bug" / "triage this bug"
30
+ - "should we fix now or open a ticket?"
31
+ - a fresh bug report where reproduction and root cause are still unknown
32
+
33
+ Route elsewhere when a phase is already settled:
34
+
35
+ - decision is already "document, don't fix now" → `bug-ticket-root-cause` (no repro/decision phase)
36
+ - the scope already had 2+ similar recent fixes → `recurring-bug-root-cause` (it's a class)
37
+ - repro and cause are established and you're fixing → `superpowers:systematic-debugging`
38
+
39
+ ## How it works
40
+
41
+ The skill runs the full triage cycle - reproduce, root-cause, decide, confirm - and forces the "fix now vs ticket" call to rest on evidence rather than urgency: a `confirmed`, localized, in-scope, low-risk cause may be fixed now, anything less becomes a ticket. Both branches must leave behind a confirmation test that goes red before and green after. `templates/bug-triage.md` captures all of this on one sheet and doubles as the tracker-agnostic ticket body when the decision is "ticket".
42
+
43
+ Full step-by-step protocol → [`SKILL.md`](SKILL.md).
44
+
45
+ ## Worked example
46
+
47
+ > "The dashboard total is sometimes wrong - reproduce and analyze."
48
+
49
+ **Reproduce**: it's wrong specifically when a filter is applied and then cleared quickly. Minimal repro: apply the "last 7 days" filter, clear it within a second → total shows the filtered figure. Deterministic once the timing is pinned.
50
+
51
+ **Root-cause**: tracing the flow, a stale async response from the filtered request resolves *after* the cleared request and overwrites the total. Cited `hooks/useTotals.ts:52` - no request-sequence guard. `git blame` points to the commit that added the filter feature. Status: **confirmed**. Existing tests never raced two requests, so they missed it.
52
+
53
+ **Decide**: cause confirmed, fix is a localized request-token guard, low risk, in scope → **fix now**.
54
+
55
+ **Confirmation test**: a UT that fires a stale-then-fresh response order and asserts the total reflects the latest request - red on current code, green after adding the guard. Both outputs pasted.
56
+
57
+ Had the cause come back merely `strong`, or the fix touched the whole data layer, the same sheet would have become a ticket with the table filled and no code written.
58
+
59
+ ## Related artifacts
60
+
61
+ - [`bug-ticket-root-cause`](../bug-ticket-root-cause/) - when the "document, don't fix" decision is already made.
62
+ - [`recurring-bug-root-cause`](../recurring-bug-root-cause/) - when the bug is the Nth of its class in the same scope.
63
+ - [`adversarial-feature-challenge`](../adversarial-feature-challenge/) - to surface bugs like this one before they reach a report.