ronce-racine 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/AGENTS.md +90 -0
  2. package/LICENSE +21 -0
  3. package/README.md +281 -0
  4. package/agents/code-reviewer.md +33 -0
  5. package/agents/qa-tester.md +28 -0
  6. package/dist/hooks/README.md +182 -0
  7. package/dist/hooks/bash-npm-silent.mjs +81 -0
  8. package/dist/hooks/session-inject.mjs +53 -0
  9. package/dist/hooks/session-precompact.mjs +36 -0
  10. package/dist/hooks/session-writer.mjs +142 -0
  11. package/dist/hooks/skill-reminder.mjs +89 -0
  12. package/dist/hooks/truncate-bash-output.mjs +46 -0
  13. package/dist/hooks/truncate-output.mjs +88 -0
  14. package/dist/hooks/worktree-env-setup.mjs +123 -0
  15. package/dist/install.js +962 -0
  16. package/docs/adopting-a-repo.md +80 -0
  17. package/docs/architecture.md +76 -0
  18. package/docs/decisions.md +72 -0
  19. package/docs/developing.md +143 -0
  20. package/docs/evaluating-skills.md +41 -0
  21. package/docs/git-worktrees.md +62 -0
  22. package/docs/rules/clean-architecture-deps.md +66 -0
  23. package/docs/rules/commits.md +59 -0
  24. package/docs/rules/detection-gap-protocol.md +55 -0
  25. package/docs/rules/error-handling-discipline.md +62 -0
  26. package/docs/rules/minimal-code.md +58 -0
  27. package/docs/rules/no-raw-sql-interpolation.md +57 -0
  28. package/docs/rules/pre-commit-secret-detection.md +54 -0
  29. package/docs/rules/secure-logging.md +53 -0
  30. package/docs/rules/sql-migrations-discipline.md +58 -0
  31. package/docs/rules/subscription-cleanup.md +63 -0
  32. package/docs/rules/test-discipline.md +66 -0
  33. package/docs/rules/ui-states-complete.md +52 -0
  34. package/docs/templates/SKILL.template.md +66 -0
  35. package/docs/templates/rule.template.md +16 -0
  36. package/docs/writing-a-rule.md +43 -0
  37. package/docs/writing-a-skill.md +118 -0
  38. package/package.json +45 -0
  39. package/rules/clean-architecture-deps.md +20 -0
  40. package/rules/commits.md +16 -0
  41. package/rules/detection-gap-protocol.md +35 -0
  42. package/rules/error-handling-discipline.md +23 -0
  43. package/rules/minimal-code.md +32 -0
  44. package/rules/no-raw-sql-interpolation.md +20 -0
  45. package/rules/pre-commit-secret-detection.md +14 -0
  46. package/rules/secure-logging.md +16 -0
  47. package/rules/sql-migrations-discipline.md +18 -0
  48. package/rules/subscription-cleanup.md +22 -0
  49. package/rules/test-discipline.md +20 -0
  50. package/rules/ui-states-complete.md +23 -0
  51. package/scripts/subscription-leak-scan.ts +53 -0
  52. package/skills/adversarial-feature-challenge/README.md +65 -0
  53. package/skills/adversarial-feature-challenge/SKILL.md +96 -0
  54. package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
  55. package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
  56. package/skills/api-contract-versioning/README.md +62 -0
  57. package/skills/api-contract-versioning/SKILL.md +76 -0
  58. package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
  59. package/skills/audit-architecture/README.md +56 -0
  60. package/skills/audit-architecture/SKILL.md +97 -0
  61. package/skills/audit-architecture/reference/ar-architecture.md +275 -0
  62. package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
  63. package/skills/audit-architecture/reference/im-incidents.md +217 -0
  64. package/skills/audit-architecture/reference/pa-pannes.md +362 -0
  65. package/skills/audit-architecture/reference/re-recuperation.md +300 -0
  66. package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
  67. package/skills/audit-architecture/reference/su-support.md +180 -0
  68. package/skills/audit-ci-cd/README.md +54 -0
  69. package/skills/audit-ci-cd/SKILL.md +124 -0
  70. package/skills/audit-ci-cd/reference/artefacts.md +39 -0
  71. package/skills/audit-ci-cd/reference/deploiement.md +100 -0
  72. package/skills/audit-ci-cd/reference/dora.md +94 -0
  73. package/skills/audit-ci-cd/reference/iac.md +40 -0
  74. package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
  75. package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
  76. package/skills/audit-compliance/README.md +69 -0
  77. package/skills/audit-compliance/SKILL.md +176 -0
  78. package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
  79. package/skills/audit-compliance/reference/finops.md +318 -0
  80. package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
  81. package/skills/audit-industrialisation/README.md +53 -0
  82. package/skills/audit-industrialisation/SKILL.md +251 -0
  83. package/skills/audit-observability/README.md +64 -0
  84. package/skills/audit-observability/SKILL.md +134 -0
  85. package/skills/audit-observability/reference/alerting.md +214 -0
  86. package/skills/audit-observability/reference/logging.md +114 -0
  87. package/skills/audit-observability/reference/metriques.md +166 -0
  88. package/skills/audit-observability/reference/traces-dashboards.md +90 -0
  89. package/skills/audit-performance-frontend/README.md +91 -0
  90. package/skills/audit-performance-frontend/SKILL.md +194 -0
  91. package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
  92. package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
  93. package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
  94. package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
  95. package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
  96. package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
  97. package/skills/audit-quality/README.md +85 -0
  98. package/skills/audit-quality/SKILL.md +126 -0
  99. package/skills/audit-quality/reference/qa-devops.md +539 -0
  100. package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
  101. package/skills/audit-report/README.md +72 -0
  102. package/skills/audit-report/SKILL.md +241 -0
  103. package/skills/audit-report/reference/scoring-model.md +45 -0
  104. package/skills/audit-security/README.md +72 -0
  105. package/skills/audit-security/SKILL.md +140 -0
  106. package/skills/audit-security/reference/auth-identite.md +98 -0
  107. package/skills/audit-security/reference/autorisation.md +66 -0
  108. package/skills/audit-security/reference/chiffrement-tls.md +97 -0
  109. package/skills/audit-security/reference/detection-patching.md +67 -0
  110. package/skills/audit-security/reference/incident-response.md +98 -0
  111. package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
  112. package/skills/audit-security/reference/secrets.md +36 -0
  113. package/skills/audit-testing/README.md +82 -0
  114. package/skills/audit-testing/SKILL.md +131 -0
  115. package/skills/audit-testing/reference/golden-dataset.md +65 -0
  116. package/skills/audit-testing/reference/resilience-chaos.md +93 -0
  117. package/skills/audit-testing/reference/tests-contractuels.md +65 -0
  118. package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
  119. package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
  120. package/skills/bug-ticket-root-cause/README.md +67 -0
  121. package/skills/bug-ticket-root-cause/SKILL.md +86 -0
  122. package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
  123. package/skills/bug-triage-structured/README.md +63 -0
  124. package/skills/bug-triage-structured/SKILL.md +104 -0
  125. package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
  126. package/skills/ci-pipeline-orchestration/README.md +55 -0
  127. package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
  128. package/skills/commit-readiness-review/README.md +66 -0
  129. package/skills/commit-readiness-review/SKILL.md +82 -0
  130. package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
  131. package/skills/comprehensive-test-strategy/README.md +64 -0
  132. package/skills/comprehensive-test-strategy/SKILL.md +108 -0
  133. package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
  134. package/skills/daily-workflow-optimization/README.md +56 -0
  135. package/skills/daily-workflow-optimization/SKILL.md +80 -0
  136. package/skills/database-schema-evolution/README.md +54 -0
  137. package/skills/database-schema-evolution/SKILL.md +107 -0
  138. package/skills/ddd-backend-implementation/README.md +63 -0
  139. package/skills/ddd-backend-implementation/SKILL.md +95 -0
  140. package/skills/design-system-component-lifecycle/README.md +56 -0
  141. package/skills/design-system-component-lifecycle/SKILL.md +97 -0
  142. package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
  143. package/skills/detection-sweep/README.md +58 -0
  144. package/skills/detection-sweep/SKILL.md +93 -0
  145. package/skills/detection-sweep/scripts/sweep.ts +80 -0
  146. package/skills/domain-modeling-design/README.md +57 -0
  147. package/skills/domain-modeling-design/SKILL.md +83 -0
  148. package/skills/frontend-fullstack-implementation/README.md +60 -0
  149. package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
  150. package/skills/frontend-spec-call-site-audit/README.md +66 -0
  151. package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
  152. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
  153. package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
  154. package/skills/merge-request-review/README.md +60 -0
  155. package/skills/merge-request-review/SKILL.md +77 -0
  156. package/skills/merge-request-review/templates/mr-review-report.md +29 -0
  157. package/skills/production-incident-diagnostic/README.md +63 -0
  158. package/skills/production-incident-diagnostic/SKILL.md +103 -0
  159. package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
  160. package/skills/qa-session-intake/README.md +56 -0
  161. package/skills/qa-session-intake/SKILL.md +78 -0
  162. package/skills/recording-decisions/README.md +91 -0
  163. package/skills/recording-decisions/SKILL.md +84 -0
  164. package/skills/recurring-bug-root-cause/README.md +64 -0
  165. package/skills/recurring-bug-root-cause/SKILL.md +93 -0
  166. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
  167. package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
  168. package/skills/refactoring-shared-component-api/README.md +50 -0
  169. package/skills/refactoring-shared-component-api/SKILL.md +84 -0
  170. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
  171. package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
  172. package/skills/validating-features-end-to-end/README.md +50 -0
  173. package/skills/validating-features-end-to-end/SKILL.md +90 -0
  174. package/skills/visual-regression-check/README.md +51 -0
  175. package/skills/visual-regression-check/SKILL.md +89 -0
  176. package/skills/writing-robust-tests/README.md +53 -0
  177. package/skills/writing-robust-tests/SKILL.md +88 -0
  178. package/templates/.adopted.example +8 -0
  179. package/templates/anti-drift.gitlab-ci.yml +23 -0
