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,64 @@
|
|
|
1
|
+
# `recurring-bug-root-cause`
|
|
2
|
+
|
|
3
|
+
> When the same area gets patched again and again, stop treating symptoms: name the bug class and kill it with a blocking, tooled guardrail - not a reminder.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `bug` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | [`scripts/detect-recurring-fixes.ts`](scripts/detect-recurring-fixes.ts), [`templates/postmortem-recidive.md`](templates/postmortem-recidive.md) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`recurring-bug-root-cause` is the escalation you apply when a scope has already taken several similar one-line fixes and is about to take another. It shifts the work from "patch the Nth symptom" to "identify the shared cause and install a mechanism that makes the whole class impossible."
|
|
15
|
+
|
|
16
|
+
## Why it exists
|
|
17
|
+
|
|
18
|
+
3+ fixes on the same scope in about two weeks is a signal: you are debugging by trial and error, patching surface symptoms of one underlying cause. Two things then go wrong under pressure:
|
|
19
|
+
|
|
20
|
+
1. **The reminder illusion** - adding a note to `CLAUDE.md` or a lint comment feels like a fix, but a documentation rule does not sweep the existing code and does not survive the next moment of inattention. The class stays alive.
|
|
21
|
+
2. **The deferred trace** - you ship the urgent one-liner and promise to open the root-cause ticket "later". Later never comes.
|
|
22
|
+
|
|
23
|
+
The skill answers both: the guardrail must be **tooled and blocking**, and the **session does not end until the spike leaves a real trace** (ticket or postmortem), even if the urgent fix shipped first.
|
|
24
|
+
|
|
25
|
+
## When it triggers
|
|
26
|
+
|
|
27
|
+
- 2+ similar recent fixes on the same scope
|
|
28
|
+
- a 2nd bug of the same class appears elsewhere
|
|
29
|
+
- "this bug again" / repeated fix commits on the same area
|
|
30
|
+
- **before** writing the Nth one-line fix
|
|
31
|
+
|
|
32
|
+
Use `bug-ticket-root-cause` instead for a first, isolated bug (not yet a class), and `superpowers:systematic-debugging` for a single bug with no repetition pattern.
|
|
33
|
+
|
|
34
|
+
## How it works
|
|
35
|
+
|
|
36
|
+
### Detect the recurrence
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx tsx scripts/detect-recurring-fixes.ts [--window 14] [--threshold 3] [repoDir]
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
It scans the git log for `fix(scope):` conventional commits, flags any scope at the threshold, and **exits 1** on recurrence - so it doubles as a CI check. 5+ fixes on a scope escalates to "root-cause required before any new fix".
|
|
43
|
+
|
|
44
|
+
### The approach
|
|
45
|
+
|
|
46
|
+
Once recurrence is detected, the skill maps the shared class rather than the Nth symptom, spikes 2–4 candidate causes until at least one is refuted with evidence, then installs a *tooled, blocking, deterministic* guardrail that sweeps the existing code (so each error it raises is a latent bug or an annotated exception). It closes with class regression tests and a postmortem that leaves a real ticket for every action not shipped inside the fix.
|
|
47
|
+
|
|
48
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
49
|
+
|
|
50
|
+
## Worked example
|
|
51
|
+
|
|
52
|
+
> On acme-app, `fix(export)` has landed four times in ten days: empty CSV, wrong delimiter, missing header, broken encoding.
|
|
53
|
+
|
|
54
|
+
1. `detect-recurring-fixes.ts` flags `export` at 4 → 🔴.
|
|
55
|
+
2. Mapping the class: every fix is an ad-hoc string built without going through the shared serializer.
|
|
56
|
+
3. Spike refutes "isolated slip" (four independent authors) and confirms "no guardrail forbids hand-rolled CSV".
|
|
57
|
+
4. Guardrail: a lint rule banning manual CSV assembly outside the serializer, run across the repo - it raises 3 more latent call sites, each ticketed.
|
|
58
|
+
5. One regression test per past bug + one asserting all export paths use the serializer. Postmortem filed with the 3 follow-up tickets.
|
|
59
|
+
|
|
60
|
+
## Related artifacts
|
|
61
|
+
|
|
62
|
+
- [`bug-ticket-root-cause`](../bug-ticket-root-cause/) - first, isolated bug (not yet a class).
|
|
63
|
+
- [`writing-robust-tests`](../writing-robust-tests/) - to build the class regression tests.
|
|
64
|
+
- [`qa-session-intake`](../qa-session-intake/) - when a QA session surfaces the recurrence.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: recurring-bug-root-cause
|
|
3
|
+
description: Use when fixing a bug in a scope that already received 2+ similar fixes recently, when a second bug of the same class appears elsewhere, or when noticing "this bug again" / "encore ce bug" / repeated fix commits on the same area. Use BEFORE writing the Nth one-line fix.
|
|
4
|
+
version: 1.0.1
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-07-20
|
|
7
|
+
category: bug
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Root-causing a recurring bug
|
|
11
|
+
|
|
12
|
+
> If the current repo has a dedicated anti-recurrence skill or process (e.g. acme-app → `recidive-root-cause` + `retro-fixes.ts`), it wins.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: 2+ similar recent fixes on the same scope, or a 2nd bug of the same class elsewhere, or "this bug again"
|
|
17
|
+
- **`bug-ticket-root-cause`** if: first observed bug, an isolated case to document (not yet a class)
|
|
18
|
+
- **`superpowers:systematic-debugging`** if: a single bug to diagnose, with no repetition pattern
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
3+ fixes on the same scope in ~2 weeks = trial-and-error debugging: you are patching **symptoms** of one shared cause. **A bug class is hunted with tooling, not with a reminder** - a documentation rule does not protect the existing code and does not survive inattention.
|
|
23
|
+
|
|
24
|
+
## The trap (observed in baseline)
|
|
25
|
+
|
|
26
|
+
Under pressure, the reflex is: ship the one-line fix, promise yourself "I'll create the root-cause ticket later"… and never do it. **The urgent fix may ship first, but the session does not end until the spike leaves a trace** (ticket created, or spike done immediately). "I'll keep it in mind" does not count.
|
|
27
|
+
|
|
28
|
+
## Tooling
|
|
29
|
+
|
|
30
|
+
- Test procedure: `scripts/detect-recurring-fixes.test.ts` - deterministic behavioral test of the script (positive + negative fixture). Run `npx tsx scripts/detect-recurring-fixes.test.ts` from the canonical repo after any change to the script (also picked up by `npm test`). Not distributed to target repos.
|
|
31
|
+
|
|
32
|
+
- `scripts/detect-recurring-fixes.ts [--window 14] [--threshold 3] [repoDir]` - detects scopes at the threshold from the git log (conventional commits); exit 1 on recurrence → usable as a CI check
|
|
33
|
+
- `templates/postmortem-recidive.md` - short postmortem template with a hypothesis table
|
|
34
|
+
|
|
35
|
+
## Context to gather (before acting)
|
|
36
|
+
|
|
37
|
+
- The list of the N fixes on the scope: `scripts/detect-recurring-fixes.ts` then `git log`/`git blame` on the files involved
|
|
38
|
+
- Guard tooling already in place (custom lint, hooks, CI checks) and why it did not catch the class
|
|
39
|
+
- The project's lint/test/build commands (`package.json` / `Cargo.toml` / CI config) - that is where the blocking guardrail lives
|
|
40
|
+
- The repo tracker for one ticket per action not shipped within the fix
|
|
41
|
+
|
|
42
|
+
## Steps
|
|
43
|
+
|
|
44
|
+
### 1. Map the class, not the symptom
|
|
45
|
+
- Detection: `scripts/detect-recurring-fixes.ts`, then list the N fixes on the scope
|
|
46
|
+
- Key question: **what common property links these fixes?** (same implicit contract violated, same missing guardrail, same environment divergence)
|
|
47
|
+
|
|
48
|
+
### 2. Spike hypotheses - each confirmed or refuted
|
|
49
|
+
- 2–4 root-cause hypotheses, each tested against the facts with evidence
|
|
50
|
+
- Always include: "existing tooling should have caught it - why didn't it?" and "this is an isolated slip of attention" (usually refuted by the 2nd occurrence)
|
|
51
|
+
- A postmortem with no refuted hypothesis = narrative, not a spike
|
|
52
|
+
|
|
53
|
+
### 3. TOOLED guardrail (not documentation)
|
|
54
|
+
- Choose the most mechanical **blocking** mechanism: compiler option, custom lint rule, integration test on the class, pre-commit hook, CI check
|
|
55
|
+
- The guardrail must **sweep the existing code** (each error raised = a latent bug or an annotated exception) - a rule that only applies to future code leaves the bombs in place
|
|
56
|
+
- Never a non-deterministic guardrail (worse than nothing)
|
|
57
|
+
|
|
58
|
+
### 4. Class regression tests
|
|
59
|
+
- One test per fixed occurrence **and** a test/check covering the whole class
|
|
60
|
+
|
|
61
|
+
### 5. Trace
|
|
62
|
+
- Short postmortem (timeline, root cause, tested hypotheses, actions) with a real ticket per action not shipped within the fix
|
|
63
|
+
|
|
64
|
+
## Traps & rationalizations
|
|
65
|
+
|
|
66
|
+
| Excuse | Reality |
|
|
67
|
+
|--------|---------|
|
|
68
|
+
| "I ship the fix and create the root-cause ticket later" | "Later" never comes. The session does not end without the spike's trace (ticket created or spike done). |
|
|
69
|
+
| "It's just an isolated slip" | A hypothesis to refute, not to assume - usually false by the 2nd occurrence. |
|
|
70
|
+
| "I'll add a note/rule to CLAUDE.md, that's enough" | A documentation rule does not sweep the existing code and does not survive inattention. Blocking guardrail or nothing. |
|
|
71
|
+
| "The guardrail only applies to new code" | The bombs stay in place. It must sweep the existing code: each error raised = a latent bug or an annotated exception. |
|
|
72
|
+
| "I'll keep it in mind" | Memory ≠ trace. Postmortem or a real ticket. |
|
|
73
|
+
|
|
74
|
+
## Guardrails
|
|
75
|
+
|
|
76
|
+
- **Never** fix the Nth symptom and declare the recurrence handled
|
|
77
|
+
- **Never** end the session without a trace of the spike (ticket or postmortem)
|
|
78
|
+
- **Never** mix the urgent fix and the root-cause refactor in the same commit
|
|
79
|
+
|
|
80
|
+
## Exit condition
|
|
81
|
+
|
|
82
|
+
- [ ] Class named (property common to the N fixes), not just the Nth symptom
|
|
83
|
+
- [ ] 2–4 hypotheses spiked, at least one refuted with evidence
|
|
84
|
+
- [ ] "Existing tooling should have caught it - why didn't it?" answered
|
|
85
|
+
- [ ] **Blocking, deterministic** guardrail added, sweeping the existing code (check output pasted)
|
|
86
|
+
- [ ] One test per fixed occurrence + a test/check covering the class
|
|
87
|
+
- [ ] Trace delivered: postmortem + a real ticket per deferred action
|
|
88
|
+
|
|
89
|
+
## Changelog
|
|
90
|
+
|
|
91
|
+
- 1.0.1 (2026-07-20) - co-located test procedure for detect-recurring-fixes.ts (scripts/detect-recurring-fixes.test.ts)
|
|
92
|
+
|
|
93
|
+
- 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
#!/usr/bin/env npx tsx
|
|
2
|
+
/**
|
|
3
|
+
* Detects recurring scopes: N+ `fix(scope):` commits within a sliding window.
|
|
4
|
+
* Generic version (any git repo, conventional commits) of acme-app's retro-fixes.ts.
|
|
5
|
+
* Usage: npx tsx detect-recurring-fixes.ts [--window 14] [--threshold 3] [repoDir]
|
|
6
|
+
* Exit: 0 if no scope reaches the threshold, 1 otherwise (usable as a CI check).
|
|
7
|
+
*/
|
|
8
|
+
import { execSync } from 'node:child_process'
|
|
9
|
+
|
|
10
|
+
const args = process.argv.slice(2)
|
|
11
|
+
function opt(flag: string, def: number): number {
|
|
12
|
+
const i = args.indexOf(flag)
|
|
13
|
+
return i >= 0 ? Number(args[i + 1]) : def
|
|
14
|
+
}
|
|
15
|
+
const windowDays = opt('--window', 14)
|
|
16
|
+
const threshold = opt('--threshold', 3)
|
|
17
|
+
const repo = args.filter((a) => !a.startsWith('--') && !/^\d+$/.test(a)).pop() ?? process.cwd()
|
|
18
|
+
|
|
19
|
+
const log = execSync(`git -C "${repo}" log --since="${windowDays} days ago" --no-merges --pretty=%h%ad%s --date=short`, {
|
|
20
|
+
encoding: 'utf-8',
|
|
21
|
+
})
|
|
22
|
+
|
|
23
|
+
const byScope = new Map<string, Array<{ hash: string; date: string; subject: string }>>()
|
|
24
|
+
for (const line of log.split('\n').filter(Boolean)) {
|
|
25
|
+
const [hash, date, subject] = line.split('')
|
|
26
|
+
const m = subject.match(/^fix\(([^)]+)\)/) ?? (subject.startsWith('fix:') ? [null, '(no-scope)'] : null)
|
|
27
|
+
if (!m) continue
|
|
28
|
+
const scope = m[1]
|
|
29
|
+
byScope.set(scope, [...(byScope.get(scope) ?? []), { hash, date, subject }])
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const offenders = [...byScope].filter(([, fixes]) => fixes.length >= threshold).sort((a, b) => b[1].length - a[1].length)
|
|
33
|
+
|
|
34
|
+
console.log(`# fix(scope) recurrences - ${windowDays}d window, threshold ${threshold}\n`)
|
|
35
|
+
if (!offenders.length) {
|
|
36
|
+
console.log('No scope at the threshold. ✅')
|
|
37
|
+
process.exit(0)
|
|
38
|
+
}
|
|
39
|
+
for (const [scope, fixes] of offenders) {
|
|
40
|
+
const level = fixes.length >= 5 ? '🔴 root-cause REQUIRED before any new fix' : '🟡 postmortem recommended'
|
|
41
|
+
console.log(`## ${scope} - ${fixes.length} fixes ${level}`)
|
|
42
|
+
for (const f of fixes) console.log(`- ${f.date} ${f.hash} ${f.subject}`)
|
|
43
|
+
console.log()
|
|
44
|
+
}
|
|
45
|
+
console.log('→ Apply the recurring-bug-root-cause skill: map the class, spike hypotheses, tooled guardrail, class tests.')
|
|
46
|
+
process.exit(1)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Recurrence <scope> - <YYYY-MM-DD>
|
|
2
|
+
|
|
3
|
+
## Timeline
|
|
4
|
+
| Date | Commit | Symptom fixed |
|
|
5
|
+
|---|---|---|
|
|
6
|
+
| | | |
|
|
7
|
+
|
|
8
|
+
## Bug class
|
|
9
|
+
<One sentence describing the common property of the N fixes - the implicit contract violated, the missing guardrail, the environment divergence. Not the symptoms.>
|
|
10
|
+
|
|
11
|
+
## Tested hypotheses
|
|
12
|
+
| Hypothesis | Test performed | Status | Evidence |
|
|
13
|
+
|---|---|---|---|
|
|
14
|
+
| <candidate cause> | | confirmed / refuted | |
|
|
15
|
+
| Existing tooling should have caught it | why didn't it? | | |
|
|
16
|
+
| Isolated slip of attention | ≥ 2 independent occurrences? | usually refuted | |
|
|
17
|
+
|
|
18
|
+
> A postmortem with no **refuted** hypothesis = narrative, not a spike.
|
|
19
|
+
|
|
20
|
+
## Root cause
|
|
21
|
+
<The confirmed mechanism, numbered factors if several.>
|
|
22
|
+
|
|
23
|
+
## Tooled guardrail
|
|
24
|
+
- Blocking mechanism: <custom lint / compiler option / class test / hook / CI check>
|
|
25
|
+
- Sweep of existing code: <N errors raised → tickets or annotated exceptions>
|
|
26
|
+
|
|
27
|
+
## Regression tests
|
|
28
|
+
| Test | Covers | Was failing on the N bugs before the fix? |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| | occurrence #1 / whole class | |
|
|
31
|
+
|
|
32
|
+
## Follow-up actions
|
|
33
|
+
| Action | Ticket | Due |
|
|
34
|
+
|---|---|---|
|
|
35
|
+
| | <real iid, never "to create"> | |
|
|
36
|
+
|
|
37
|
+
## What we learned
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# `refactoring-shared-component-api`
|
|
2
|
+
|
|
3
|
+
> Changing a shared component's public API isn't done when the typecheck passes - it's done when every grepped call site is migrated or justified.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `frontend` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | [`scripts/sweep-call-sites.ts`](scripts/sweep-call-sites.ts), [`templates/migration-checklist.md`](templates/migration-checklist.md) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`refactoring-shared-component-api` is a checklist for one dangerous operation: changing the public contract (props, emits, slots, events, exported signature) of a component or module consumed in two or more places. It replaces "the compiler is happy" with a concrete, greppable definition of done.
|
|
15
|
+
|
|
16
|
+
## Why it exists
|
|
17
|
+
|
|
18
|
+
The whole trap is that the compiler lies here. Vue fallthrough attrs, dynamic JS, and untyped templates silently accept an unknown prop or argument - no compile error, no typecheck error, no runtime error. So a rename can "pass" everywhere while half the call sites are quietly broken, only surfacing when a human exercises the feature.
|
|
19
|
+
|
|
20
|
+
The most-forgotten consumer is the **compatibility wrapper** - the thin layer whose only job is to carry the old interface. It looks like plumbing, not a call site, so it gets skipped; and skipping it defeats the entire migration. The skill treats wrappers as first-class call sites and makes the call-site sweep - not the typecheck - authoritative.
|
|
21
|
+
|
|
22
|
+
## When it triggers
|
|
23
|
+
|
|
24
|
+
- renaming a prop, removing a parameter, changing a contract on a component/module used in 2+ places
|
|
25
|
+
- any change to props/emits/slots/events/exported signatures of shared UI or modules
|
|
26
|
+
- when a typecheck passes but the change touches a shared contract
|
|
27
|
+
|
|
28
|
+
Use `frontend-spec-call-site-audit` instead when specifying a *new* feature rather than changing an existing contract, and pair with `writing-robust-tests` for the integration-point tests.
|
|
29
|
+
|
|
30
|
+
## How it works
|
|
31
|
+
|
|
32
|
+
The approach is a mandatory-order checklist that makes the call-site sweep - not the typecheck - the authority. You run [`scripts/sweep-call-sites.ts`](scripts/sweep-call-sites.ts) first (zero-dependency; finds every casing, dynamic usage, object spread, and stories/mocks, and flags suspicious wrappers as first-class call sites), migrate each site until the old name greps to zero among consumers, then verify with a silent-contract check, wrapper/adapter mount tests, and a validation run. Paste the [migration checklist](templates/migration-checklist.md) into the MR with each call site's status.
|
|
33
|
+
|
|
34
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
35
|
+
|
|
36
|
+
## Worked example
|
|
37
|
+
|
|
38
|
+
> On acme-app you rename `<StatusBadge variant>` to `tone`.
|
|
39
|
+
|
|
40
|
+
1. `sweep-call-sites.ts StatusBadge` lists 9 call sites and flags `LegacyStatusBadge.vue` as a suspicious wrapper.
|
|
41
|
+
2. You migrate all 9; `grep -r 'variant' ` on consumers returns 0.
|
|
42
|
+
3. The wrapper passed `variant` through untyped - no typecheck error would have caught it. You update it and add its mount test.
|
|
43
|
+
4. An existing test asserted a `.badge--ok` CSS class (still green with the old prop) - you rewrite it to assert the `tone` prop drives the render.
|
|
44
|
+
5. MR ships with the checklist: 8 migrated, 1 wrapper migrated + tested, 0 old-name occurrences.
|
|
45
|
+
|
|
46
|
+
## Related artifacts
|
|
47
|
+
|
|
48
|
+
- [`writing-robust-tests`](../writing-robust-tests/) - for the wrapper/adapter mount tests.
|
|
49
|
+
- [`visual-regression-check`](../visual-regression-check/) - to confirm the migrated component still renders correctly.
|
|
50
|
+
- [`validating-features-end-to-end`](../validating-features-end-to-end/) - when the contract change is part of a feature to validate.
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: refactoring-shared-component-api
|
|
3
|
+
description: Use when changing the public API (props, emits, slots, events, exported signatures) of a UI component or module consumed in 2+ places - renaming a prop, removing a parameter, changing a contract - "change this shared component's API", "change l'API de ce composant partagé", "rename this prop", "renomme cette prop". Also use when a typecheck passes but the change touches a shared contract.
|
|
4
|
+
version: 1.0.1
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-07-20
|
|
7
|
+
category: frontend
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Refactoring a shared component's API
|
|
11
|
+
|
|
12
|
+
> If the current repo has a dedicated skill or conventions for this case (e.g. acme-app → `shared-component-refactor`), they win.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: changing the public API (props/emits/slots/events/exported signature) of a component or module consumed in 2+ places
|
|
17
|
+
- **frontend-spec-call-site-audit** instead if: specifying a new feature, not changing an existing contract
|
|
18
|
+
- **writing-robust-tests** alongside: to write the integration-point tests in step 4
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
A shared-API refactor is **not done when the typecheck passes**: it is done when **every grepped call site** is migrated or justified. Many frameworks (Vue fallthrough attrs, dynamic JS, untyped templates) silently accept an unknown prop/argument - no compile, typecheck, or runtime signal.
|
|
23
|
+
|
|
24
|
+
## Context to gather (before acting)
|
|
25
|
+
|
|
26
|
+
- Does the compiler check templates strictly (`strictTemplates`, typed JSX)? If not, the silent-contract check in step 3 is **manual and mandatory**
|
|
27
|
+
- Typecheck + test commands: read `package.json` / `Cargo.toml` / CI
|
|
28
|
+
- Locate existing compatibility wrappers around the component - these are the most often forgotten consumers
|
|
29
|
+
|
|
30
|
+
## Checklist (mandatory order, no step is optional)
|
|
31
|
+
|
|
32
|
+
### 1. Exhaustive sweep BEFORE touching the component - `scripts/sweep-call-sites.ts`
|
|
33
|
+
- Grep every call site - all casings (`<MyBadge`, `<my-badge`), dynamic usages (`:is=`, factories), object spreads (`v-bind="obj"`, `{...props}`)
|
|
34
|
+
- **Compatibility wrappers are first-class call sites** - the wrapper whose only job is to preserve the old interface is the most often forgotten consumer
|
|
35
|
+
- Include: stories/fixtures/mocks, docstrings that reference the old API
|
|
36
|
+
- List every call site; that is the migration checklist
|
|
37
|
+
|
|
38
|
+
### 2. Migration
|
|
39
|
+
- Migrate each listed call site, ticking them off as you go
|
|
40
|
+
- For each removed or renamed prop/parameter: grepping the old name must return **0 occurrences** among consumers
|
|
41
|
+
|
|
42
|
+
### 3. Silent-contract check
|
|
43
|
+
- For each migrated call site: open the consumed component and verify that **every prop/argument passed is declared** in its interface
|
|
44
|
+
- If the compiler checks templates strictly (e.g. `strictTemplates`), the typecheck is enough; otherwise this check is **manual and mandatory**
|
|
45
|
+
|
|
46
|
+
### 4. Integration-point tests
|
|
47
|
+
- Every wrapper/adapter touched gets its **own mount test** (the event bubbles up, the prop drives the render) - these bugs are invisible until a human exercises the feature
|
|
48
|
+
|
|
49
|
+
### 5. Validation
|
|
50
|
+
- Unit tests + typecheck; verify the existing tests actually exercise the prop name (a test on a CSS class passes even if the rename is incomplete)
|
|
51
|
+
|
|
52
|
+
## Templates
|
|
53
|
+
|
|
54
|
+
- `templates/migration-checklist.md` - migration checklist to paste into the MR (call sites + status)
|
|
55
|
+
|
|
56
|
+
## Traps & rationalizations
|
|
57
|
+
|
|
58
|
+
| Excuse | Reality |
|
|
59
|
+
|--------|---------|
|
|
60
|
+
| "The typecheck passes, it's done" | Fallthrough attrs, dynamic JS, and untyped templates accept an unknown prop without complaint. The call-site sweep is authoritative. |
|
|
61
|
+
| "The compat wrapper isn't really a call site" | It's the most often forgotten consumer, and its only job is to carry the old interface. Sweep mandatory. |
|
|
62
|
+
| "A global sed on `variant` will be faster" | A generic name touches unrelated components. Migrate file by file. |
|
|
63
|
+
| "The existing tests pass" | A test on a CSS class passes even if the rename is incomplete. Verify they exercise the prop name. |
|
|
64
|
+
|
|
65
|
+
## Exit condition
|
|
66
|
+
|
|
67
|
+
- [ ] Exhaustive sweep run (`scripts/sweep-call-sites.ts`), all call sites listed
|
|
68
|
+
- [ ] Each call site migrated or justified (not affected); grep of the old name = **0 occurrences** among consumers
|
|
69
|
+
- [ ] Silent-contract check done (every prop passed is declared in the component's interface)
|
|
70
|
+
- [ ] Mount test on each wrapper/adapter touched
|
|
71
|
+
- [ ] Tests + typecheck run, output pasted - never "it should pass"
|
|
72
|
+
- [ ] Deliverable: list of call sites + status (migrated / removed / not affected, justified)
|
|
73
|
+
|
|
74
|
+
## Tooling
|
|
75
|
+
|
|
76
|
+
- Test procedure: `scripts/sweep-call-sites.test.ts` - deterministic behavioral test of the script (positive + negative fixture). Run `npx tsx scripts/sweep-call-sites.test.ts` from the canonical repo after any change to the script (also picked up by `npm test`). Not distributed to target repos.
|
|
77
|
+
|
|
78
|
+
- `scripts/sweep-call-sites.ts <ComponentName> [rootDir]` - automatic sweep (casings, dynamic usages, spreads, **suspicious wrappers highlighted**, stories/mocks), output = markdown checklist
|
|
79
|
+
|
|
80
|
+
## Changelog
|
|
81
|
+
|
|
82
|
+
- 1.0.1 (2026-07-20) - co-located test procedure for sweep-call-sites.ts (scripts/sweep-call-sites.test.ts)
|
|
83
|
+
|
|
84
|
+
- 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
#!/usr/bin/env npx tsx
|
|
2
|
+
/**
|
|
3
|
+
* Exhaustive sweep of a shared component's call sites.
|
|
4
|
+
* Usage: npx tsx sweep-call-sites.ts <ComponentName> [rootDir]
|
|
5
|
+
* Output: markdown checklist of call sites (PascalCase, kebab-case,
|
|
6
|
+
* dynamic usages, spreads, suspicious wrappers, stories/fixtures/mocks).
|
|
7
|
+
* Zero dependency - node builtins only.
|
|
8
|
+
*/
|
|
9
|
+
import * as fs from 'node:fs'
|
|
10
|
+
import * as path from 'node:path'
|
|
11
|
+
|
|
12
|
+
const [name, root = process.cwd()] = process.argv.slice(2)
|
|
13
|
+
if (!name) {
|
|
14
|
+
console.error('Usage: sweep-call-sites.ts <ComponentName> [rootDir]')
|
|
15
|
+
process.exit(2)
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
const kebab = name
|
|
19
|
+
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
|
|
20
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
|
|
21
|
+
.toLowerCase()
|
|
22
|
+
const EXT = new Set(['.vue', '.ts', '.tsx', '.js', '.jsx', '.svelte', '.html'])
|
|
23
|
+
const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.nuxt', '.next', '.output', 'coverage'])
|
|
24
|
+
|
|
25
|
+
interface Hit {
|
|
26
|
+
file: string
|
|
27
|
+
line: number
|
|
28
|
+
text: string
|
|
29
|
+
kind: string
|
|
30
|
+
}
|
|
31
|
+
const hits: Hit[] = []
|
|
32
|
+
|
|
33
|
+
function classify(text: string, file: string): string | null {
|
|
34
|
+
const base = path.basename(file)
|
|
35
|
+
if (new RegExp(`<${name}[\\s/>]`).test(text)) return 'tag PascalCase'
|
|
36
|
+
if (new RegExp(`<${kebab}[\\s/>]`).test(text)) return 'tag kebab-case'
|
|
37
|
+
if (/:is=|<component\b/.test(text) && text.includes(name)) return 'dynamic usage (:is/component)'
|
|
38
|
+
if (/v-bind="(?!\$attrs)|\{\.\.\./.test(text) && text.includes(name)) return 'potential spread'
|
|
39
|
+
if (new RegExp(`\\b${name}\\b`).test(text)) {
|
|
40
|
+
if (/\.(spec|test|stories)\./.test(base)) return 'test/story'
|
|
41
|
+
if (/mock|fixture/i.test(file)) return 'mock/fixture'
|
|
42
|
+
return 'reference (import, type, doc)'
|
|
43
|
+
}
|
|
44
|
+
return null
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function walk(dir: string): void {
|
|
48
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
49
|
+
if (entry.isDirectory()) {
|
|
50
|
+
if (!SKIP.has(entry.name)) walk(path.join(dir, entry.name))
|
|
51
|
+
continue
|
|
52
|
+
}
|
|
53
|
+
if (!EXT.has(path.extname(entry.name))) continue
|
|
54
|
+
const file = path.join(dir, entry.name)
|
|
55
|
+
const lines = fs.readFileSync(file, 'utf-8').split('\n')
|
|
56
|
+
lines.forEach((text, i) => {
|
|
57
|
+
const kind = classify(text, file)
|
|
58
|
+
if (kind) hits.push({ file: path.relative(root, file), line: i + 1, text: text.trim().slice(0, 100), kind })
|
|
59
|
+
})
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
walk(root)
|
|
63
|
+
|
|
64
|
+
const selfFile = (f: string) => path.basename(f).startsWith(`${name}.`)
|
|
65
|
+
const external = hits.filter((h) => !selfFile(h.file))
|
|
66
|
+
const wrappers = [...new Set(external.map((h) => h.file))].filter((f) => {
|
|
67
|
+
const base = path.basename(f, path.extname(f))
|
|
68
|
+
return base !== name && (base.includes(name) || /legacy|wrapper|compat|adapter/i.test(base))
|
|
69
|
+
})
|
|
70
|
+
|
|
71
|
+
console.log(`# Sweep call sites - ${name} (kebab: ${kebab})\n`)
|
|
72
|
+
if (wrappers.length) {
|
|
73
|
+
console.log('## ⚠️ Suspicious wrappers/adapters - FIRST-CLASS call sites\n')
|
|
74
|
+
for (const w of wrappers) console.log(`- [ ] ${w}`)
|
|
75
|
+
console.log()
|
|
76
|
+
}
|
|
77
|
+
console.log('## Call sites to migrate\n')
|
|
78
|
+
const byFile = new Map<string, Hit[]>()
|
|
79
|
+
for (const h of external) byFile.set(h.file, [...(byFile.get(h.file) ?? []), h])
|
|
80
|
+
for (const [file, fileHits] of [...byFile].sort()) {
|
|
81
|
+
console.log(`- [ ] **${file}**`)
|
|
82
|
+
for (const h of fileHits) console.log(` L${h.line} [${h.kind}] ${h.text}`)
|
|
83
|
+
}
|
|
84
|
+
console.log(`\nTotal: ${byFile.size} file(s), ${external.length} occurrence(s).`)
|
|
85
|
+
console.log('Reminder: after migration, grepping the old prop name must return 0 occurrences among these consumers.')
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# API migration - <Component>: `<old>` → `<new>`
|
|
2
|
+
|
|
3
|
+
## Sweep (paste the output of sweep-call-sites.ts here)
|
|
4
|
+
|
|
5
|
+
- [ ] <file> - migrated / removed / not affected (justification)
|
|
6
|
+
|
|
7
|
+
## Checks
|
|
8
|
+
|
|
9
|
+
- [ ] Grep of the old name = **0 occurrences** among consumers
|
|
10
|
+
- [ ] Silent-contract: every prop passed by every call site is declared in the component's interface (manual if no strictTemplates)
|
|
11
|
+
- [ ] Every wrapper/adapter touched has its **mount unit test** (event bubbles up, prop drives the render)
|
|
12
|
+
- [ ] Existing tests assert the **new** name (not a CSS class that would pass anyway)
|
|
13
|
+
- [ ] Typecheck + unit tests green
|
|
14
|
+
|
|
15
|
+
## MR deliverable
|
|
16
|
+
|
|
17
|
+
| Call site | Status | Justification if not migrated |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| | | |
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# `validating-features-end-to-end`
|
|
2
|
+
|
|
3
|
+
> Green unit tests are not proof a feature works. Before closing the ticket, exercise it in the real running app and back every ✅ with an archivable artifact.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `feature` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | None dedicated (project dev/E2E commands + Playwright MCP) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`validating-features-end-to-end` is the gate between "implemented, tests green" and "done, ticket closed". It requires you to start the actual application, exercise the feature the ticket describes, and produce a short report where every claim is backed by evidence - a screenshot, a curl output, a read-only SQL query.
|
|
15
|
+
|
|
16
|
+
## Why it exists
|
|
17
|
+
|
|
18
|
+
"It compiles" is not "it works", and "green tests" is not "working feature". Green unit tests on a formatter do not prove the button downloads a file; a passing test with an over-permissive mock or an empty fixture exercises nothing. The gap between green and working is exactly where features get announced and then break in front of users.
|
|
19
|
+
|
|
20
|
+
The most expensive version of that gap is **cross-tenant leakage** in exports and lists - the #1 risk for any multi-tenant feature, and one that only two accounts from two tenants can reveal. So the skill insists on evidence before assertion, strict scope (validate *this* feature, not audit the project), and a filled report that turns "I believe it works" into "I verified X, Y, Z".
|
|
21
|
+
|
|
22
|
+
## When it triggers
|
|
23
|
+
|
|
24
|
+
- a feature is just implemented and tests pass
|
|
25
|
+
- "is it good?" / "does it work?" / "can I close the ticket?"
|
|
26
|
+
- green unit tests offered as the only evidence
|
|
27
|
+
|
|
28
|
+
Use `commit-readiness-review` instead if the question is "is it committable" (secrets, lint, debug leftovers), and move to `adversarial-feature-challenge` *after* - once it is proven to work, to hunt for what breaks it.
|
|
29
|
+
|
|
30
|
+
## How it works
|
|
31
|
+
|
|
32
|
+
You start the real app, derive the invariants from the ticket (golden path, error cases, business rules), then exercise each one and back every claim with an archivable artifact - a screenshot, a curl output, a read-only SQL query. Coverage spans the golden path, the planned edge cases (with two accounts from two tenants for multi-tenant isolation), backend/DB evidence, adjacent-domain non-regression, and a re-read of the green tests' assertions. The run ends in a mandatory evidence-backed report with an explicit verdict; if a gap is found, you **do not close the ticket** - document it and return to implementation.
|
|
33
|
+
|
|
34
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
35
|
+
|
|
36
|
+
## Worked example
|
|
37
|
+
|
|
38
|
+
> acme-app adds "export my invoices as CSV". Unit tests on the formatter are green.
|
|
39
|
+
|
|
40
|
+
1. Start the app; log in as tenant A and click Export → CSV downloads. Screenshot archived.
|
|
41
|
+
2. Edge case: log in as tenant B, call the export endpoint for tenant A's invoice id → expect 404/403. Verified with curl (status + body), output pasted.
|
|
42
|
+
3. Backend: `curl -i` shows `Content-Type: text/csv` and `Content-Disposition: attachment`; a read-only query confirms row count matches.
|
|
43
|
+
4. Run the billing E2E suite → green.
|
|
44
|
+
5. Report filled, verdict "ready for review".
|
|
45
|
+
|
|
46
|
+
## Related artifacts
|
|
47
|
+
|
|
48
|
+
- [`adversarial-feature-challenge`](../adversarial-feature-challenge/) - the next step: stress-test what breaks it.
|
|
49
|
+
- [`visual-regression-check`](../visual-regression-check/) - for the UI rendering side of a feature.
|
|
50
|
+
- [`writing-robust-tests`](../writing-robust-tests/) - to harden the E2E spec used as evidence.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: validating-features-end-to-end
|
|
3
|
+
description: Use when a feature is just implemented and tests pass, before closing a ticket or announcing it done - "is it good?", "does it work?", "ready to close the ticket?", "c'est bon ?", "est-ce que ça marche ?", "je peux fermer le ticket ?", green unit tests as only evidence.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: feature
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Functional validation of a feature - evidence before verdict
|
|
11
|
+
|
|
12
|
+
> If the current repo has a dedicated validation skill (e.g. acme-app → `feature-functional-validation`), it wins.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: feature implemented, tests green, before closing the ticket / announcing "done" - you must prove the intended behavior works in the real app
|
|
17
|
+
- **`adversarial-feature-challenge`** next: once it is proven to work, hunt for what breaks it
|
|
18
|
+
- **`commit-readiness-review`** instead if: the question is "is it committable" (secrets, lint, debug leftovers), not "does it work"
|
|
19
|
+
|
|
20
|
+
## Context to gather (before acting)
|
|
21
|
+
|
|
22
|
+
- The ticket/spec: golden path, explicit error cases, business rules - that is the list of invariants to validate
|
|
23
|
+
- Dev start command + the domain's E2E test command (`package.json` / `Makefile` / CI config)
|
|
24
|
+
- How to call the API directly (auth, base URL) and how to read the DB read-only
|
|
25
|
+
- If multi-tenant: 2 accounts from 2 distinct tenants to verify isolation
|
|
26
|
+
|
|
27
|
+
## Principle
|
|
28
|
+
|
|
29
|
+
- **"It compiles ≠ it works" and "green tests ≠ working feature"** - green unit tests on the formatter do not prove the button downloads a file
|
|
30
|
+
- **Evidence before assertion**: every ✅ in the report = an archivable artifact (screenshot, curl output, SQL query), never "it should work"
|
|
31
|
+
- **Strict scope**: validate THE requested feature, not audit the project
|
|
32
|
+
- Complementary to `adversarial-feature-challenge`: here you prove the intended behavior works; the challenge hunts for what breaks
|
|
33
|
+
|
|
34
|
+
## Workflow
|
|
35
|
+
|
|
36
|
+
1. **Actually start the app** (the project's dev command). No verdict without having exercised the feature in the running app.
|
|
37
|
+
2. **List the invariants** from the ticket/spec: golden path, explicit error cases, business rules. Validate **what the ticket asks for**, not what the code does.
|
|
38
|
+
3. **Golden path exercised with evidence**: preferably a dedicated E2E spec (page object, data-testid, zero hard waits) with a final screenshot; otherwise a driven manual walkthrough (Playwright MCP) + screenshot.
|
|
39
|
+
4. **Planned edge cases**: for each error case in the spec - 404/someone else's resource, insufficient rights, server validation, quota. **Multi-tenant: validate with 2 accounts from 2 tenants** (cross-tenant leakage is the #1 risk of exports/lists).
|
|
40
|
+
5. **Backend evidence**: direct API call (status, payload matching the contract, headers - e.g. `Content-Type`/`Content-Disposition` for an export) + read-only DB state.
|
|
41
|
+
6. **Adjacent non-regression**: run the E2E/test suite for the same functional domain - the feature must not break its neighbors.
|
|
42
|
+
7. **Re-read the assertions of the green tests**: a test with an over-permissive mock or an empty fixture passes without exercising anything. Green ≠ relevant.
|
|
43
|
+
|
|
44
|
+
## Report (mandatory, not optional)
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
Feature: <name> - Ticket: #<iid>
|
|
48
|
+
Golden path: ✅ (evidence: <screenshot path / output>)
|
|
49
|
+
Edge cases: <list with ✅/❌ and evidence for each>
|
|
50
|
+
Backend: API conforms ✅ · DB consistent ✅ (evidence)
|
|
51
|
+
Adjacent non-regression: <suites run + result>
|
|
52
|
+
Tenant isolation: ✅ (if applicable)
|
|
53
|
+
Verdict: ready for review | gap identified → <detail>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
If a gap: **do not close the ticket** - document it in the tracker and return to implementation.
|
|
57
|
+
|
|
58
|
+
## Exit condition
|
|
59
|
+
|
|
60
|
+
- [ ] App started and feature actually exercised (not just the tests)
|
|
61
|
+
- [ ] Golden path proven by an archived artifact (screenshot / output)
|
|
62
|
+
- [ ] Each edge case in the spec: ✅/❌ + evidence
|
|
63
|
+
- [ ] Backend verified: API conforms to the contract + consistent DB state
|
|
64
|
+
- [ ] Tenant isolation proven with 2 accounts (if applicable)
|
|
65
|
+
- [ ] Adjacent-domain suites run and green
|
|
66
|
+
- [ ] Report filled with evidence - verdict given (never "it should work")
|
|
67
|
+
|
|
68
|
+
## Forbidden rationalizations
|
|
69
|
+
|
|
70
|
+
| Excuse | Reality |
|
|
71
|
+
|--------|---------|
|
|
72
|
+
| "The tests pass, it's fine" | Tests cover what they test. Did you see the feature work in the app? |
|
|
73
|
+
| "I checked by hand, no need to archive" | Without evidence, the report is worth an opinion. Screenshot/output or nothing. |
|
|
74
|
+
| "It's late, we'll check tomorrow" | 10 min tonight < an incident after the announcement. Verify the critical (tenant, golden path), defer the cosmetic. |
|
|
75
|
+
| "The report is bureaucracy" | It is what turns "I believe" into "I verified X, Y, Z". |
|
|
76
|
+
|
|
77
|
+
## Tooling
|
|
78
|
+
|
|
79
|
+
- Browser driving for UI evidence: Playwright MCP (`browser_navigate`, `browser_snapshot`, `browser_take_screenshot`) or the project's E2E runner
|
|
80
|
+
- Backend evidence: HTTP client on the CLI (status, headers, payload) + read-only DB access
|
|
81
|
+
- No dedicated script here: the commands (dev, E2E) are project-specific - read them from its config
|
|
82
|
+
|
|
83
|
+
## After
|
|
84
|
+
|
|
85
|
+
- Adversarial stress-test: `adversarial-feature-challenge`
|
|
86
|
+
- Bug found: `superpowers:systematic-debugging`, ticket via the repo's bug skill
|
|
87
|
+
|
|
88
|
+
## Changelog
|
|
89
|
+
|
|
90
|
+
- 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
|