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.
- package/AGENTS.md +90 -0
- package/LICENSE +21 -0
- package/README.md +281 -0
- package/agents/code-reviewer.md +33 -0
- package/agents/qa-tester.md +28 -0
- package/dist/hooks/README.md +182 -0
- package/dist/hooks/bash-npm-silent.mjs +81 -0
- package/dist/hooks/session-inject.mjs +53 -0
- package/dist/hooks/session-precompact.mjs +36 -0
- package/dist/hooks/session-writer.mjs +142 -0
- package/dist/hooks/skill-reminder.mjs +89 -0
- package/dist/hooks/truncate-bash-output.mjs +46 -0
- package/dist/hooks/truncate-output.mjs +88 -0
- package/dist/hooks/worktree-env-setup.mjs +123 -0
- package/dist/install.js +962 -0
- package/docs/adopting-a-repo.md +80 -0
- package/docs/architecture.md +76 -0
- package/docs/decisions.md +72 -0
- package/docs/developing.md +143 -0
- package/docs/evaluating-skills.md +41 -0
- package/docs/git-worktrees.md +62 -0
- package/docs/rules/clean-architecture-deps.md +66 -0
- package/docs/rules/commits.md +59 -0
- package/docs/rules/detection-gap-protocol.md +55 -0
- package/docs/rules/error-handling-discipline.md +62 -0
- package/docs/rules/minimal-code.md +58 -0
- package/docs/rules/no-raw-sql-interpolation.md +57 -0
- package/docs/rules/pre-commit-secret-detection.md +54 -0
- package/docs/rules/secure-logging.md +53 -0
- package/docs/rules/sql-migrations-discipline.md +58 -0
- package/docs/rules/subscription-cleanup.md +63 -0
- package/docs/rules/test-discipline.md +66 -0
- package/docs/rules/ui-states-complete.md +52 -0
- package/docs/templates/SKILL.template.md +66 -0
- package/docs/templates/rule.template.md +16 -0
- package/docs/writing-a-rule.md +43 -0
- package/docs/writing-a-skill.md +118 -0
- package/package.json +45 -0
- package/rules/clean-architecture-deps.md +20 -0
- package/rules/commits.md +16 -0
- package/rules/detection-gap-protocol.md +35 -0
- package/rules/error-handling-discipline.md +23 -0
- package/rules/minimal-code.md +32 -0
- package/rules/no-raw-sql-interpolation.md +20 -0
- package/rules/pre-commit-secret-detection.md +14 -0
- package/rules/secure-logging.md +16 -0
- package/rules/sql-migrations-discipline.md +18 -0
- package/rules/subscription-cleanup.md +22 -0
- package/rules/test-discipline.md +20 -0
- package/rules/ui-states-complete.md +23 -0
- package/scripts/subscription-leak-scan.ts +53 -0
- package/skills/adversarial-feature-challenge/README.md +65 -0
- package/skills/adversarial-feature-challenge/SKILL.md +96 -0
- package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
- package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
- package/skills/api-contract-versioning/README.md +62 -0
- package/skills/api-contract-versioning/SKILL.md +76 -0
- package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
- package/skills/audit-architecture/README.md +56 -0
- package/skills/audit-architecture/SKILL.md +97 -0
- package/skills/audit-architecture/reference/ar-architecture.md +275 -0
- package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
- package/skills/audit-architecture/reference/im-incidents.md +217 -0
- package/skills/audit-architecture/reference/pa-pannes.md +362 -0
- package/skills/audit-architecture/reference/re-recuperation.md +300 -0
- package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
- package/skills/audit-architecture/reference/su-support.md +180 -0
- package/skills/audit-ci-cd/README.md +54 -0
- package/skills/audit-ci-cd/SKILL.md +124 -0
- package/skills/audit-ci-cd/reference/artefacts.md +39 -0
- package/skills/audit-ci-cd/reference/deploiement.md +100 -0
- package/skills/audit-ci-cd/reference/dora.md +94 -0
- package/skills/audit-ci-cd/reference/iac.md +40 -0
- package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
- package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
- package/skills/audit-compliance/README.md +69 -0
- package/skills/audit-compliance/SKILL.md +176 -0
- package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
- package/skills/audit-compliance/reference/finops.md +318 -0
- package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
- package/skills/audit-industrialisation/README.md +53 -0
- package/skills/audit-industrialisation/SKILL.md +251 -0
- package/skills/audit-observability/README.md +64 -0
- package/skills/audit-observability/SKILL.md +134 -0
- package/skills/audit-observability/reference/alerting.md +214 -0
- package/skills/audit-observability/reference/logging.md +114 -0
- package/skills/audit-observability/reference/metriques.md +166 -0
- package/skills/audit-observability/reference/traces-dashboards.md +90 -0
- package/skills/audit-performance-frontend/README.md +91 -0
- package/skills/audit-performance-frontend/SKILL.md +194 -0
- package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
- package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
- package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
- package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
- package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
- package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
- package/skills/audit-quality/README.md +85 -0
- package/skills/audit-quality/SKILL.md +126 -0
- package/skills/audit-quality/reference/qa-devops.md +539 -0
- package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
- package/skills/audit-report/README.md +72 -0
- package/skills/audit-report/SKILL.md +241 -0
- package/skills/audit-report/reference/scoring-model.md +45 -0
- package/skills/audit-security/README.md +72 -0
- package/skills/audit-security/SKILL.md +140 -0
- package/skills/audit-security/reference/auth-identite.md +98 -0
- package/skills/audit-security/reference/autorisation.md +66 -0
- package/skills/audit-security/reference/chiffrement-tls.md +97 -0
- package/skills/audit-security/reference/detection-patching.md +67 -0
- package/skills/audit-security/reference/incident-response.md +98 -0
- package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
- package/skills/audit-security/reference/secrets.md +36 -0
- package/skills/audit-testing/README.md +82 -0
- package/skills/audit-testing/SKILL.md +131 -0
- package/skills/audit-testing/reference/golden-dataset.md +65 -0
- package/skills/audit-testing/reference/resilience-chaos.md +93 -0
- package/skills/audit-testing/reference/tests-contractuels.md +65 -0
- package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
- package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
- package/skills/bug-ticket-root-cause/README.md +67 -0
- package/skills/bug-ticket-root-cause/SKILL.md +86 -0
- package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
- package/skills/bug-triage-structured/README.md +63 -0
- package/skills/bug-triage-structured/SKILL.md +104 -0
- package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
- package/skills/ci-pipeline-orchestration/README.md +55 -0
- package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
- package/skills/commit-readiness-review/README.md +66 -0
- package/skills/commit-readiness-review/SKILL.md +82 -0
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
- package/skills/comprehensive-test-strategy/README.md +64 -0
- package/skills/comprehensive-test-strategy/SKILL.md +108 -0
- package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
- package/skills/daily-workflow-optimization/README.md +56 -0
- package/skills/daily-workflow-optimization/SKILL.md +80 -0
- package/skills/database-schema-evolution/README.md +54 -0
- package/skills/database-schema-evolution/SKILL.md +107 -0
- package/skills/ddd-backend-implementation/README.md +63 -0
- package/skills/ddd-backend-implementation/SKILL.md +95 -0
- package/skills/design-system-component-lifecycle/README.md +56 -0
- package/skills/design-system-component-lifecycle/SKILL.md +97 -0
- package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
- package/skills/detection-sweep/README.md +58 -0
- package/skills/detection-sweep/SKILL.md +93 -0
- package/skills/detection-sweep/scripts/sweep.ts +80 -0
- package/skills/domain-modeling-design/README.md +57 -0
- package/skills/domain-modeling-design/SKILL.md +83 -0
- package/skills/frontend-fullstack-implementation/README.md +60 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
- package/skills/frontend-spec-call-site-audit/README.md +66 -0
- package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
- package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
- package/skills/merge-request-review/README.md +60 -0
- package/skills/merge-request-review/SKILL.md +77 -0
- package/skills/merge-request-review/templates/mr-review-report.md +29 -0
- package/skills/production-incident-diagnostic/README.md +63 -0
- package/skills/production-incident-diagnostic/SKILL.md +103 -0
- package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
- package/skills/qa-session-intake/README.md +56 -0
- package/skills/qa-session-intake/SKILL.md +78 -0
- package/skills/recording-decisions/README.md +91 -0
- package/skills/recording-decisions/SKILL.md +84 -0
- package/skills/recurring-bug-root-cause/README.md +64 -0
- package/skills/recurring-bug-root-cause/SKILL.md +93 -0
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
- package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
- package/skills/refactoring-shared-component-api/README.md +50 -0
- package/skills/refactoring-shared-component-api/SKILL.md +84 -0
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
- package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
- package/skills/validating-features-end-to-end/README.md +50 -0
- package/skills/validating-features-end-to-end/SKILL.md +90 -0
- package/skills/visual-regression-check/README.md +51 -0
- package/skills/visual-regression-check/SKILL.md +89 -0
- package/skills/writing-robust-tests/README.md +53 -0
- package/skills/writing-robust-tests/SKILL.md +88 -0
- package/templates/.adopted.example +8 -0
- 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.
|