@@ -0,0 +1,77 @@
1
+ ---
2
+ name: merge-request-review
3
+ description: Use when reviewing a merge/pull request or a branch diff before merge - "review this MR", "review this PR", "validate this branch diff", "review cette MR", "review cette PR", "valide ce diff de branche", before integrating someone else's work into the mainline.
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: process
8
+ ---
9
+
10
+ # Merge Request Review - reviewing a change before integration
11
+
12
+ > If the current repo has a specific review skill (e.g. acme-app → `mr-review`), it wins - it knows the forge, the tracker, the API commands and the project's optional auto-merge.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: reviewing the diff of an MR/PR or a branch **that is someone else's or not yet integrated** before merge - "review this PR", "validate this diff", "OK to merge?"
17
+ - **`commit-readiness-review`** instead if: it is **my own** changes to commit (before commit, not before merging a third-party branch)
18
+ - **`superpowers:requesting-code-review`** instead if: I want **my own** finished work reviewed, not to review someone else's
19
+ - **`validating-features-end-to-end`** instead if: the question is "does it work" (functional proof), not "is it mergeable"
20
+
21
+ ## Principle
22
+
23
+ - **Approving = having read the diff line by line.** A "green pipeline" proves the existing tests pass, not that the code is correct, safe or complete.
24
+ - The review produces an **explicit verdict**: approve / request changes - never a vague "looks good".
25
+
26
+ ## Context to gather (before acting)
27
+
28
+ - **The full diff** of the source branch against the target: `git fetch <remote> <source-branch>` then `git diff <remote>/<target>...<remote>/<source-branch>` (not just the forge summary)
29
+ - **The pipeline / CI status** of the MR/PR (green / red / running) via the forge UI or CLI
30
+ - **The linked ticket / issue**: what the change is supposed to do → check the diff does it, and only that
31
+ - **The repo conventions**: message format, lint/typecheck/test per stack (`package.json` / `Cargo.toml` / `Makefile` / CI config)
32
+
33
+ ## Protocol
34
+
35
+ Read the whole diff first, then work through the checklist:
36
+
37
+ ```
38
+ - [ ] Pipeline / CI green (and looked at: which jobs, not just the overall badge)
39
+ - [ ] Debug leftovers in added lines (console.log, print, dbg!, debugger, unjustified unwrap/expect)
40
+ - [ ] Hard-coded waits (waitForTimeout, sleep) in tests
41
+ - [ ] Contract / API respected: public signatures, props, events, schema - no unflagged breaking change
42
+ - [ ] i18n: no visible hard-coded string if the project is internationalized
43
+ - [ ] Sensitive files: .env, *.pem, *.key, credentials, secrets → STOP
44
+ - [ ] Disabled tests (.skip, xit, #[ignore]) without justification
45
+ - [ ] No conflict with the target (otherwise → resolve before merge)
46
+ - [ ] The diff does what the ticket says, and nothing out of scope
47
+ - [ ] Explicit verdict issued: approve OR request changes
48
+ ```
49
+
50
+ If there is a conflict with the target: rebase/merge the target into the source, re-validate lint/test, re-push - never force-push the default branch. Schema migration already applied → do not modify the old one, create a new one.
51
+
52
+ ## Templates
53
+
54
+ - `templates/mr-review-report.md` - review report (verdict, blocking points, minor points)
55
+
56
+ ## Traps & rationalizations
57
+
58
+ | Excuse | Reality |
59
+ |--------|---------|
60
+ | "Pipeline green, I approve" | The pipeline tests the existing code, not the correctness or safety of the new code. Read the diff |
61
+ | "Small diff, no need to read" | A secret or a breaking change fits in one line |
62
+ | "It's urgent, I merge" | Urgency does not change the checklist; a broken merge costs more than a review |
63
+ | "The contract doesn't look touched" | Check the public signatures/props/events called elsewhere, don't assume |
64
+ | "Minor conflict, I force-push" | Always `--force-with-lease`, never on the default branch |
65
+
66
+ ## Exit condition
67
+
68
+ - [ ] Full diff read (not just the forge summary)
69
+ - [ ] Whole checklist worked through; every gap → blocking or justified
70
+ - [ ] Verdict issued: approve or request changes, with reasons
71
+ - [ ] If merged: green pipeline confirmed and no sensitive files
72
+
73
+ As long as a blocking point remains, do not approve.
74
+
75
+ ## Changelog
76
+
77
+ - 1.0.0 (2026-06-19) - initial version, derived from an MR review workflow; forge/tracker/auto-merge coupling removed
@@ -0,0 +1,29 @@
1
+ # Review - <MR/PR #id or branch>
2
+
3
+ **Target**: `<target-branch>` ← **Source**: `<source-branch>`
4
+ **Ticket**: <id / link> - <what the change should do>
5
+ **Pipeline / CI**: <green / red / running - jobs looked at>
6
+
7
+ ## Verdict
8
+
9
+ > **APPROVE** | **REQUEST CHANGES**
10
+
11
+ ## Blocking points
12
+
13
+ - [ ] <file:line - problem - expected fix>
14
+
15
+ ## Minor points (non-blocking)
16
+
17
+ - <file:line - suggestion>
18
+
19
+ ## Checklist
20
+
21
+ - [ ] CI green (jobs verified)
22
+ - [ ] No debug leftovers
23
+ - [ ] No hard-coded waits in tests
24
+ - [ ] Contract / API respected
25
+ - [ ] i18n OK
26
+ - [ ] No sensitive files
27
+ - [ ] No unjustified disabled tests
28
+ - [ ] No conflict with the target
29
+ - [ ] Diff matches the ticket, nothing out of scope
@@ -0,0 +1,63 @@
1
+ # `production-incident-diagnostic`
2
+
3
+ > Traverse a live incident layer by layer - hosting, backend, alerting, frontend - and isolate the faulty one with evidence before touching anything. Never a blind restart.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `process` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | [`templates/incident-report.md`](templates/incident-report.md) · generic (`curl`, dashboard, read-only DB, tracing) |
11
+
12
+ ## What it is
13
+
14
+ `production-incident-diagnostic` is a triage protocol for **live production incidents**. It moves methodically from symptom to faulty layer: reproduce, categorize, check the running version, read logs, read metrics, follow traces, bisect layer by layer, and only then state a supported root cause and choose a mitigation. Its output is never a blind restart - it is a located layer, an evidenced cause, and a deliberate fix.
15
+
16
+ It is infra-agnostic. When the current repo has its own prod-diagnostic skill that knows the hosting and observability stack, that one wins.
17
+
18
+ ## Why it exists
19
+
20
+ Under incident pressure, the instinct is to act before understanding - restart the process, blame "the database", declare it fixed when the symptom disappears. Each of these destroys evidence or masks a cause that will return:
21
+
22
+ - **A restart before diagnosis** erases the logs and metrics that would have pinned the cause.
23
+ - **An unproven "it's probably the network"** sends the fix at the wrong layer.
24
+ - **A vanished symptom** without a root cause is an incident that will replay.
25
+ - **A green deploy** can still be serving the old image - the version actually running must be verified, not assumed.
26
+
27
+ The skill enforces the opposite reflex: **evidence before conclusion**, one proof per layer, and read-only access by default with explicit confirmation for any destructive action.
28
+
29
+ ## When it triggers
30
+
31
+ Invoke it when diagnosing a production incident:
32
+
33
+ - "prod is down", an API responding 502/503/500 or slow, abnormal behavior in prod
34
+ - a user reporting something broken in production
35
+ - alerting gone silent
36
+
37
+ Quick disambiguation: prod reachable but misbehaving → this skill. Pipeline red but prod fine → `ci-pipeline-orchestration`. A bug that recurs (2+ similar fixes) → [`recurring-bug-root-cause`](../recurring-bug-root-cause/). Static code problems across the project, outside any incident → [`detection-sweep`](../detection-sweep/).
38
+
39
+ ## How it works
40
+
41
+ The skill descends the stack layer by layer - quick triage and symptom categorization, the version actually running, logs, metrics and alerts, traces, then bisection - accumulating one piece of evidence per layer until the faulty one is isolated. Only then does it state a supported root cause and choose a mitigation (rollback vs forward-fix), with read-only access by default and explicit confirmation for any destructive action.
42
+
43
+ Full step-by-step protocol → [`SKILL.md`](SKILL.md).
44
+
45
+ ### Record the incident
46
+
47
+ [`templates/incident-report.md`](templates/incident-report.md) captures scope, faulty layer, timeline, evidence, root cause, mitigation, and follow-up tickets (including any missing observability that failed to alert).
48
+
49
+ ## Worked example
50
+
51
+ > "The API is returning 502s."
52
+
53
+ 1. **Triage**: `curl -I` the health endpoint → also 502. Table says hosting / process down.
54
+ 2. **Version**: the last deploy is 10 minutes old and marked success - but the running container is on the *previous* image (a known "green deploy, old image" trap).
55
+ 3. **Logs**: the new process crash-loops on startup with a missing env var.
56
+ 4. **Bisection**: reverse proxy up, app process down → hosting/deploy layer confirmed.
57
+ 5. **Root cause**: the release introduced a required config value never set in prod.
58
+ 6. **Mitigation**: rollback (fast, reversible), then add the missing variable and re-deploy. Health endpoint re-checked OK, output pasted. Incident report written, follow-up ticket to add a startup-config check.
59
+
60
+ ## Related artifacts
61
+
62
+ - [`recurring-bug-root-cause`](../recurring-bug-root-cause/) - for a bug class that keeps coming back, not a live incident.
63
+ - [`detection-sweep`](../detection-sweep/) - for static problem-hunting across the whole project.
@@ -0,0 +1,103 @@
1
+ ---
2
+ name: production-incident-diagnostic
3
+ description: Use when diagnosing a production incident - "prod is down", "la prod est down", an API responding 502/500/slow, abnormal behavior in prod, a user reporting something broken in production, alerting gone silent. Triggers on localizing the faulty layer of a live system.
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: process
8
+ ---
9
+
10
+ # Production incident triage - from symptom to faulty layer
11
+
12
+ > If the current repo has a specific prod-diagnostic skill (e.g. acme-app → `production-diagnostic`), it wins - it knows the hosting, the observability tool, the endpoints and the project tracker.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: a **production** incident - prod down, API misbehaving (502/503/500/slow), abnormal behavior in prod, user report, silent alerting
17
+ - **`ci-pipeline-orchestration`** instead if: the CI pipeline is red but **prod runs normally** (build/release problem, not a live incident)
18
+ - **`recurring-bug-root-cause`** instead if: a bug that **recurs** (2+ similar fixes) - class hunting, not a live incident
19
+ - **`detection-sweep`** instead if: hunting **static** code problems across the whole project, outside an incident
20
+
21
+ > Quick rule: prod reachable but misbehaving → this skill; pipeline red, prod OK → ci-pipeline-orchestration.
22
+
23
+ ## Principle
24
+
25
+ **Isolate the layer before fixing.** An incident is traversed layer by layer - hosting/deployment → backend/API → alerting → frontend - until the faulty one is located. **Evidence before conclusion**: never "it's probably X" without a log, metric, trace or reproduction. The output = faulty layer + supported root cause + mitigation, not a blind restart.
26
+
27
+ ## Context to gather (before acting)
28
+
29
+ - **Scope**: is everything affected, or one endpoint / one feature / a subset of users?
30
+ - **Since when**: timestamp of the first symptom; does it correlate with a deployment, a migration, a traffic spike?
31
+ - **Suspected layer** from the symptom (see triage table)
32
+ - **Access**: health endpoint URLs, access to logs / metrics / traces (observability tool, dashboard), status of the last deployment, read-only DB access
33
+ - Project conventions: deploy/rollback commands, tracker for the incident ticket
34
+
35
+ ## Protocol
36
+
37
+ ### 1. Quick triage - categorize the symptom
38
+ - Reproduce the symptom (curl the endpoint, user journey) and note the exact code/behavior
39
+ - Hit the **health endpoint** (liveness/readiness) if exposed
40
+
41
+ | Symptom | Likely layer |
42
+ |---------|--------------|
43
+ | 502/503 | Hosting / process down / reverse proxy |
44
+ | Health 200 but 500 on endpoints | Partial backend (DB, external dependency) |
45
+ | Abnormal latency, timeouts | Saturation (DB pool, CPU, queue) |
46
+ | Blocked job/worker | Crashed worker or deadlock |
47
+ | Silent alerting | Channel config / rate limiting |
48
+ | Blank page, asset 404s | Corrupted frontend build/deploy, cache/CDN |
49
+ | Errors specific to one user | Auth / permissions / data |
50
+
51
+ ### 2. Check deployment & version
52
+ - **What version is actually running in prod?** Compare to the expected commit (a "deploy success" serving the old image is a classic)
53
+ - Last deployment / migration: timing vs incident start → rollback candidate
54
+
55
+ ### 3. Logs
56
+ - Filter the observability tool on the incident window and the suspected layer
57
+ - Look for: crash/panic/exception, OOM, "too many connections", exhausted descriptors, external dependency errors
58
+
59
+ ### 4. Metrics & alerts
60
+ - Dashboard: CPU/memory, error rate, p95/p99 latency, connection pool saturation, queue depth
61
+ - Should an alert have fired? If not, an observability gap to track too
62
+
63
+ ### 5. Traces
64
+ - If distributed tracing available: follow a faulty request end-to-end to locate the slow/failed hop
65
+
66
+ ### 6. Layer bisection
67
+ - Confirm/rule out each layer with evidence (health responds → process up; direct DB query responds → DB up). Descend to the layer that faults.
68
+
69
+ ### 7. Root cause + mitigation
70
+ - State the **supported** root cause (log/trace/repro). Decide mitigation: rollback (fast, reversible) vs forward-fix - when in doubt, ask the user
71
+ - Any destructive action in prod (UPDATE/DELETE, restart, purge): **explicit user confirmation**, read-only access by default
72
+
73
+ ## Templates
74
+
75
+ - `templates/incident-report.md` - incident report (timeline, layer, evidence, root cause, mitigation, follow-up)
76
+
77
+ ## Traps & rationalizations
78
+
79
+ | Excuse | Reality |
80
+ |--------|---------|
81
+ | "I'll restart, it'll come back" | A restart without diagnosis erases the evidence and hides a cause that will return. Capture logs/metrics first. |
82
+ | "The symptom is gone, it's fixed" | Fixing a symptom without a root cause = an incident that replays. No closure without a supported cause. |
83
+ | "It's probably the DB / the network" | Unproven hypothesis. One piece of evidence per layer, otherwise you treat the wrong one. |
84
+ | "The deploy is green, prod is up to date" | Verify the version actually served - a green deploy can serve the old image. |
85
+ | "I'll write up the incident later" | "Later" never comes. Report + ticket before closure. |
86
+
87
+ ## Exit condition
88
+
89
+ - [ ] Symptom reproduced and scope delimited
90
+ - [ ] Faulty layer isolated with at least one piece of evidence (log, metric, trace or repro)
91
+ - [ ] Root cause documented - never an unproven hypothesis
92
+ - [ ] Mitigation applied or planned; destructive actions confirmed by the user
93
+ - [ ] Prod re-checked: health endpoint OK and symptom gone (output pasted)
94
+ - [ ] Incident report written + ticket created if prod was impacted
95
+
96
+ ## Tooling
97
+
98
+ - `templates/incident-report.md` - report template to fill in
99
+ - Generic tools: `curl -v`/`-I` on health endpoints, query the observability dashboard over the window, read-only DB query, trace following
100
+
101
+ ## Changelog
102
+
103
+ - 1.0.0 (2026-06-19) - initial version, derived from a project workflow decanted of all infra coupling
@@ -0,0 +1,33 @@
1
+ # Incident report - <short summary>
2
+
3
+ ## Summary
4
+ - **Scope**: <everything / endpoint / feature / subset of users>
5
+ - **First detected**: <timestamp>
6
+ - **Detected by**: <alert / user report / monitoring>
7
+ - **Status**: <ongoing | mitigated | resolved | escalated>
8
+
9
+ ## Faulty layer
10
+ <hosting/deployment | backend/API | alerting | frontend | data>
11
+
12
+ ## Timeline
13
+ | Time | Event |
14
+ |------|-------|
15
+ | <ts> | <symptom observed> |
16
+ | <ts> | <diagnostic action> |
17
+ | <ts> | <mitigation applied> |
18
+
19
+ ## Evidence
20
+ - <log excerpt>
21
+ - <metric / dashboard capture>
22
+ - <trace / query result>
23
+ - <reproduction command + output>
24
+
25
+ ## Root cause
26
+ <hypothesis supported by the evidence above - no unproven speculation>
27
+
28
+ ## Mitigation
29
+ - <rollback / forward-fix / confirmed restart / confirmed purge>
30
+
31
+ ## Follow-up
32
+ - [ ] <hardening action> - ticket #<iid>
33
+ - [ ] <missing observability to add if the incident did not alert> - ticket #<iid>
@@ -0,0 +1,56 @@
1
+ # `qa-session-intake`
2
+
3
+ > Turn a recorded human QA session - timeline, screenshots, network errors - into a clean set of tracker tickets, one per distinct problem, with nothing lost silently.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `process` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | None generic (project intake tool if present) |
11
+
12
+ ## What it is
13
+
14
+ `qa-session-intake` is a triage discipline. A manual QA pass produces a noisy bundle: a timestamped timeline of verbal remarks, a pile of screenshots, and a log of network errors captured by the browser. Left raw, it is unusable - too much to act on, too easy to lose. This skill converts that bundle into a small, actionable set of tickets plus an auditable trace of what happened to every signal.
15
+
16
+ ## Why it exists
17
+
18
+ The two failure modes of manual triage are opposite and equally bad:
19
+
20
+ - **One ticket per event** - 45 network errors become 45 tickets. The signal drowns in noise; nobody triages 45 items.
21
+ - **One mega-ticket** - the whole session dumped into a single issue. Untriageable, unclosable, forgotten.
22
+
23
+ Both destroy the value of the session. The fix is a firm rule - **one ticket per distinct problem** - plus correlation done *before* any ticket is created, so a 40-minute session collapses to the 5–10 real problems it actually surfaced.
24
+
25
+ It also defends against a subtler loss: a network error the tester never noticed. A silently failing endpoint can hide data loss, so "the tester said nothing" is not a reason to drop it.
26
+
27
+ ## When it triggers
28
+
29
+ Invoke it when you have a recorded QA session bundle to process into tickets:
30
+
31
+ - "process the QA session" / "create the QA tickets"
32
+ - a QA bundle folder (timeline + screenshots + network log) to triage
33
+
34
+ Use a sibling skill instead when: a single observed bug outside a session (`bug-ticket-root-cause`), or proving a specific feature works (`validating-features-end-to-end`).
35
+
36
+ ## How it works
37
+
38
+ The skill correlates before it creates: the timeline is read chronologically, network errors are clustered by `(endpoint, status, message)` and attached to the tester's remarks, and only then are tickets opened following a signal hierarchy (verbal remark → always a ticket; repeated cluster with estimable impact → triage ticket; isolated no-impact error → attached or ignored with a reason). The deliverable is not just the 5–10 tickets but a traceable result - a session summary plus an annotated trace where every network error and screenshot is accounted for.
39
+
40
+ Full step-by-step protocol → [`SKILL.md`](SKILL.md).
41
+
42
+ ## Worked example
43
+
44
+ > A 40-minute session on acme-app: 28 timeline events, 45 captured network errors.
45
+
46
+ 1. Correlation groups the 45 errors into 7 `(endpoint, status)` clusters; 4 align with tester remarks.
47
+ 2. Two remarks describe the same broken screen with the same interaction → merged into one ticket.
48
+ 3. A repeated `POST /export 500` cluster with no remark is estimated to drop rows silently → its own triage ticket.
49
+ 4. The remaining isolated 401s are marked `ignored: no impact` in the trace.
50
+ 5. Result: **6 tickets**, a session summary, and a trace where all 45 errors are accounted for.
51
+
52
+ ## Related artifacts
53
+
54
+ - [`bug-ticket-root-cause`](../bug-ticket-root-cause/) - for a single observed bug, with its root cause.
55
+ - [`validating-features-end-to-end`](../validating-features-end-to-end/) - to prove a specific feature works, not to triage remarks.
56
+ - [`recurring-bug-root-cause`](../recurring-bug-root-cause/) - when the session surfaces the Nth instance of the same class.
@@ -0,0 +1,78 @@
1
+ ---
2
+ name: qa-session-intake
3
+ description: Use when processing a recorded human QA session (timeline of verbal remarks, screenshots, captured network errors) into tracker tickets - "process the QA session", "create the QA tickets", "traite la session QA", "crée les tickets QA", a QA bundle folder to triage.
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: process
8
+ ---
9
+
10
+ # QA Session Intake - from a recorded QA session to tickets
11
+
12
+ > If the current repo has dedicated intake tooling (e.g. acme-app → `qa-intake` + `tool/qa-session/`), it wins - run its script instead of triaging by hand.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: triaging a recorded QA session bundle (timeline, screenshots, network errors) into tickets
17
+ - **`bug-ticket-root-cause`** if: a single observed bug outside a QA session, to document with its root cause
18
+ - **`validating-features-end-to-end`** if: the goal is to prove a specific feature works, not to triage remarks
19
+
20
+ ## Principle
21
+
22
+ **One ticket per distinct problem, not per event.** A 40-minute session with 28 events and 45 network errors typically yields 5–10 tickets. 45 tickets = noise that buries the signal; 1 mega-ticket = untriageable.
23
+
24
+ ## Context to gather (before acting)
25
+
26
+ - Inventory the bundle: timestamped timeline, screenshots (with timestamps), network-error log
27
+ - Tracker + the repo's format/label/severity conventions (the project's bug skill if it exists) - do not invent
28
+ - Existing open tickets, for de-duplication
29
+ - Version/build under test and the functional areas the session covered
30
+
31
+ ## Triage
32
+
33
+ 1. **Correlate before creating**: read the timeline in chronological order; group network errors by `(endpoint, status, message)`; attach each cluster to its time window and the tester's remarks; only look at screenshots that coincide with an event.
34
+ 2. **Signal hierarchy**:
35
+ - **Tester's verbal remark** → always a ticket (most reliable signal), merge if same screen + same interaction
36
+ - **Repeated network cluster with no remark** → a triage ticket if the impact is estimable (missing data, silent failure) - do not ignore it because "the tester didn't notice": a silently failing endpoint can hide data loss
37
+ - **Isolated network error with no visible impact** → attach to an existing ticket or mark as ignored with a reason
38
+ 3. **Content of each ticket**: title from the user's point of view · steps reconstructed from the timeline (timestamps) · expected vs actual · closest screenshot attached · network requests from the ±5 s window if relevant · estimated severity.
39
+
40
+ ## Traceability (nothing is lost silently)
41
+
42
+ Deliver alongside the tickets:
43
+ - **Session summary**: areas tested, breakdown by severity, areas not covered
44
+ - **Annotated trace**: each network error marked → `ticket #N` | `ignored: duplicate` | `ignored: no impact` - verifiable by anyone
45
+ - Unused screenshots listed with a reason
46
+
47
+ ## Guardrails
48
+
49
+ - Do not create a ticket without reconstructed reproduction steps - a ticket "401 error somewhere" is unclosable
50
+ - De-duplication: search open tickets before creating
51
+ - Format/labels: follow the repo tracker's conventions (the project's bug skill if it exists)
52
+
53
+ ## Traps & rationalizations
54
+
55
+ | Excuse | Reality |
56
+ |--------|---------|
57
+ | "45 network errors → I create 45 tickets" | One ticket per distinct problem, not per event. Correlate first; 5–10 tickets typical. |
58
+ | "Everything in one session mega-ticket" | Untriageable and unclosable. One problem = one ticket. |
59
+ | "The tester said nothing, I ignore the network error" | A silently failing endpoint can hide data loss. Triage if the impact is estimable. |
60
+ | "401 error somewhere, I create the ticket" | Without steps reconstructed from the timeline, the ticket is unclosable. |
61
+ | "I create quickly, I check duplicates later" | Search open tickets first - the duplicate pollutes the tracker. |
62
+
63
+ ## Exit condition
64
+
65
+ - [ ] One ticket per distinct problem, each with reconstructed steps, expected vs actual, closest screenshot, severity
66
+ - [ ] Annotated trace: each network error marked `ticket #N` | `ignored: <reason>` - verifiable
67
+ - [ ] Session summary delivered (areas tested, severity breakdown, areas not covered)
68
+ - [ ] Unused screenshots listed with a reason
69
+ - [ ] De-duplication done against open tickets
70
+
71
+ ## Tooling
72
+
73
+ - No generic script (triage depends on the bundle format): if the repo has dedicated intake tooling, run it (see header note).
74
+ - Follow the project bug skill's ticket template for the content of each ticket created.
75
+
76
+ ## Changelog
77
+
78
+ - 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
@@ -0,0 +1,91 @@
1
+ # `recording-decisions`
2
+
3
+ > Capture non-obvious technical choices the moment they are made, so no one silently undoes them three weeks later.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `process` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | None (human-driven; inline templates) |
11
+
12
+ ## What it is
13
+
14
+ `recording-decisions` is a discipline for **institutional memory**. Every codebase accumulates choices whose reasons are obvious in the moment and invisible afterward: why polling instead of a websocket, why this library over that one, why a seemingly redundant guard exists. When the reason is lost, the choice looks like an accident - and the next person "cleans it up," reintroducing the exact problem it solved.
15
+
16
+ This skill turns that tacit reasoning into two durable, co-located records.
17
+
18
+ ## Why it exists
19
+
20
+ Undocumented decisions regress along **two independent paths**, and each needs its own defense:
21
+
22
+ 1. **Deliberate migration** - someone reviews the code, sees no rationale, concludes "nobody knows why this is here," and rewrites it. Defense: a **decision log** entry that survives at the repo level.
23
+ 2. **Impulsive refactor** - someone is mid-refactor, the odd-looking line catches their eye, and they "fix" it reflexively. A repo-level log won't stop them; they're not reading it. Defense: a **comment at the implementation site** with a loud signal.
24
+
25
+ A single record covers only one path. That is why the skill insists on **both** - decision log *and* inline comment - whenever an impulsive regression is plausible.
26
+
27
+ ## When it triggers
28
+
29
+ Invoke it when a non-trivial technical choice is made during a session and phrases like these appear:
30
+
31
+ - "let's go with X" / "we'll pick" / "decision made"
32
+ - a counter-intuitive approach is adopted
33
+ - an external constraint is accepted (infra, library, third-party API)
34
+ - a workaround is introduced whose reason will be forgotten
35
+
36
+ The threshold test: *"would a developer or agent picking this up in three weeks need to know this to avoid undoing it?"* If yes, record it.
37
+
38
+ **Do not** invoke it for trivia - variable names, import order, obvious choices. Over-recording drowns the signal.
39
+
40
+ ## How it works
41
+
42
+ The skill anchors a decision in two co-located places - a repo-level log entry and a loud comment at the implementation site - because deliberate migration and impulsive refactor are independent regression paths that each need their own defense. The templates and rules below are the mechanism; the full protocol → [`SKILL.md`](SKILL.md).
43
+
44
+ ### 1. The decision log entry
45
+
46
+ Location: `docs/adr/` if the repo uses Architecture Decision Records, otherwise `.claude/decisions.md`.
47
+
48
+ ```markdown
49
+ ## YYYY-MM-DD - <Short title>
50
+ **Context**: [problem that forced the decision, ticket/branch]
51
+ **Options**: 1. A - pro/con · 2. B - pro/con
52
+ **Decision**: [choice + rationale]
53
+ **Consequences**: [code impact, workflow, re-evaluate if <condition>]
54
+ **Status**: Proposed | Accepted | Implemented | Deprecated
55
+ ```
56
+
57
+ ### 2. The implementation-site comment
58
+
59
+ Short, with a strong signal and a back-reference to the log:
60
+
61
+ ```
62
+ // Intentional 5s polling - DO NOT migrate to WebSocket:
63
+ // the LB drops idle connections >60s. See ADR-007.
64
+ ```
65
+
66
+ ### Non-negotiable rules
67
+
68
+ - Record **at the moment of the decision**, not at the end of the session - the rejected options and the exact constraint evaporate fast.
69
+ - **Never rewrite** an existing decision. Write a new one that deprecates it; the history of the reasoning is part of the value.
70
+ - Always include a **re-evaluation condition** ("revisit if the infra changes"). A decision with no expiry becomes dogma.
71
+ - A closed ticket, a chat message, or a PR description **alone** do not count - they are invisible from the code.
72
+
73
+ ## Worked example
74
+
75
+ > During a session you choose 5-second polling over a websocket because the load balancer kills idle connections after 60 seconds.
76
+
77
+ 1. Append to `.claude/decisions.md`:
78
+ ```markdown
79
+ ## 2026-07-10 - Poll every 5s instead of a websocket
80
+ **Context**: live status widget; LB drops idle connections >60s.
81
+ **Options**: 1. WebSocket - real-time, but killed by the LB · 2. 5s polling - slightly stale, survives the LB.
82
+ **Decision**: 5s polling. Simpler, resilient to the LB, staleness acceptable for this widget.
83
+ **Consequences**: extra request every 5s (negligible). Re-evaluate if the LB idle timeout is lifted.
84
+ **Status**: Accepted
85
+ ```
86
+ 2. Add the guard comment at the polling call site, referencing the entry.
87
+
88
+ ## Related artifacts
89
+
90
+ - [`bug-ticket-root-cause`](../bug-ticket-root-cause/) - for tracing a bug to fix, not a design decision.
91
+ - the Superpowers `writing-plans` skill - plans are designed up front; decisions are recorded when made.
@@ -0,0 +1,84 @@
1
+ ---
2
+ name: recording-decisions
3
+ description: Use when a non-trivial technical choice is made during a session - "let's go with X", "on choisit X", "we'll pick", "on part sur", "decision made", "décision prise", a counter-intuitive approach adopted, an external constraint accepted, a workaround whose reason will be forgotten.
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: process
8
+ ---
9
+
10
+ # Recording Decisions - capture non-obvious choices
11
+
12
+ > If the current repo has an equivalent skill (e.g. acme-app → `record-decision`), it wins - it knows where the decision log lives.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: a non-trivial technical choice is made mid-session and risks being undone out of ignorance
17
+ - **`bug-ticket-root-cause`** if: you are tracing a bug to fix, not a design decision
18
+ - **`writing-plans`** if: you are designing a full plan up front - the decision gets recorded at the moment it is made, it is not replaced by the plan
19
+
20
+ ## When to record
21
+
22
+ Threshold: **"would a developer (or agent) picking this up in three weeks need to know this to avoid undoing it?"** If yes → record.
23
+
24
+ - A choice between 2+ approaches (polling vs. websocket, lib A vs. B)
25
+ - A counter-intuitive pattern or workaround whose reason evaporates
26
+ - An accepted external constraint (infra, library, third-party API)
27
+ - A change of course versus the ticket/spec
28
+
29
+ Do not record: variable names, import order, trivial choices.
30
+
31
+ ## Double anchoring (both, not either)
32
+
33
+ Two distinct regression vectors → two protections:
34
+
35
+ 1. **Decision log** - against deliberate migration ("nobody knows why it's like this, let's change it"). Location: `docs/adr/` if the repo has one, otherwise `.claude/decisions.md`. Format:
36
+
37
+ ```markdown
38
+ ## YYYY-MM-DD - <Short title>
39
+ **Context**: [problem that forced the decision, ticket/branch]
40
+ **Options**: 1. A - pro/con · 2. B - pro/con
41
+ **Decision**: [choice + rationale]
42
+ **Consequences**: [code impact, workflow, re-evaluate if <condition>]
43
+ **Status**: Proposed | Accepted | Implemented | Deprecated
44
+ ```
45
+
46
+ 2. **Comment at the implementation site** - against the impulsive "fix" during a refactor. Short, with a strong signal and a back-reference:
47
+
48
+ ```
49
+ // Intentional 5s polling - DO NOT migrate to WebSocket:
50
+ // the LB drops idle connections >60s. See ADR-007.
51
+ ```
52
+
53
+ ## Rules
54
+
55
+ - Record **at the moment of the decision**, not at the end of the session (context evaporates)
56
+ - Never modify an existing decision - write a new one that deprecates it
57
+ - Include the re-evaluation condition ("if the infra changes…"): a decision with no expiry date becomes dogma
58
+ - Not in a closed ticket, a chat message or a PR description alone - invisible from the code in three weeks
59
+
60
+ ## Traps & rationalizations
61
+
62
+ | Excuse | Reality |
63
+ |--------|---------|
64
+ | "I'll record it at the end of the session" | The context (rejected options, exact constraint) evaporates. Record at the moment of choice. |
65
+ | "It's obvious why we do it this way" | Obvious today, a mystery in three weeks. The test: "would someone picking it up guess it without risk of undoing it?" |
66
+ | "The log is enough, no need for a comment" | The log protects against deliberate migration; the comment protects against the impulsive "fix" in a refactor. Both. |
67
+ | "I said it in the PR / chat" | Invisible from the code. Log + comment at the implementation site. |
68
+ | "I'm fixing the old decision that was wrong" | Never rewrite: write a new one that deprecates the old (the history of the reasoning matters). |
69
+
70
+ ## Exit condition
71
+
72
+ - [ ] Decision recorded at the moment it was made
73
+ - [ ] Log entry in the right place (`docs/adr/` otherwise `.claude/decisions.md`): context, options, decision, consequences, status
74
+ - [ ] Comment at the implementation site with a strong signal + back-reference (if impulsive regression is plausible)
75
+ - [ ] Explicit re-evaluation condition ("revisit if …")
76
+
77
+ ## Tooling
78
+
79
+ - No script: essentially a human decision. Inline templates above (log entry + comment).
80
+ - If the repo has a `docs/adr/` directory, follow its existing numbering and template rather than these.
81
+
82
+ ## Changelog
83
+
84
+ - 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)