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,104 @@
1
+ ---
2
+ name: bug-triage-structured
3
+ description: Use when a bug needs full triage before deciding what to do with it - "reproduce and analyze this bug", "reproduis et analyse ce bug", "fix now or open a ticket?", "faut-il corriger maintenant ou ouvrir un ticket", "triage this bug", "trie ce bug", a fresh bug report where reproduction and root cause are still unknown. NOT for merely documenting an already-understood bug.
4
+ version: 1.1.0
5
+ metadata:
6
+ last-reviewed: 2026-07-21
7
+ category: bug
8
+ ---
9
+
10
+ # Structured bug triage - reproduce, understand, decide
11
+
12
+ > If the current repo has a specific triage/ticketing skill (e.g. acme-app → `add-bug`, beta-app → `jira-bug`), it wins - it knows the project's tracker, paths and commands.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: a bug arrives with no confirmed repro or known cause, and the "fix now / ticket" decision is not yet made. Covers the full cycle: repro → root-cause → decision → confirmation test.
17
+ - **`bug-ticket-root-cause`** if: the decision is already "we're not fixing now, we document". No reproduction/decision phase - just write the ticket.
18
+ - **`recurring-bug-root-cause`** if: the scope has already had **2+ similar recent fixes** → it is a class, not an isolated case; that skill requires a tooled guardrail.
19
+ - **`superpowers:systematic-debugging`** if: the repro and cause are already established and you are fixing.
20
+
21
+ ## Principle
22
+
23
+ Triage decides **before** acting: you neither fix nor open a ticket until the bug is reproduced and the cause is located. The "fix now vs ticket" decision is made on facts (mechanism + `file:line`), not on a sense of urgency. In every case the output includes a **confirmation test** that fails before and passes after - otherwise nothing proves it is resolved.
24
+
25
+ ## Context to gather (before acting)
26
+
27
+ - Project test/lint/build commands (`package.json` / `Cargo.toml` / `Makefile` / CI config) - to reproduce and to target the confirmation test
28
+ - Tracker + repo label/format conventions (project skill if one exists) - do not invent an identifier format
29
+ - Access to production code? If not, mark the cause `to investigate` without disguising it
30
+ - Bug already open? search for a duplicate in existing tickets before creating one
31
+
32
+ ## Protocol
33
+
34
+ ```
35
+ - [ ] 1. Reproduce - minimal, deterministic repro (or assumed intermittent status)
36
+ - [ ] 2. Root-cause - mechanism + file:line + introducing commit + hypothesis status
37
+ - [ ] 3. Decide - fix now OR ticket, on explicit criteria
38
+ - [ ] 4. Confirmation test - red before, green after
39
+ ```
40
+
41
+ ### 1. Reproduce
42
+ Establish a minimal, deterministic reproduction: initial state, action, observed vs expected symptom, where (page/endpoint/module), since when (commit/version). If not reproducible after reasonable effort: declare it `intermittent`, note the suspected conditions, and do not invent a cause. If too vague to locate the code: ask 2-3 targeted questions and **stop**.
43
+
44
+ ### 2. Root-cause (if code access)
45
+ - Read the real production code, trace the flow end to end (UI → state → call → handler → data)
46
+ - Git archaeology: `git log`/`git blame` on the suspect files → introducing commit
47
+ - Confront the facts: an existing test that should have failed (why didn't it?), a query, a log
48
+ - Deliverable: **mechanism** (≠ symptom) + **cited code `file:line`** + introducing commit + status (`confirmed` / `strong` / `to validate` / `to investigate`)
49
+
50
+ ### 3. Decide - fix now OR ticket
51
+ Rule on criteria, not on feeling:
52
+
53
+ | Decision | When |
54
+ |----------|------|
55
+ | **Fix now** | cause `confirmed`, localized and low-risk fix, within the current session's scope |
56
+ | **Ticket** | cause `strong`/`to validate`/`to investigate`, or a large/risky fix, or out of scope/priority, or not the right time |
57
+
58
+ When in doubt → ticket. A fix whose cause is not confirmed is a fix by trial and error.
59
+
60
+ ### 4. Confirmation test
61
+ In **both** branches, write/identify the test that materializes the bug: it must **fail before** the fix and **pass after**.
62
+ - Fix branch: add the test, see it red, fix, see it green (paste both outputs).
63
+ - Ticket branch: fill the ticket's confirmation-tests table (Type · target file · assertion · ❌ before / ✅ after) without coding the fix.
64
+
65
+ ### 5. Check for recurrence (run it, do not eyeball it)
66
+ Never skip this step: a bug that already came back is a different problem from a first-time bug, and the triage decision changes.
67
+
68
+ ```bash
69
+ git log --oneline -20 --grep="fix(<scope>)" # <scope> = the area you just triaged
70
+ ```
71
+
72
+ If the scope has already had 2+ recent fixes → apply `recurring-bug-root-cause` (tooled guardrail) instead of laying down the Nth one-line fix. State the count in the triage sheet even when it is zero, so the check is visibly done.
73
+
74
+ ## Templates
75
+
76
+ - `templates/bug-triage.md` - triage sheet: reproduction, root cause, argued decision, confirmation test (also serves as the ticket body if the decision = ticket, tracker-agnostic)
77
+
78
+ ## Traps & rationalizations
79
+
80
+ | Excuse | Reality |
81
+ |--------|---------|
82
+ | "It's obvious, I'll just fix it" | Without a repro + `file:line`, "obvious" = a hypothesis. Reproduce and locate first. |
83
+ | "I'll decide after coding the fix" | The fix/ticket decision is made on the confirmed cause, not after committing to the code. |
84
+ | "The confirmation test, I'll do it later" | Without a red-then-green test, nothing proves it's fixed. It is the heart of triage, not an option. |
85
+ | "Cause not sure but I'll try the fix" | Unconfirmed cause → ticket. A fix on an uncertain cause is trial and error. |
86
+ | "Symptom = cause" | The symptom is observed, the cause is the mechanism. Trace to the point of divergence. |
87
+
88
+ ## Exit condition
89
+
90
+ - [ ] Deterministic reproduction established (or `intermittent` status assumed with conditions noted)
91
+ - [ ] Root cause = mechanism + `file:line` (or `to investigate` for lack of code access)
92
+ - [ ] Fix/ticket decision made on explicit criteria
93
+ - [ ] Confirmation test red-before / green-after (outputs pasted if fix; table filled if ticket)
94
+ - [ ] Recurrence checked - `recurring-bug-root-cause` applied if 2+ recent fixes on the scope
95
+
96
+ ## Tooling
97
+
98
+ - `templates/bug-triage.md` - triage sheet / tracker-agnostic ticket body
99
+
100
+ ## Changelog
101
+
102
+ - 1.1.0 (2026-07-21) - recurrence check made mechanical (git log command, count stated even when zero); eval runs showed agents skipping it
103
+
104
+ - 1.0.0 (2026-06-19) - initial release: project-agnostic generalization of the add-bug workflow into full triage (repro → root-cause → decision → confirmation)
@@ -0,0 +1,38 @@
1
+ # [Bug] <short title - symptom, not solution>
2
+
3
+ ## Reproduction
4
+ **Observed**: <observed behavior>
5
+ **Expected**: <correct behavior>
6
+ **Where**: <page / endpoint / module>
7
+ **Since when**: <commit, version, date - or unknown>
8
+ **Minimal repro**: <initial state · action · result - exact steps>
9
+ **Status**: deterministic / intermittent (suspected conditions: <…>)
10
+
11
+ ## Root-cause analysis
12
+ **Code access**: yes / no - if no, cause `to investigate`, do not disguise a design hypothesis as a root cause.
13
+
14
+ **Mechanism**: <what actually happens - NOT the symptom>
15
+ **Cited code**: `file:line` - <the faulty code or the missing guard>
16
+ **Introducing commit**: `hash` (<date>) - <context>
17
+ **Hypothesis status**: confirmed / strong / to validate / to investigate
18
+ **Why the existing tests didn't catch the bug**: <honest answer>
19
+
20
+ ## Decision
21
+ **Outcome**: fix now / ticket
22
+ **Justification**: <cause status · size and risk of the fix · session scope and priority>
23
+
24
+ ## Confirmation test
25
+ | Type | Target file | Key assertion | Before fix | After fix |
26
+ |---|---|---|---|---|
27
+ | UT | | | ❌ FAIL | ✅ PASS |
28
+ | E2E | | | ❌ FAIL | ✅ PASS |
29
+
30
+ > Each test MUST fail before the fix and pass after.
31
+ > If decision = fix: paste the red-then-green outputs.
32
+ > If decision = ticket: fill the table, do not code the fix.
33
+
34
+ ## Priority
35
+ <critical: prod down, data loss, exploitable flaw · high: broken with no workaround · medium: workaround possible · low: cosmetic> - <justification>
36
+
37
+ ## Recurrence
38
+ <Section present only if the scope has 2+ recent fixes - see the recurring-bug-root-cause skill.>
@@ -0,0 +1,55 @@
1
+ # `ci-pipeline-orchestration`
2
+
3
+ > Drive a CI pipeline end-to-end after a push: read its status, diagnose failures to a cause, rerun only genuine flakes, and validate the deploy actually responds.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `process` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | The CI provider's own CLI/API (`gh run`, `glab ci`, REST) - detected per project |
11
+
12
+ ## What it is
13
+
14
+ `ci-pipeline-orchestration` is the discipline of **owning what happens after `git push`** until the change is proven live. It spans the full arc: the pipeline's job statuses, the diagnosis of any red job, the decision to fix or rerun, and the post-deploy validation that the deployed app actually answers with the right status and headers.
15
+
16
+ It is deliberately **provider-agnostic**. It does not assume GitLab, GitHub Actions, Jenkins or any single CI; it tells the agent to find the available command or config first, then act.
17
+
18
+ ## Why it exists
19
+
20
+ Two failure modes waste the most time on CI, and this skill exists to block both:
21
+
22
+ 1. **The blind rerun.** A job goes red, someone hits "retry" hoping it passes. If the failure was a real bug, the rerun masks it and burns runner minutes; if it recurs, nobody ever tracks it. The skill forces a **diagnosis-to-cause** step before any rerun, and escalates a failure seen 2+ times to a ticket.
23
+ 2. **The false green.** A pipeline turns green and everyone assumes the app is deployed and healthy. But a green build says nothing about whether the running service responds. The skill makes a **smoke test + HTTP header check** part of "done".
24
+
25
+ ## When it triggers
26
+
27
+ - After any `git push`, to check the resulting pipeline
28
+ - CI is red and the failure needs diagnosing
29
+ - Jobs need retrying
30
+ - Validating post-deploy HTTP headers or running a smoke test
31
+
32
+ Trigger phrases: "check the pipeline", "rerun CI", "the pipeline failed", "validate the headers".
33
+
34
+ Route elsewhere when: the errors are still local and **unpushed** (→ [`commit-readiness-review`](../commit-readiness-review/)); or production is broken **outside** an in-progress deploy, which is an incident (→ [`production-incident-diagnostic`](../production-incident-diagnostic/)).
35
+
36
+ ## How it works
37
+
38
+ The skill owns everything after `git push` until the change is proven live: read the pipeline status for the target commit, diagnose each red job to a *cause* rather than a symptom, then either fix-and-repush or rerun only a confirmed infra flake - never a reproducible red test. A green pipeline is not the finish line: it closes with a smoke test and an HTTP-header check on the deployed app, and escalates any failure seen 2+ times to a ticket instead of rerunning again. Manual deploy jobs always need explicit user confirmation, and `--no-verify` is never used to get past a hook.
39
+
40
+ Full step-by-step protocol (including the symptom→cause table and the exact headers to check) → [`SKILL.md`](SKILL.md).
41
+
42
+ ## Worked example
43
+
44
+ > You push a fix to `acme-app`. The pipeline goes red on the `test` job.
45
+
46
+ 1. **Status**: list runs for the pushed SHA - `build` passed, `test` failed, `deploy` is manual.
47
+ 2. **Diagnose**: read the tail of the `test` logs. The failure reproduces locally → it is a regression, not a flake.
48
+ 3. **Act**: fix the code on the branch, repush. The pipeline re-triggers and goes green.
49
+ 4. **Post-deploy**: the `deploy` job is manual - ask the user before triggering it. After deploy, `curl -I https://acme-app.example/health` returns 200 with HSTS and `nosniff` present. Smoke test passes.
50
+ 5. **Report** with the template, pasting the real header output.
51
+
52
+ ## Related artifacts
53
+
54
+ - [`commit-readiness-review`](../commit-readiness-review/) - local checks before the push that feeds the pipeline.
55
+ - [`production-incident-diagnostic`](../production-incident-diagnostic/) - prod broken outside a deploy is an incident, not this.
@@ -0,0 +1,110 @@
1
+ ---
2
+ name: ci-pipeline-orchestration
3
+ description: Use when a CI pipeline needs checking after a push, when CI is red and the failure must be diagnosed, when jobs need retrying, or when validating post-deploy HTTP headers and smoke tests. Triggers on "check the pipeline", "vérifier le pipeline", "rerun CI", "relancer CI", "the pipeline failed", "le pipeline a échoué", "validate the headers", "valider les headers", after any `git push`.
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-06-19
7
+ category: process
8
+ ---
9
+
10
+ # CI Pipeline Orchestration - drive the pipeline end-to-end after a push
11
+
12
+ > If the current repo has a project-specific pipeline skill (e.g. acme-app → `pipeline-orchestration`), it wins - it knows the CI provider, its commands and the deploy URLs.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: a push happened and the CI pipeline must be checked, diagnosed, retried, or its post-deploy validated - CI red, job reruns, HTTP header checks
17
+ - **`commit-readiness-review`** instead if: the errors are local and the code is **not pushed yet** (pre-commit checks)
18
+ - **`production-incident-diagnostic`** instead if: production is down or misbehaving outside of an in-progress deploy - that is an incident, not the pipeline
19
+
20
+ > Quick rule: red pipeline after a push → this skill; local errors before push → `commit-readiness-review`; prod broken outside a deploy → incident diagnostic.
21
+
22
+ ## Principle
23
+
24
+ - **End-to-end**: from pipeline status through post-deploy validation (HTTP headers, smoke test) - a green pipeline does not prove the app responds.
25
+ - **Diagnose before rerunning**: map the failure to a precise cause. Blind reruns mask a real bug and burn runner minutes.
26
+ - **Track the recurring**: the same failure 2+ times = a ticket, not yet another rerun.
27
+
28
+ ## Context to gather (before acting)
29
+
30
+ - **Which CI provider** and how to query it: GitLab CI, GitHub Actions, Jenkins, CircleCI… available CLI (`gh run`, `glab ci`, API), or config (`.gitlab-ci.yml`, `.github/workflows/`, `Jenkinsfile`)
31
+ - **Which commit / branch** should carry the target pipeline (the pushed SHA, not an old one)
32
+ - **CI access**: token/credentials available to read job status and logs
33
+ - **Post-deploy URL** (staging/prod) and healthcheck endpoint for validation
34
+ - Read an existing neighbor/project skill and copy its commands before inventing
35
+
36
+ ## Protocol
37
+
38
+ ```
39
+ - [ ] 1. Pipeline status of the target commit
40
+ - [ ] 2. If failed → diagnose (failed job logs) → map to a cause
41
+ - [ ] 3. Fix (push) OR targeted rerun if a genuine flake
42
+ - [ ] 4. Post-deploy: smoke test + HTTP headers
43
+ - [ ] 5. Recurring failure (2+) → ticket
44
+ ```
45
+
46
+ 1. **Current status** - list the latest pipelines/runs and fetch the job statuses for the target commit. Identify what is `passed`, `failed`, `running`, `manual`.
47
+ 2. **Diagnosis** - for each `failed` job, read the tail of the logs and map it to a **cause**, not just a symptom:
48
+
49
+ | Symptom in the logs | Likely cause → action |
50
+ |------------------------|--------------------------|
51
+ | lint/format diff | reformat + fix locally, repush |
52
+ | red test | analyze the failing test (regression vs flake) before any retry |
53
+ | build/compile error | reproduce the build locally, fix, repush |
54
+ | runner infra error / network timeout / image pull | infra flake → legitimate rerun with no code fix |
55
+ | missing secret/variable | CI config to fix, not the code |
56
+
57
+ 3. **Act**:
58
+ - **Real bug**: fix on a branch, repush - the pipeline re-triggers. No rerun without a fix.
59
+ - **Confirmed infra flake** (runner system failure, network timeout): rerun the targeted job. Document the rerun.
60
+ - **Manual deploy job**: **ask the user to confirm** before triggering it, especially toward production.
61
+ - **Never** `--no-verify` on push even if a hook fails.
62
+ 4. **Post-deploy** - a green pipeline is not enough:
63
+ - **Smoke test**: call the healthcheck / key endpoint, verify a real 2xx.
64
+ - **HTTP headers** (`curl -I <url>/health`):
65
+ - `Strict-Transport-Security` present in prod
66
+ - `X-Content-Type-Options: nosniff`
67
+ - `Cache-Control` consistent (no aggressive caching on an API)
68
+ - `Access-Control-Allow-Origin` = expected domain
69
+ - App not responding despite a green pipeline → read the deploy logs before declaring success.
70
+ 5. **Recurrence** - the same failure 2+ times → create a CI bug ticket (logs + context + criterion "the job passes on the default branch") instead of rerunning an Nth time.
71
+
72
+ ## Templates
73
+
74
+ ```
75
+ Pipeline <id> (<branch>, <sha>): <status>
76
+ - Job <a>: ✅/❌ (+ cause if ❌)
77
+ - Job <b>: ✅/❌ (+ cause if ❌)
78
+ - Smoke test: ✅/❌
79
+ - Headers: ✅/❌ (+ detail if KO)
80
+ - Action: <fix pushed | flake rerun documented | deploy validated | ticket created>
81
+ ```
82
+
83
+ ## Traps & rationalizations
84
+
85
+ | Excuse | Reality |
86
+ |--------|---------|
87
+ | "I'll rerun, maybe it passes" | Rerunning without diagnosing masks a real bug and burns runner minutes. Diagnose first |
88
+ | "It's probably a flake" | "Flake" is not a decree: a genuine flake = an identified infra error (runner, network). A reproducible red test is not a flake |
89
+ | "This job fails often, I ignore it" | An ignored recurring failure = debt that will make the pipeline useless. 2+ times → ticket |
90
+ | "Pipeline green, it's deployed" | A green job does not prove the app responds. Smoke test + headers mandatory |
91
+ | "The hook blocks the push, `--no-verify`" | The hook protects the branch. No `--no-verify` without an explicit request |
92
+ | "I'll trigger the manual deploy directly" | Manual job = user confirmation, especially toward prod |
93
+
94
+ ## Exit condition
95
+
96
+ - [ ] Target commit's pipeline `passed` or `running` (no longer `failed`)
97
+ - [ ] If a fix: commit pushed and a new pipeline triggered
98
+ - [ ] If a flake: rerun launched and result documented
99
+ - [ ] Post-deploy validated: smoke test 2xx + conformant headers (output pasted, not assumed)
100
+ - [ ] If a recurring failure (2+): ticket created
101
+
102
+ Pipeline still `failed` with no ticket and no fix = not done.
103
+
104
+ ## Tooling
105
+
106
+ - The CI provider's CLI depending on the project (`gh run view/rerun`, `glab ci`, REST API) - spot the available command before acting, do not hardcode a single provider.
107
+
108
+ ## Changelog
109
+
110
+ - 1.0.0 (2026-06-19) - initial version, derived from a project workflow and decoupled from the CI provider
@@ -0,0 +1,66 @@
1
+ # `commit-readiness-review`
2
+
3
+ > A pre-commit self-review that scans for secrets, runs the right per-stack checks, catches debug leftovers, and stages file by file - before the commit, never after.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (on-demand workflow) |
8
+ | **Category** | `process` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Tooling** | [`scripts/precommit-scan.ts`](scripts/precommit-scan.ts) (read-only staged-diff scanner) |
11
+
12
+ ## What it is
13
+
14
+ `commit-readiness-review` is the gate an agent runs on itself right before any Claude-initiated `git commit`. It turns "commit that" into a short, ordered checklist: map the diff, scan for secrets, run format/lint/typecheck/targeted tests per touched stack, catch forbidden patterns, stage each file deliberately, then summarize and ask for confirmation.
15
+
16
+ It is generic on purpose. If the current repo has its own pre-commit skill with exact commands, that one wins - this is the baseline when none exists.
17
+
18
+ ## Why it exists
19
+
20
+ A commit is cheap to make and expensive to unmake. Two costs dominate:
21
+
22
+ - **A leaked secret.** Once a key, token or private key is pushed, the fix is not a `revert` - it is a **credential rotation plus a history purge**. The skill treats any secret detection as a hard STOP, no matter the time pressure, because "just for debugging" still leaks.
23
+ - **A broken or dirty commit.** Skipping the lint "because we're in a hurry" ships red pipelines, debug `console.log`s, hardcoded waits, and disabled tests. The skill's stance is that **time pressure does not change the checklist** - and that a green check means *executed with pasted output*, never assumed.
24
+
25
+ Staging file by file (never blind `git add -A`) is part of the same defense: it keeps `.env`, build artifacts, and unrelated changes out of the commit.
26
+
27
+ ## When it triggers
28
+
29
+ - Any agent-initiated commit is imminent - "ready to commit", "commit that", "quick commit"
30
+ - Time pressure to ship
31
+ - A diff containing test/debug leftovers, or touching multiple stacks
32
+
33
+ Route elsewhere when: the question is "does it actually work" (functional proof) rather than "is it committable" (→ [`validating-features-end-to-end`](../validating-features-end-to-end/)); or the repo has its own git skill whose branch/message/tracker conventions take precedence.
34
+
35
+ ## How it works
36
+
37
+ The skill turns "commit that" into an ordered gate the agent runs on itself before any commit: map the diff and STOP on at-risk files, scan for secrets (gitleaks or a regex fallback), run format → lint → typecheck → targeted tests per touched stack, catch forbidden patterns (debug leftovers, hardcoded waits, disabled tests), stage each file deliberately rather than `git add -A`, then summarize and ask for confirmation. Any secret detection is a hard STOP, and time pressure never shortens the checklist - a green check means executed with pasted output, never assumed.
38
+
39
+ Full step-by-step protocol (exact commands, grep patterns, traps) → [`SKILL.md`](SKILL.md).
40
+
41
+ ### The scanner
42
+
43
+ [`scripts/precommit-scan.ts`](scripts/precommit-scan.ts) automates steps 2 and 4:
44
+
45
+ ```bash
46
+ npx tsx scripts/precommit-scan.ts # scans git diff --cached
47
+ npx tsx scripts/precommit-scan.ts --all # also scans the unstaged tree
48
+ ```
49
+
50
+ It uses gitleaks when installed and falls back to a regex otherwise, flags staged sensitive files, and reports debug leftovers. It is read-only and exits 1 on a secret or sensitive file (debug hits are non-blocking, left to human judgment). It can be wired as a hook - see [`hooks/`](../../hooks/).
51
+
52
+ ## Worked example
53
+
54
+ > You ask the agent to commit a change to `acme-app` that touches a TypeScript service and a SQL migration.
55
+
56
+ 1. `git diff --stat` shows two stacks; no `.env` in scope.
57
+ 2. `precommit-scan.ts` is clean on secrets but flags a leftover `console.log` in the service.
58
+ 3. The agent removes the log, then runs the TS format/lint/typecheck and the targeted service test - all green, output pasted.
59
+ 4. Files are staged one by one; the migration and the service file both belong to the change.
60
+ 5. The agent proposes `fix(billing): correct proration rounding` and asks for confirmation before committing.
61
+
62
+ ## Related artifacts
63
+
64
+ - [`validating-features-end-to-end`](../validating-features-end-to-end/) - for "does it work", the functional proof this skill does not provide.
65
+ - [`ci-pipeline-orchestration`](../ci-pipeline-orchestration/) - takes over once the commit is pushed and the pipeline runs.
66
+ - Rule [`pre-commit-secret-detection`](../../rules/pre-commit-secret-detection.md) - the always-on policy behind the secret-scan step.
@@ -0,0 +1,82 @@
1
+ ---
2
+ name: commit-readiness-review
3
+ description: Use before any Claude-initiated git commit - "ready to commit", "commit that", "quick commit", "prêt à commit", "commit ça", "vite un commit", time pressure to ship, diff containing test/debug leftovers or touching multiple stacks.
4
+ version: 1.0.1
5
+ metadata:
6
+ last-reviewed: 2026-07-20
7
+ category: process
8
+ ---
9
+
10
+ # Commit Readiness Review - self-review before committing
11
+
12
+ > If the current repo has a project-specific pre-commit skill (e.g. acme-app → `pre-commit-self-review`), it wins - it knows the exact commands.
13
+
14
+ ## This skill vs. others
15
+
16
+ - **This skill** when: an agent-initiated commit is imminent - "commit that", "ready to commit", a diff with debug leftovers or touching several stacks, time pressure
17
+ - **`validating-features-end-to-end`** instead if: the question is "does it work" (functional proof), not "is it committable"
18
+ - **The repo's git skill** if it exists: the project's branch/message/tracker conventions win over this generic checklist
19
+
20
+ ## Context to gather (before acting)
21
+
22
+ - `git status` + `git diff --stat`: real scope, stacks touched, at-risk files
23
+ - Per-stack format/lint/typecheck/test commands (`package.json` / `Makefile` / CI config)
24
+ - The repo's message format: `git log --oneline -5`
25
+ - The associated ticket (number to put in `Closes #` if the convention requires it)
26
+
27
+ ## Principle
28
+
29
+ - **Before the commit, never after** - no catch-up via `--amend` once pushed
30
+ - **Time pressure does not change the checklist** - a committed secret costs a key rotation + history purge, not a revert
31
+ - Targeted scope: check what changed, not the whole suite
32
+
33
+ ## Workflow
34
+
35
+ 1. **Map the diff**: `git status` + `git diff --stat`. Identify the stacks touched (each extension → its checks) and at-risk files (`.env`, `*.pem`, `*.key`, credentials) → immediate STOP if present.
36
+ 2. **Secret scan** on the content. Two levels:
37
+ - **Dedicated tool if available** (preferred, fewer false negatives): `gitleaks protect --staged --redact` on the staged diff, or `gitleaks detect --no-git --redact` on the tree. If it is not installed, do not block on it - fall back to the grep below.
38
+ - **Fallback grep**: `git diff HEAD | grep -iE "(password|api[_-]?key|secret|token|sk_live|ghp_|glpat-|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----)\s*[:=]?"` plus at-risk files `git diff --name-only HEAD | grep -iE "\.env|\.pem|\.key|credentials|secret"`.
39
+ - Any detection = show the line to the user and wait for their decision. "It's just for debugging" is not an exception. False positive: exclude it ad hoc with a `gitleaks:allow` comment on the line, or systemically via the allowlist of a repo-level `.gitleaks.toml` config - never by loosening the global scan.
40
+ - **Tooling details and post-leak procedure**: see `rules/pre-commit-secret-detection.md` for gitleaks install, pre-commit hook, allowlist and the rotation procedure if a secret is already pushed.
41
+ 3. **Per touched stack, in order format → lint → typecheck → targeted tests** (commands: `package.json` scripts, `Makefile`, repo conventions). Test the changed scope only; the full suite is for before push.
42
+ 4. **Problematic patterns in the diff** (added lines only):
43
+ - hardcoded waits in tests (`waitForTimeout`, `sleep`)
44
+ - debug leftovers (`console.log`, `print(`, `dbg!`, `debugger`)
45
+ - `TODO`/`FIXME` added → track in a ticket or remove
46
+ - disabled tests (`.skip`, `xit`, `#[ignore]`) with no justification
47
+ 5. **Stage file by file** - never a blind `git add -A`/`git add .`. Verify each staged file belongs to the change.
48
+ 6. **Summary + confirmation**: files, check results (real ✅/❌, not assumed), proposed message in the repo format (`git log --oneline -5` for the format). Ask for confirmation before `git commit` unless an autonomous mode is explicitly active.
49
+
50
+ ## Traps & rationalizations
51
+
52
+ | Excuse | Reality |
53
+ |--------|---------|
54
+ | "It's just for debugging, I'll commit the secret for 2 min" | A pushed secret = key rotation + history purge. No exception |
55
+ | "We're in a hurry, I'll skip the lint" | Pressure does not change the checklist. A rushed broken commit costs more |
56
+ | "`git add -A` is faster" | Blind staging pulls in `.env`, builds, files from other changes. File by file |
57
+ | "`--no-verify` to get past the hook" | The hook protects the branch. No `--no-verify` without an explicit user request |
58
+ | "The checks will probably pass" | ✅ = executed with pasted output, never assumed |
59
+ | "I'll fix it with `--amend` after the push" | No `--amend` on a pushed commit. Verify beforehand |
60
+
61
+ ## Exit condition
62
+
63
+ - [ ] Format/lint/typecheck green on each touched stack (real output)
64
+ - [ ] Targeted tests of the changed scope passed
65
+ - [ ] Zero secret / sensitive file in the diff
66
+ - [ ] Zero forbidden pattern (debug, hardcoded wait, disabled test, TODO) or explicitly justified
67
+ - [ ] Files staged one by one, all legitimate
68
+ - [ ] Message in the repo format + user confirmation obtained (unless autonomous mode)
69
+
70
+ A missing box = no commit.
71
+
72
+ ## Tooling
73
+
74
+ - Test procedure: `scripts/precommit-scan.test.ts` - deterministic behavioral test of the script (positive + negative fixture). Run `npx tsx scripts/precommit-scan.test.ts` from the canonical repo after any change to the script (also picked up by `npm test`). Not distributed to target repos.
75
+
76
+ - `scripts/precommit-scan.ts` - scans the staged diff (`npx tsx scripts/precommit-scan.ts`): secrets via gitleaks or regex fallback, sensitive files, debug leftovers. Read-only, exit 1 on a secret/sensitive file. Wireable as a hook (see `hooks/`).
77
+
78
+ ## Changelog
79
+
80
+ - 1.0.1 (2026-07-20) - co-located test procedure for precommit-scan.ts (scripts/precommit-scan.test.ts)
81
+
82
+ - 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
@@ -0,0 +1,81 @@
1
+ #!/usr/bin/env -S npx tsx
2
+ /**
3
+ * Scan the staged diff before commit: secrets, sensitive files, debug leftovers.
4
+ * Read-only. Paired with the commit-readiness-review skill (step 2 "secret scan" + step 4 "patterns").
5
+ *
6
+ * npx tsx precommit-scan.ts # scans `git diff --cached`
7
+ * npx tsx precommit-scan.ts --all # also scans the unstaged tree (git diff)
8
+ *
9
+ * Exit 1 if at least one staged secret or sensitive file; 0 otherwise
10
+ * (debug patterns are reported but non-blocking - human decision).
11
+ */
12
+ import { execSync } from "node:child_process";
13
+
14
+ const all = process.argv.includes("--all");
15
+ const range = all ? "HEAD" : "--cached";
16
+
17
+ function sh(cmd: string): string {
18
+ try {
19
+ return execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
20
+ } catch (e) {
21
+ return (e as { stdout?: string }).stdout ?? "";
22
+ }
23
+ }
24
+ function installed(bin: string): boolean {
25
+ try {
26
+ execSync(`command -v ${bin}`, { stdio: "ignore" });
27
+ return true;
28
+ } catch {
29
+ return false;
30
+ }
31
+ }
32
+
33
+ const addedLines = sh(`git diff ${range} -U0`)
34
+ .split("\n")
35
+ .filter((l) => l.startsWith("+") && !l.startsWith("+++"));
36
+
37
+ // Secrets: gitleaks first (widest coverage), otherwise grep fallback.
38
+ let secretHits = 0;
39
+ if (installed("gitleaks")) {
40
+ try {
41
+ execSync("gitleaks protect --staged --no-banner", { stdio: "ignore" });
42
+ } catch {
43
+ console.log("✗ SECRET - gitleaks detected a staged secret. Detail: gitleaks protect --staged --verbose");
44
+ secretHits = 1;
45
+ }
46
+ } else {
47
+ const secretRe =
48
+ /AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|sk_live_[0-9a-zA-Z]+|glpat-[0-9a-zA-Z_-]{20}|ghp_[0-9a-zA-Z]{36}|(password|secret|api[_-]?key|token)\s*[:=]\s*\S/i;
49
+ const hits = addedLines.filter((l) => secretRe.test(l));
50
+ if (hits.length) {
51
+ console.log("✗ Potential SECRET (grep fallback - install gitleaks for reliability):");
52
+ hits.forEach((l) => console.log(" " + l));
53
+ secretHits = 1;
54
+ }
55
+ }
56
+
57
+ // Sensitive files added to the staging area.
58
+ const sensitive = sh("git diff --cached --name-only")
59
+ .split("\n")
60
+ .filter((f) => /(^|\/)\.env($|\.)|\.pem$|\.key$|id_rsa|credentials/i.test(f));
61
+ let sensitiveHits = 0;
62
+ if (sensitive.length) {
63
+ console.log("✗ SENSITIVE FILE staged:");
64
+ sensitive.forEach((f) => console.log(" " + f));
65
+ sensitiveHits = 1;
66
+ }
67
+
68
+ // Debug leftovers in the added lines (non-blocking).
69
+ const debugRe =
70
+ /console\.(log|debug)|debugger;|dbg!\(|[^a-zA-Z]print\(|System\.out\.print|fmt\.Print|var_dump|binding\.pry/;
71
+ const dbg = addedLines.filter((l) => debugRe.test(l));
72
+ if (dbg.length) {
73
+ console.log("⚠ DEBUG - potential leftovers (check, remove if unwanted):");
74
+ dbg.forEach((l) => console.log(" " + l));
75
+ }
76
+
77
+ if (secretHits + sensitiveHits > 0) {
78
+ console.log("→ Blocking: remove the secret/sensitive file before committing.");
79
+ process.exit(1);
80
+ }
81
+ console.log("✓ No secret or sensitive file in the staged scope.");
@@ -0,0 +1,64 @@
1
+ # `comprehensive-test-strategy`
2
+
3
+ > Decide what to test, at which level, and in what order - a risk-ranked coverage matrix and an ordered plan for a module or a whole project, before a single assertion is written.
4
+
5
+ | | |
6
+ |---|---|
7
+ | **Type** | Skill (planning workflow) |
8
+ | **Category** | `test` |
9
+ | **Artifact** | [`SKILL.md`](SKILL.md) |
10
+ | **Reference** | [`reference/testing-advanced.md`](reference/testing-advanced.md) (progressive disclosure) |
11
+ | **Tooling** | None (analysis + delegation; inline matrix template) |
12
+
13
+ ## What it is
14
+
15
+ `comprehensive-test-strategy` is a **planning** discipline, not a test-writing one. Its output is a **coverage matrix** (one row per testable surface) and an **ordered execution plan** - never test code. It maps every surface a system exposes, ranks each by risk, assigns a test level from the pyramid, marks whether it is Covered / Partial / Absent, and hands the work off to the skills that actually write tests.
16
+
17
+ ## Why it exists
18
+
19
+ Left to instinct, teams test **what is easy, not what is risky**: cosmetics get covered while multi-tenant isolation stays bare, and an 85%-coverage badge hides the fact that the dangerous path is never exercised. This skill forces four commitments:
20
+
21
+ - **Map before executing** - the matrix is the deliverable, not a warm-up.
22
+ - **Risk-based budget** - security, data integrity and tenant isolation (P0) come before empty states and pagination (P2).
23
+ - **Conscious level choice** - the ~70/20/10 pyramid is a cost/confidence trade-off; an E2E that could have been a contract test is waste.
24
+ - **A declared gap beats false coverage** - a green test that does not exercise the intended path is worse than an identified hole.
25
+
26
+ ## When it triggers
27
+
28
+ Invoke it for "test strategy", "full coverage", "where to start" - auditing or designing the strategy of a module or project, mapping surfaces and prioritizing.
29
+
30
+ - Use **`writing-robust-tests`** instead when the target is **one specific file** to write/harden.
31
+ - Use **`superpowers:test-driven-development`** instead when the code does not exist yet (test-first, red-green).
32
+ - Normal flow: this skill produces the matrix + plan, then delegates surface by surface to `writing-robust-tests` or TDD.
33
+
34
+ ## How it works
35
+
36
+ The skill maps every surface a system exposes, ranks each by risk (P0 security/isolation/data-loss → P2 cosmetics), assigns a level from the ~70/20/10 pyramid, and marks it Covered / Partial / Absent - producing a coverage matrix and an ordered P0→P1→P2 plan, never test code. Each surface is then delegated to `writing-robust-tests` or TDD; a declared gap always beats false coverage, and the skill never descends to the file level itself.
37
+
38
+ Full step-by-step protocol (risk tiers, pyramid budget, delegation) → [`SKILL.md`](SKILL.md).
39
+
40
+ ### Coverage matrix (template)
41
+
42
+ | Surface | Level | Framework | Priority | State | Action |
43
+ |---------|--------|-----------|----------|------|--------|
44
+ | Authentication (login/logout/refresh) | E2E + contract | (fill in) | P0 | Partial | complete refresh |
45
+ | Isolation between organizations/tenants | integration + E2E | (fill in) | P0 | Absent | create |
46
+ | API endpoint contract | snapshot/contract | (fill in) | P0/P1 | … | … |
47
+
48
+ When the strategy needs automated safeguards, load [`reference/testing-advanced.md`](reference/testing-advanced.md): quality gates, mutation testing, parser fuzzing, API snapshots, UAT, and multi-agent confidence metrics.
49
+
50
+ ## Worked example
51
+
52
+ > `acme-app` is a multi-tenant SaaS at 85% line coverage; a leadership request asks "are we actually safe?"
53
+
54
+ 1. Mapping surfaces reveals a **P0** row "Isolation between organizations" that is **Absent** - the 85% never touched it.
55
+ 2. It is placed at integration + E2E level and put **first** in the ordered plan as blocking.
56
+ 3. Form validation (P1) is Partial (client only, server missing) → action: add server-side contract tests.
57
+ 4. Pagination and empty states (P2) are deferred. A follow-up ticket is opened for each absent surface, then the isolation row is delegated to `writing-robust-tests`.
58
+
59
+ The output is a matrix + plan, not the tests themselves.
60
+
61
+ ## Related artifacts
62
+
63
+ - [`writing-robust-tests`](../writing-robust-tests/) - writes/hardens the tests for a single file once this skill has prioritized it.
64
+ - the Superpowers `test-driven-development` skill - the red-green loop for code that does not exist yet.