ronce-racine 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +90 -0
- package/LICENSE +21 -0
- package/README.md +281 -0
- package/agents/code-reviewer.md +33 -0
- package/agents/qa-tester.md +28 -0
- package/dist/hooks/README.md +182 -0
- package/dist/hooks/bash-npm-silent.mjs +81 -0
- package/dist/hooks/session-inject.mjs +53 -0
- package/dist/hooks/session-precompact.mjs +36 -0
- package/dist/hooks/session-writer.mjs +142 -0
- package/dist/hooks/skill-reminder.mjs +89 -0
- package/dist/hooks/truncate-bash-output.mjs +46 -0
- package/dist/hooks/truncate-output.mjs +88 -0
- package/dist/hooks/worktree-env-setup.mjs +123 -0
- package/dist/install.js +962 -0
- package/docs/adopting-a-repo.md +80 -0
- package/docs/architecture.md +76 -0
- package/docs/decisions.md +72 -0
- package/docs/developing.md +143 -0
- package/docs/evaluating-skills.md +41 -0
- package/docs/git-worktrees.md +62 -0
- package/docs/rules/clean-architecture-deps.md +66 -0
- package/docs/rules/commits.md +59 -0
- package/docs/rules/detection-gap-protocol.md +55 -0
- package/docs/rules/error-handling-discipline.md +62 -0
- package/docs/rules/minimal-code.md +58 -0
- package/docs/rules/no-raw-sql-interpolation.md +57 -0
- package/docs/rules/pre-commit-secret-detection.md +54 -0
- package/docs/rules/secure-logging.md +53 -0
- package/docs/rules/sql-migrations-discipline.md +58 -0
- package/docs/rules/subscription-cleanup.md +63 -0
- package/docs/rules/test-discipline.md +66 -0
- package/docs/rules/ui-states-complete.md +52 -0
- package/docs/templates/SKILL.template.md +66 -0
- package/docs/templates/rule.template.md +16 -0
- package/docs/writing-a-rule.md +43 -0
- package/docs/writing-a-skill.md +118 -0
- package/package.json +45 -0
- package/rules/clean-architecture-deps.md +20 -0
- package/rules/commits.md +16 -0
- package/rules/detection-gap-protocol.md +35 -0
- package/rules/error-handling-discipline.md +23 -0
- package/rules/minimal-code.md +32 -0
- package/rules/no-raw-sql-interpolation.md +20 -0
- package/rules/pre-commit-secret-detection.md +14 -0
- package/rules/secure-logging.md +16 -0
- package/rules/sql-migrations-discipline.md +18 -0
- package/rules/subscription-cleanup.md +22 -0
- package/rules/test-discipline.md +20 -0
- package/rules/ui-states-complete.md +23 -0
- package/scripts/subscription-leak-scan.ts +53 -0
- package/skills/adversarial-feature-challenge/README.md +65 -0
- package/skills/adversarial-feature-challenge/SKILL.md +96 -0
- package/skills/adversarial-feature-challenge/assets/fuzz-payloads.txt +60 -0
- package/skills/adversarial-feature-challenge/templates/challenge-report.md +42 -0
- package/skills/api-contract-versioning/README.md +62 -0
- package/skills/api-contract-versioning/SKILL.md +76 -0
- package/skills/api-contract-versioning/templates/consumer-inventory.md +29 -0
- package/skills/audit-architecture/README.md +56 -0
- package/skills/audit-architecture/SKILL.md +97 -0
- package/skills/audit-architecture/reference/ar-architecture.md +275 -0
- package/skills/audit-architecture/reference/di-disponibilite.md +252 -0
- package/skills/audit-architecture/reference/im-incidents.md +217 -0
- package/skills/audit-architecture/reference/pa-pannes.md +362 -0
- package/skills/audit-architecture/reference/re-recuperation.md +300 -0
- package/skills/audit-architecture/reference/sc-scalabilite.md +173 -0
- package/skills/audit-architecture/reference/su-support.md +180 -0
- package/skills/audit-ci-cd/README.md +54 -0
- package/skills/audit-ci-cd/SKILL.md +124 -0
- package/skills/audit-ci-cd/reference/artefacts.md +39 -0
- package/skills/audit-ci-cd/reference/deploiement.md +100 -0
- package/skills/audit-ci-cd/reference/dora.md +94 -0
- package/skills/audit-ci-cd/reference/iac.md +40 -0
- package/skills/audit-ci-cd/reference/pipeline-ci.md +36 -0
- package/skills/audit-ci-cd/reference/supply-chain.md +44 -0
- package/skills/audit-compliance/README.md +69 -0
- package/skills/audit-compliance/SKILL.md +176 -0
- package/skills/audit-compliance/reference/conformite-rgpd.md +295 -0
- package/skills/audit-compliance/reference/finops.md +318 -0
- package/skills/audit-compliance/reference/gouvernance-donnees.md +238 -0
- package/skills/audit-industrialisation/README.md +53 -0
- package/skills/audit-industrialisation/SKILL.md +251 -0
- package/skills/audit-observability/README.md +64 -0
- package/skills/audit-observability/SKILL.md +134 -0
- package/skills/audit-observability/reference/alerting.md +214 -0
- package/skills/audit-observability/reference/logging.md +114 -0
- package/skills/audit-observability/reference/metriques.md +166 -0
- package/skills/audit-observability/reference/traces-dashboards.md +90 -0
- package/skills/audit-performance-frontend/README.md +91 -0
- package/skills/audit-performance-frontend/SKILL.md +194 -0
- package/skills/audit-performance-frontend/reference/assets-cache-network.md +129 -0
- package/skills/audit-performance-frontend/reference/css-rendering-pipeline.md +154 -0
- package/skills/audit-performance-frontend/reference/html-critical-path.md +128 -0
- package/skills/audit-performance-frontend/reference/js-engine-runtime.md +280 -0
- package/skills/audit-performance-frontend/reference/memory-gc.md +126 -0
- package/skills/audit-performance-frontend/reference/profiling-tooling.md +98 -0
- package/skills/audit-quality/README.md +85 -0
- package/skills/audit-quality/SKILL.md +126 -0
- package/skills/audit-quality/reference/qa-devops.md +539 -0
- package/skills/audit-quality/reference/qu-qualite-donnees.md +402 -0
- package/skills/audit-report/README.md +72 -0
- package/skills/audit-report/SKILL.md +241 -0
- package/skills/audit-report/reference/scoring-model.md +45 -0
- package/skills/audit-security/README.md +72 -0
- package/skills/audit-security/SKILL.md +140 -0
- package/skills/audit-security/reference/auth-identite.md +98 -0
- package/skills/audit-security/reference/autorisation.md +66 -0
- package/skills/audit-security/reference/chiffrement-tls.md +97 -0
- package/skills/audit-security/reference/detection-patching.md +67 -0
- package/skills/audit-security/reference/incident-response.md +98 -0
- package/skills/audit-security/reference/reseau-conteneurs.md +72 -0
- package/skills/audit-security/reference/secrets.md +36 -0
- package/skills/audit-testing/README.md +82 -0
- package/skills/audit-testing/SKILL.md +131 -0
- package/skills/audit-testing/reference/golden-dataset.md +65 -0
- package/skills/audit-testing/reference/resilience-chaos.md +93 -0
- package/skills/audit-testing/reference/tests-contractuels.md +65 -0
- package/skills/audit-testing/reference/tests-e2e-flaky.md +67 -0
- package/skills/audit-testing/reference/tests-unit-integ-ci.md +125 -0
- package/skills/bug-ticket-root-cause/README.md +67 -0
- package/skills/bug-ticket-root-cause/SKILL.md +86 -0
- package/skills/bug-ticket-root-cause/templates/bug-ticket.md +43 -0
- package/skills/bug-triage-structured/README.md +63 -0
- package/skills/bug-triage-structured/SKILL.md +104 -0
- package/skills/bug-triage-structured/templates/bug-triage.md +38 -0
- package/skills/ci-pipeline-orchestration/README.md +55 -0
- package/skills/ci-pipeline-orchestration/SKILL.md +110 -0
- package/skills/commit-readiness-review/README.md +66 -0
- package/skills/commit-readiness-review/SKILL.md +82 -0
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +81 -0
- package/skills/comprehensive-test-strategy/README.md +64 -0
- package/skills/comprehensive-test-strategy/SKILL.md +108 -0
- package/skills/comprehensive-test-strategy/reference/testing-advanced.md +85 -0
- package/skills/daily-workflow-optimization/README.md +56 -0
- package/skills/daily-workflow-optimization/SKILL.md +80 -0
- package/skills/database-schema-evolution/README.md +54 -0
- package/skills/database-schema-evolution/SKILL.md +107 -0
- package/skills/ddd-backend-implementation/README.md +63 -0
- package/skills/ddd-backend-implementation/SKILL.md +95 -0
- package/skills/design-system-component-lifecycle/README.md +56 -0
- package/skills/design-system-component-lifecycle/SKILL.md +97 -0
- package/skills/design-system-component-lifecycle/templates/component-contract.md +43 -0
- package/skills/detection-sweep/README.md +58 -0
- package/skills/detection-sweep/SKILL.md +93 -0
- package/skills/detection-sweep/scripts/sweep.ts +80 -0
- package/skills/domain-modeling-design/README.md +57 -0
- package/skills/domain-modeling-design/SKILL.md +83 -0
- package/skills/frontend-fullstack-implementation/README.md +60 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +133 -0
- package/skills/frontend-spec-call-site-audit/README.md +66 -0
- package/skills/frontend-spec-call-site-audit/SKILL.md +82 -0
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +79 -0
- package/skills/frontend-spec-call-site-audit/templates/ticket-frontend.md +32 -0
- package/skills/merge-request-review/README.md +60 -0
- package/skills/merge-request-review/SKILL.md +77 -0
- package/skills/merge-request-review/templates/mr-review-report.md +29 -0
- package/skills/production-incident-diagnostic/README.md +63 -0
- package/skills/production-incident-diagnostic/SKILL.md +103 -0
- package/skills/production-incident-diagnostic/templates/incident-report.md +33 -0
- package/skills/qa-session-intake/README.md +56 -0
- package/skills/qa-session-intake/SKILL.md +78 -0
- package/skills/recording-decisions/README.md +91 -0
- package/skills/recording-decisions/SKILL.md +84 -0
- package/skills/recurring-bug-root-cause/README.md +64 -0
- package/skills/recurring-bug-root-cause/SKILL.md +93 -0
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +46 -0
- package/skills/recurring-bug-root-cause/templates/postmortem-recidive.md +37 -0
- package/skills/refactoring-shared-component-api/README.md +50 -0
- package/skills/refactoring-shared-component-api/SKILL.md +84 -0
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +85 -0
- package/skills/refactoring-shared-component-api/templates/migration-checklist.md +19 -0
- package/skills/validating-features-end-to-end/README.md +50 -0
- package/skills/validating-features-end-to-end/SKILL.md +90 -0
- package/skills/visual-regression-check/README.md +51 -0
- package/skills/visual-regression-check/SKILL.md +89 -0
- package/skills/writing-robust-tests/README.md +53 -0
- package/skills/writing-robust-tests/SKILL.md +88 -0
- package/templates/.adopted.example +8 -0
- package/templates/anti-drift.gitlab-ci.yml +23 -0
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: comprehensive-test-strategy
|
|
3
|
+
description: Use when defining or auditing the test strategy of a module or whole project - building a coverage matrix by risk, choosing the test pyramid split, prioritizing what to test first, deciding which surfaces deserve which test level - "define the test strategy", "définis la stratégie de test", "coverage matrix by risk", "matrice de couverture". Not for writing the tests of one targeted file.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: test
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Comprehensive Test Strategy - what to test, at which level, in what order
|
|
11
|
+
|
|
12
|
+
> If the current repo has a project-specific test-strategy skill, it wins - it knows the surfaces, the commands and the project's tracker.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: "test strategy", "full coverage", "where to start", auditing/designing the strategy of a module or project, mapping the surfaces and prioritizing. Output = a **matrix** + an **ordered plan**, not test code.
|
|
17
|
+
- **`writing-robust-tests`** instead if: the target is **one specific file** whose tests must be written/hardened (ISTQB design, page object, proof of failure).
|
|
18
|
+
- **`superpowers:test-driven-development`** instead if: the code does not exist yet (test first, red-green loop on a feature).
|
|
19
|
+
- Normal flow: this skill produces the matrix + the plan → case-by-case delegation to `writing-robust-tests` or TDD.
|
|
20
|
+
|
|
21
|
+
## Principle
|
|
22
|
+
|
|
23
|
+
- **Map before executing** - every testable surface identified and classified before writing a single assertion.
|
|
24
|
+
- **Risk-based prioritization** - security, data integrity and multi-tenant isolation first; cosmetics last. The test budget goes where an incident costs the most.
|
|
25
|
+
- **Conscious level choice** - the pyramid (unit / integration-contract / E2E) is a deliberate cost/confidence trade-off, not a reflex.
|
|
26
|
+
- **A declared gap beats false coverage** - a green test that does not exercise the intended path is worse than an identified hole.
|
|
27
|
+
|
|
28
|
+
## Context to gather (before acting)
|
|
29
|
+
|
|
30
|
+
- Framework(s) + commands: read `package.json` / `Cargo.toml` / `Makefile` / `pyproject.toml` / CI config.
|
|
31
|
+
- Project surfaces: pages/screens, API endpoints (OpenAPI/routes), persisted entities and their invariants, authorization/isolation boundaries.
|
|
32
|
+
- Existing tests: locate them (`*.spec.*`, `*.test.*`, `tests/` folders), read a neighbour to copy its conventions.
|
|
33
|
+
- The current coverage baseline if any, and the thresholds (quality gates) already in place.
|
|
34
|
+
|
|
35
|
+
## Protocol
|
|
36
|
+
|
|
37
|
+
1. **Map the surfaces.** List everything testable: API routes, screens, forms, error pages (missing resource, ID from another org), business invariants, isolation boundaries. One matrix row per surface.
|
|
38
|
+
2. **Classify by risk (priority P0/P1/P2).**
|
|
39
|
+
- **P0**: authentication, authorization, multi-tenant isolation, data integrity/loss, payment. A defect here = security incident or corruption.
|
|
40
|
+
- **P1**: main business journeys, form validation (client + server), API contracts, error states.
|
|
41
|
+
- **P2**: sort/filter/pagination, empty states, cosmetics, rare low-impact cases.
|
|
42
|
+
3. **Choose the level (pyramid ~70/20/10).**
|
|
43
|
+
- **~70% unit**: pure logic, invariants, branches - fast, no I/O.
|
|
44
|
+
- **~20% integration-contract**: handlers + persistence, API contract (snapshot), authorization policies against a real database.
|
|
45
|
+
- **~10% E2E**: critical end-to-end journeys, real backend + seeded data. Expensive and slow → reserved for the highest-risk paths.
|
|
46
|
+
- Justify every placement high in the pyramid: an E2E that could have been a contract test is waste.
|
|
47
|
+
4. **Gap analysis.** For each row: `Covered` (existing test) / `Partial` (exists but misses cases) / `Absent`. Produce the `Surface · Priority · Level · State · Action` report.
|
|
48
|
+
5. **Ordered execution plan.** P0 first (blocking: create them if missing), then P1, then P2. For each planned-but-absent entry, create a follow-up ticket (via the project tracker) rather than writing everything at once.
|
|
49
|
+
6. **Delegation.** Hand each surface to cover to `writing-robust-tests` (existing code) or the TDD flow (code to write). This skill does not descend to the file level.
|
|
50
|
+
|
|
51
|
+
Copy-paste checklist:
|
|
52
|
+
```
|
|
53
|
+
- [ ] Surfaces mapped (one matrix row each)
|
|
54
|
+
- [ ] Each surface classified P0/P1/P2 by risk
|
|
55
|
+
- [ ] Test level chosen and justified (70/20/10 pyramid)
|
|
56
|
+
- [ ] Gap analysis: Covered / Partial / Absent per surface
|
|
57
|
+
- [ ] Ordered plan P0 → P1 → P2, tickets created for the absent ones
|
|
58
|
+
- [ ] Surfaces delegated to the right skill (writing-robust-tests / TDD)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Templates
|
|
62
|
+
|
|
63
|
+
Coverage matrix (header to fill in):
|
|
64
|
+
|
|
65
|
+
| Surface | Level | Framework | Priority | State | Action |
|
|
66
|
+
|---------|--------|-----------|----------|------|--------|
|
|
67
|
+
| Authentication (login/logout/refresh) | E2E + contract | (to fill in) | P0 | Partial | complete refresh |
|
|
68
|
+
| Isolation between organizations/tenants | integration + E2E | (to fill in) | P0 | Absent | create |
|
|
69
|
+
| API endpoint contract | snapshot/contract | (to fill in) | P0/P1 | … | … |
|
|
70
|
+
| Form validation (client + server) | unit + E2E | (to fill in) | P1 | … | … |
|
|
71
|
+
| Error pages (non-existent ID, resource of another tenant) | E2E | (to fill in) | P1 | … | … |
|
|
72
|
+
| Business invariants | unit | (to fill in) | P1 | … | … |
|
|
73
|
+
| Lists (sort/filter/pagination/empty state) | unit + E2E | (to fill in) | P2 | … | … |
|
|
74
|
+
|
|
75
|
+
Expected output (final summary):
|
|
76
|
+
```
|
|
77
|
+
Matrix : X surfaces identified
|
|
78
|
+
Risk : a P0 | b P1 | c P2
|
|
79
|
+
Gaps : Y absent | Z partial
|
|
80
|
+
Plan : N P0 tests to create (blocking), M P1 tests
|
|
81
|
+
Tickets: <list of follow-up tickets created>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Traps & rationalizations
|
|
85
|
+
|
|
86
|
+
| Excuse | Reality |
|
|
87
|
+
|--------|---------|
|
|
88
|
+
| "We test everything the same, we'll figure out the order later" | Without risk prioritization the budget drains into cosmetics while tenant isolation stays bare. P0 first, always. |
|
|
89
|
+
| "Let's do everything in E2E, it's the most realistic" | E2E = slow, fragile, expensive. The majority must be unit. An E2E that could have been a contract test is waste. |
|
|
90
|
+
| "Coverage is at 85%, so it's covered" | The % does not tell you whether the risky path is exercised. A test that does not break when you break the code covers nothing. |
|
|
91
|
+
| "We mock the whole API to make it stable" | An E2E with a fully-mocked API becomes a UI test: it will never catch a backend contract break. |
|
|
92
|
+
| "No time to map, I'm starting to write" | Without a matrix you test what is easy, not what is risky. The map is the output, not a preamble. |
|
|
93
|
+
|
|
94
|
+
## Exit condition
|
|
95
|
+
|
|
96
|
+
- [ ] Complete matrix: all testable surfaces listed and classified by risk.
|
|
97
|
+
- [ ] Each surface has a justified test level (roughly respecting the pyramid).
|
|
98
|
+
- [ ] Gap analysis produced (Covered / Partial / Absent) with actions.
|
|
99
|
+
- [ ] Ordered plan P0 → P1 → P2; follow-up tickets created for the absent ones.
|
|
100
|
+
- [ ] Surfaces to cover delegated to the right skill (never write the tests here).
|
|
101
|
+
|
|
102
|
+
## Tooling
|
|
103
|
+
|
|
104
|
+
- `reference/testing-advanced.md` - advanced techniques loaded on demand: quality gates, mutation testing, fuzzing, API snapshots, UAT, pyramid detail. Read it when the strategy must rely on automated safeguards.
|
|
105
|
+
|
|
106
|
+
## Changelog
|
|
107
|
+
|
|
108
|
+
- 1.0.0 (2026-06-19) - initial release, generalized from a project workflow (coverage matrix, risk prioritization, pyramid), stack/tracker coupling removed.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Advanced testing - reference
|
|
2
|
+
|
|
3
|
+
Automated safeguards to underpin a test strategy. Generic tooling: adapt the commands to the project's framework (read `package.json` / `Cargo.toml` / `Makefile` / CI config). All the stack examples below are neutral and interchangeable.
|
|
4
|
+
|
|
5
|
+
## Table of contents
|
|
6
|
+
|
|
7
|
+
1. [Test pyramid](#1-test-pyramid)
|
|
8
|
+
2. [Quality gates](#2-quality-gates)
|
|
9
|
+
3. [Mutation testing](#3-mutation-testing)
|
|
10
|
+
4. [Parser fuzzing](#4-parser-fuzzing)
|
|
11
|
+
5. [API snapshot (contract)](#5-api-snapshot-contract)
|
|
12
|
+
6. [UAT (real-condition acceptance)](#6-uat-real-condition-acceptance)
|
|
13
|
+
7. [Confidence metrics for a multi-agent flow](#7-confidence-metrics-for-a-multi-agent-flow)
|
|
14
|
+
|
|
15
|
+
## 1. Test pyramid
|
|
16
|
+
|
|
17
|
+
| Level | Target share | What it covers | Cost / speed |
|
|
18
|
+
|--------|-----------|-----------------|----------------|
|
|
19
|
+
| Unit | ~70% | pure logic, invariants, branches, boundaries | very fast, no I/O |
|
|
20
|
+
| Integration / contract | ~20% | handlers + persistence, API contract, authorization policies against a real database | medium |
|
|
21
|
+
| E2E | ~10% | critical end-to-end journeys, real backend + seeded data | slow, fragile, expensive |
|
|
22
|
+
|
|
23
|
+
Rules: moving up the pyramid must be justified; an E2E that could have been a contract test is waste. Mock only at the boundaries (external network, clock), never in the middle of the system under test - otherwise an "E2E" becomes a UI test blind to backend contract breaks.
|
|
24
|
+
|
|
25
|
+
## 2. Quality gates
|
|
26
|
+
|
|
27
|
+
Automated barrier to pass before push/merge. Typical thresholds to wire into CI:
|
|
28
|
+
|
|
29
|
+
| Gate | Typical threshold |
|
|
30
|
+
|------|---------------|
|
|
31
|
+
| Compilation + static lint | 0 warnings |
|
|
32
|
+
| Unit tests | 100% pass |
|
|
33
|
+
| Dependency audit (vulnerabilities) | 0 critical |
|
|
34
|
+
| Coverage vs baseline | ≥ -5% (no sharp regression) |
|
|
35
|
+
| Frontend typecheck + lint | 0 errors |
|
|
36
|
+
|
|
37
|
+
Keep a versioned coverage baseline and compare each run to that baseline rather than to an absolute threshold: you block a **regression**, not a historically low project.
|
|
38
|
+
|
|
39
|
+
## 3. Mutation testing
|
|
40
|
+
|
|
41
|
+
Measures whether the tests actually **detect** a defect, not just whether they pass. The tool introduces mutations (flip a condition, change a constant, remove a call) and checks that at least one test fails ("mutant killed").
|
|
42
|
+
|
|
43
|
+
- **Goal**: kill rate ≥ 70% on the critical modules.
|
|
44
|
+
- Target the at-risk (P0) modules first; full mutation testing is expensive - sample (e.g. 20%) for a fast loop.
|
|
45
|
+
- A surviving mutant points to a missing or too-permissive test → create a follow-up ticket.
|
|
46
|
+
|
|
47
|
+
Manual substitute when no tool is available: temporarily break the code under test and check that the test turns red with a readable message, then restore.
|
|
48
|
+
|
|
49
|
+
## 4. Parser fuzzing
|
|
50
|
+
|
|
51
|
+
For any code that parses untrusted input (file formats, protocols, user input), generate random/malformed inputs and look for crashes, panics or unhandled behavior.
|
|
52
|
+
|
|
53
|
+
- Prioritize parsers exposed to external input.
|
|
54
|
+
- Run in short repeated campaigns (e.g. 30–60 s/target) integrated into CI.
|
|
55
|
+
- Any input that causes a crash becomes a deterministic regression test case.
|
|
56
|
+
|
|
57
|
+
## 5. API snapshot (contract)
|
|
58
|
+
|
|
59
|
+
Freeze the shape of API responses (statuses, schema, fields) in versioned snapshots; any unintended deviation breaks the test.
|
|
60
|
+
|
|
61
|
+
- Store the snapshots in the repo, reviewed in code review like code.
|
|
62
|
+
- A snapshot update is a **deliberate contract change**, never a reflexive "update" to make the test pass.
|
|
63
|
+
- Cover at minimum: status codes, response schema, sensitive fields (presence/absence depending on authorization).
|
|
64
|
+
|
|
65
|
+
## 6. UAT (real-condition acceptance)
|
|
66
|
+
|
|
67
|
+
End-to-end scenarios run against a near-production environment, grouped by functional domain (e.g. auth/core, features, settings) and runnable in parallel.
|
|
68
|
+
|
|
69
|
+
- Parameterize the target URL and credentials via environment variables, never hard-coded.
|
|
70
|
+
- Provide a "dry run" mode (no ticket creation) to validate the harness.
|
|
71
|
+
- Output: PASS/FAIL report + screenshots; each failure generates a prioritized ticket (P0/P1/P2).
|
|
72
|
+
|
|
73
|
+
## 7. Confidence metrics for a multi-agent flow
|
|
74
|
+
|
|
75
|
+
When several agents/contributors develop in parallel, converge the work toward a common quality barrier before integration:
|
|
76
|
+
|
|
77
|
+
| Metric | Threshold | Action if failing |
|
|
78
|
+
|----------|-------|--------------|
|
|
79
|
+
| Lint warnings | 0 | block the commit |
|
|
80
|
+
| Test pass rate | 100% | block the merge |
|
|
81
|
+
| Coverage delta | ≥ -5% | block the merge |
|
|
82
|
+
| Mutation kill rate | ≥ 70% | create a test ticket |
|
|
83
|
+
| Critical vulnerabilities | 0 | block the push + alert |
|
|
84
|
+
|
|
85
|
+
Typical chain: development → quality gates → review → mutation testing → security scan → integration. Any failure sends the work back to the development step rather than bypassing the barrier.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# `daily-workflow-optimization`
|
|
2
|
+
|
|
3
|
+
> Find and cut recurring friction in the dev/agent workflow - toil loops, retry storms, cold reads, stale context - prioritized by friction × frequency, acting on tooling and process, never on production code.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `process` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | None required (uses `git log`, CI history, session transcripts; the repo's metrics tool if it has one) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`daily-workflow-optimization` is a periodic **toil review**. It looks at how the team and its agents actually work - which commands get rerun, which files get re-read every session, which tickets keep reopening - and turns that into a short, prioritized list of concrete improvements to the tooling, scripts, memories and process.
|
|
15
|
+
|
|
16
|
+
Its scope is strictly the workflow. It is not a code-quality pass and never edits production code.
|
|
17
|
+
|
|
18
|
+
## Why it exists
|
|
19
|
+
|
|
20
|
+
Friction that nobody measures **rationalizes itself away**: every individual instance feels quick, so it never gets fixed, and the cumulative cost stays invisible. This skill counters that with a simple economic lens - **friction × frequency** - so the biggest recurring drag gets addressed first, not the easiest.
|
|
21
|
+
|
|
22
|
+
It also guards against two common anti-patterns:
|
|
23
|
+
|
|
24
|
+
- **Optimizing without a signal.** Without evidence, you harden a marginal friction and miss the real one. Every action must trace back to an observed signal, never "just in case".
|
|
25
|
+
- **Automating a broken process.** Wrapping a script around a flawed step freezes the defect. Fix the process first, then automate.
|
|
26
|
+
|
|
27
|
+
## When it triggers
|
|
28
|
+
|
|
29
|
+
- Reviewing recurring workflow friction - "what's slowing us down"
|
|
30
|
+
- Periodic toil review
|
|
31
|
+
- Cutting repeated manual steps
|
|
32
|
+
- Identical recurring feedback/fixes appearing across PRs or tickets
|
|
33
|
+
- Stale memories or context that need refreshing
|
|
34
|
+
|
|
35
|
+
Route elsewhere when: you are detecting **code** problems to ticket (→ [`detection-sweep`](../detection-sweep/)); or the same **bug** keeps returning, which is a code root cause, not workflow friction (→ [`recurring-bug-root-cause`](../recurring-bug-root-cause/)).
|
|
36
|
+
|
|
37
|
+
## How it works
|
|
38
|
+
|
|
39
|
+
The skill collects friction signals from git/CI history, session transcripts, recurring tickets and stale memories, then categorizes each (toil loop, retry storm, cold read, stale context), prioritizes by friction × frequency, and decides one concrete action per item - always on tooling, process or memories, never on production code. Every action must trace back to an observed signal (no optimizing "just in case"), and a broken process is fixed before it is automated. If the repo exposes a metrics tool, it wins over manual inference.
|
|
40
|
+
|
|
41
|
+
Full step-by-step protocol (per-category actions, documentation threshold) → [`SKILL.md`](SKILL.md).
|
|
42
|
+
|
|
43
|
+
## Worked example
|
|
44
|
+
|
|
45
|
+
> Over a week on `acme-app`, you notice the agent re-reads the same `schema.ts` at the start of every session and CI shows a "fix lint" commit almost daily.
|
|
46
|
+
|
|
47
|
+
1. **Collect**: transcripts show the repeated `schema.ts` read (cold_read); git log shows the "fix lint" streak (toil_loop).
|
|
48
|
+
2. **Categorize + prioritize**: the lint streak is high frequency and low effort to fix → highest product, handled first.
|
|
49
|
+
3. **Actions**: add a pre-commit format-on-save / lint alias so lint never reaches CI (removes the toil_loop); consolidate the stable parts of `schema.ts` into a reference memory so it stops being a cold read.
|
|
50
|
+
4. **Execute** on tooling and memory only - no production code touched.
|
|
51
|
+
5. **Document** both actions with their expected effect, and run a non-regression check on the modified tooling with the output pasted.
|
|
52
|
+
|
|
53
|
+
## Related artifacts
|
|
54
|
+
|
|
55
|
+
- [`detection-sweep`](../detection-sweep/) - for finding and ticketing code problems (this skill deliberately does not touch code).
|
|
56
|
+
- [`recurring-bug-root-cause`](../recurring-bug-root-cause/) - when the recurring thing is a bug, not friction.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: daily-workflow-optimization
|
|
3
|
+
description: Use when reviewing recurring development workflow friction - "what's slowing things down", "qu'est-ce qui nous ralentit", periodic toil review, cutting repeated manual steps, identical recurring feedback/fixes, stale memories or context to refresh.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: process
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Daily Workflow Optimization - cut workflow friction, not fix code
|
|
11
|
+
|
|
12
|
+
> If the current repo has a tooled improvement command (e.g. acme-app → `daily-improve`), it wins - it knows its metrics, scripts and paths.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: optimizing the dev/agent WORKFLOW - recurring toil, retry storms, cold reads, repeated manual steps, stale memories/context. Target = tooling, scripts, memories, process. Never production code.
|
|
17
|
+
- **detection-sweep** instead if: detecting CODE problems in the project and ticketing them.
|
|
18
|
+
- **recurring-bug-root-cause** instead if: the same bug keeps coming back - that is a root cause in the code, not workflow friction.
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
Unmeasured friction rationalizes itself away ("it's quick"). The expected output = a list of concrete actions prioritized by **friction × frequency**, acting on tooling/process, with an explicit expected effect. No changes to production code, no optimization without a signal that justifies it.
|
|
23
|
+
|
|
24
|
+
## Context to gather (sources of friction signals)
|
|
25
|
+
|
|
26
|
+
No dedicated metric is required; infer friction from generic signals already available:
|
|
27
|
+
|
|
28
|
+
- **Git/CI history**: repeated fix commits on the same area, "fix lint" streaks, CI re-runs, slow or flaky jobs.
|
|
29
|
+
- **Session logs / transcripts**: same commands rerun, same files re-read without changes (cold reads), identical manual corrections.
|
|
30
|
+
- **Recurring tickets**: same-class tickets reopened, identical review feedback from one PR to the next.
|
|
31
|
+
- **Memories / context docs**: expired notes or notes with no TTL, reference files re-read every session for lack of consolidation.
|
|
32
|
+
|
|
33
|
+
If the repo exposes a measurement tool (metrics script, report), use it - it wins over manual inference.
|
|
34
|
+
|
|
35
|
+
## Protocol
|
|
36
|
+
|
|
37
|
+
1. **Collect** the signals from the sources above.
|
|
38
|
+
2. **Categorize** each signal: toil_loop (repeated command/manual step) · retry_storm (file/test/component that forces retries) · cold_read (re-read with no change) · stale_context (expired memory/doc).
|
|
39
|
+
3. **Prioritize** by friction × frequency: effort per occurrence × number of occurrences. Handle the highest product first.
|
|
40
|
+
4. **Decide one action per prioritized item**:
|
|
41
|
+
- toil_loop → helper script, alias, or rule that removes the step
|
|
42
|
+
- retry_storm → trace back to the cause (fragile test, poorly documented type) → memory or skill
|
|
43
|
+
- cold_read → consolidate into a reference doc/memory
|
|
44
|
+
- stale_context → renew the TTL or archive
|
|
45
|
+
5. **Execute** on tooling/process/memories only. Open a ticket only if the action spans multiple sessions.
|
|
46
|
+
6. **Document** if ≥ 2 actions taken: signal detected, action, expected effect.
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
- [ ] Signals collected (git/CI, sessions, tickets, memories)
|
|
50
|
+
- [ ] Items categorized + prioritized by friction × frequency
|
|
51
|
+
- [ ] Action decided for each priority item
|
|
52
|
+
- [ ] Execution on tooling/process only (zero production code)
|
|
53
|
+
- [ ] ≥ 2 actions ⇒ improvement note written
|
|
54
|
+
- [ ] Non-regression checks run on the modified tooling
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Traps & rationalizations
|
|
58
|
+
|
|
59
|
+
| Excuse | Reality |
|
|
60
|
+
|--------|---------|
|
|
61
|
+
| "It's obvious, I optimize right away" | Optimizing without measuring the signal → you harden a marginal friction and miss the real one. Collect first. |
|
|
62
|
+
| "Let's automate this step" | Automating a broken process freezes the defect. Fix the process, then automate. |
|
|
63
|
+
| "One friction, one more ticket" | Workflow frictions are handled in the session, not in the backlog. Ticket only if multi-session. |
|
|
64
|
+
| "I'll touch the production code while I'm at it" | Out of scope. This skill acts on tooling/process; a code bug → detection-sweep or recurring-bug-root-cause. |
|
|
65
|
+
| "The expired memory, I'll ignore it" | A stale note pollutes the context. Renew it or archive it, never ignore it. |
|
|
66
|
+
|
|
67
|
+
## Exit condition
|
|
68
|
+
|
|
69
|
+
- [ ] Each action taken is tied to an observed friction signal (never "just in case")
|
|
70
|
+
- [ ] Actions prioritized by friction × frequency, not by ease
|
|
71
|
+
- [ ] Zero change to production code
|
|
72
|
+
- [ ] Expected effect noted for structuring actions; non-regression check run on the tooling (output pasted)
|
|
73
|
+
|
|
74
|
+
## Tooling
|
|
75
|
+
|
|
76
|
+
- The repo's metrics tool if it exists (wins); otherwise `git log`, `git log --oneline`, CI history, session transcripts.
|
|
77
|
+
|
|
78
|
+
## Changelog
|
|
79
|
+
|
|
80
|
+
- 1.0.0 (2026-06-19) - initial version, generalized from acme-app's daily-improve workflow (metrics/scripts coupling removed)
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# `database-schema-evolution`
|
|
2
|
+
|
|
3
|
+
> Evolve a database schema with no breakage and no downtime: scan every usage first, then expand → backfill → switch → contract in separate, immutable migrations, verified from a clean state.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `process` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | Project's own migration tool + `grep -rn` for the scan (engine-agnostic) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`database-schema-evolution` is a **zero-downtime migration protocol** for the risky schema changes - renaming or reshaping a table or column, anything that touches many usages across the code. It replaces the tempting single destructive migration with the classic **expand-contract** sequence, and it front-loads an exhaustive scan so no usage is missed.
|
|
15
|
+
|
|
16
|
+
It is engine- and tool-agnostic: it tells the agent to read the project's migration config and copy a neighboring migration's conventions rather than assume a specific database or framework.
|
|
17
|
+
|
|
18
|
+
## Why it exists
|
|
19
|
+
|
|
20
|
+
Schema changes fail in three predictable ways, and this skill defends against each:
|
|
21
|
+
|
|
22
|
+
- **A forgotten usage.** A rename that updates the queries but misses a type, a seed, or an OpenAPI spec breaks at compile time or at runtime, far from the edit. Defense: an **exhaustive scan** producing an impact plan before any edit.
|
|
23
|
+
- **A destructive one-shot.** `RENAME` + `DROP` in a single migration means no rollback and guaranteed downtime while old code still reads the old name. Defense: **expand then contract, in separate migrations**, so a code rollback stays possible.
|
|
24
|
+
- **A rewritten history.** Editing an already-applied migration breaks the checksum most tools verify. Defense: **an applied migration is immutable** - fix forward with a new one.
|
|
25
|
+
|
|
26
|
+
## When it triggers
|
|
27
|
+
|
|
28
|
+
- Renaming or reshaping tables/columns
|
|
29
|
+
- A risky schema migration
|
|
30
|
+
- A change touching many usages across the code
|
|
31
|
+
- A zero-downtime requirement
|
|
32
|
+
|
|
33
|
+
Route elsewhere when: the change is about an **exposed contract** (API, events, public types) rather than the physical schema (→ [`api-contract-versioning`](../api-contract-versioning/)); or the repo has its own migration skill whose engine/tool/CI conventions take precedence.
|
|
34
|
+
|
|
35
|
+
## How it works
|
|
36
|
+
|
|
37
|
+
The approach front-loads an exhaustive `grep -rn` scan into an impact plan, then applies the classic **expand-contract** sequence across separate, immutable migrations: add the new schema (additive, nullable, idempotent), backfill the data, switch the code over, and only later drop the old schema. The whole change is verified by replaying migrations from a clean database plus typecheck and data tests on both sides.
|
|
38
|
+
|
|
39
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
40
|
+
|
|
41
|
+
## Worked example
|
|
42
|
+
|
|
43
|
+
> On `acme-app`, the column `users.name` must become `users.full_name` with zero downtime and production data present.
|
|
44
|
+
|
|
45
|
+
1. **Scan**: `grep -rn` finds `name` in 2 migrations, 5 queries, a `User` DTO, and the client types → impact plan built.
|
|
46
|
+
2. **Expand**: new migration adds a nullable `full_name` column, `IF NOT EXISTS`.
|
|
47
|
+
3. **Backfill**: `UPDATE users SET full_name = name WHERE full_name IS NULL`, re-runnable.
|
|
48
|
+
4. **Switch**: all reads/writes moved to `full_name` across the impact plan; deployed.
|
|
49
|
+
5. **Contract**: once stable, a separate migration sets `full_name NOT NULL` and drops `name`.
|
|
50
|
+
6. **Verify**: drop + recreate the local DB, replay all migrations, run typecheck and data tests green on both sides - output pasted.
|
|
51
|
+
|
|
52
|
+
## Related artifacts
|
|
53
|
+
|
|
54
|
+
- [`api-contract-versioning`](../api-contract-versioning/) - for changes to an exposed contract rather than the physical schema.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: database-schema-evolution
|
|
3
|
+
description: Use when renaming or reshaping tables/columns, when a schema migration is risky, when a schema change touches many usages across the code, or when a zero-downtime migration is required - "migrate this schema", "migre ce schéma", "rename this column", "renomme cette colonne", "zero-downtime migration".
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: process
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Database Schema Evolution - evolve a schema with no breakage or downtime
|
|
11
|
+
|
|
12
|
+
> If the current repo has a project-specific migration skill (e.g. acme-app → `bulk-db-migration`), it wins - it knows the SQL engine, the migration tool, the commands and the project's CI gates.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: renaming/reshaping a table or column, a risky schema migration, a change touching several usages across the code, a zero-downtime constraint
|
|
17
|
+
- **`api-contract-versioning`** instead if: the change is about an exposed contract (API, events, public types), not the physical database schema
|
|
18
|
+
- **The repo's migration skill** if it exists: its conventions (engine, tool, CI lint) win over this generic protocol
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
- **Exhaustive scan before any edit** - a forgotten schema usage breaks compilation, a query or the runtime down the line
|
|
23
|
+
- **Two-step expand-contract** - never a destructive change in a single migration; add the new, switch over, drop the old later
|
|
24
|
+
- **An applied migration is immutable** - fix it with a new migration, never by editing the existing one
|
|
25
|
+
|
|
26
|
+
## Context to gather (before acting)
|
|
27
|
+
|
|
28
|
+
- SQL engine and migration tool: read the config (`package.json` / `Cargo.toml` / `Makefile` / `migrations/` folder) - know how a migration is created and applied
|
|
29
|
+
- Read a neighboring migration and copy its conventions (naming, idempotence, format) before inventing
|
|
30
|
+
- Scope of usages: migrations/seeds, queries, types/DTOs mapped onto the schema, code generating or consuming those types, specs/contracts
|
|
31
|
+
- Is there data in production? (determines whether backfill and the two-step are mandatory)
|
|
32
|
+
|
|
33
|
+
## Protocol
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
- [ ] 1. Exhaustive scan of usages → impact plan
|
|
37
|
+
- [ ] 2. Expand: additive migration (new schema, nullable, idempotent)
|
|
38
|
+
- [ ] 3. Backfill / migrate the data to the new schema
|
|
39
|
+
- [ ] 4. Switch the code over to the new schema
|
|
40
|
+
- [ ] 5. Contract: separate migration dropping the old (after the switch is deployed)
|
|
41
|
+
- [ ] 6. End-to-end verification from a clean state
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### 1. Exhaustive scan (mandatory before editing)
|
|
45
|
+
|
|
46
|
+
`grep -rn` the name to evolve across: migration and seed files, application code (queries), type definitions mapped onto the schema, frontend/client code consuming those types, specs/OpenAPI. Produce an **impact plan**:
|
|
47
|
+
|
|
48
|
+
| Area | Files | Nature of usage |
|
|
49
|
+
|---|---|---|
|
|
50
|
+
| migrations / seeds | N | DDL, data |
|
|
51
|
+
| data access | N | queries |
|
|
52
|
+
| types / DTOs | N | schema mapping |
|
|
53
|
+
| client / specs | N | consumed types |
|
|
54
|
+
|
|
55
|
+
### 2. Expand - additive migration
|
|
56
|
+
|
|
57
|
+
Create a **new** migration (never edit an applied one). It only adds:
|
|
58
|
+
- a new **nullable** column or a new table, never a blocking constraint up front;
|
|
59
|
+
- idempotence: `IF NOT EXISTS` / `IF EXISTS` on every DDL operation, a conditional block if the engine supports it;
|
|
60
|
+
- a rename = **add** the new name (view, duplicated column or alias), no brutal `RENAME` while code still reads the old one.
|
|
61
|
+
|
|
62
|
+
### 3. Backfill / migrate the data
|
|
63
|
+
|
|
64
|
+
Copy the old data into the new schema (in the migration if the volume is low, otherwise a dedicated idempotent and re-runnable job). No `DROP` or `NOT NULL` at this step.
|
|
65
|
+
|
|
66
|
+
### 4. Switch the code over
|
|
67
|
+
|
|
68
|
+
Update all usages from the impact plan to read/write the new schema. On a large scope, parallelize by area (see `superpowers:dispatching-parallel-agents`).
|
|
69
|
+
|
|
70
|
+
### 5. Contract - deferred removal
|
|
71
|
+
|
|
72
|
+
A **separate** migration, after the code switch is deployed and stable: add the constraints (`NOT NULL`), drop the old column/table. Never in the same migration as the expand: a code rollback must stay possible as long as the old schema exists.
|
|
73
|
+
|
|
74
|
+
### 6. End-to-end verification
|
|
75
|
+
|
|
76
|
+
Replay all migrations **from a clean state** (drop + recreate the local database), then compile/typecheck + tests touching the data, server side and client side.
|
|
77
|
+
|
|
78
|
+
## Traps & rationalizations
|
|
79
|
+
|
|
80
|
+
| Excuse | Reality |
|
|
81
|
+
|--------|---------|
|
|
82
|
+
| "I'll fix the already-applied migration, simpler" | Most tools verify a checksum: editing an applied migration breaks the history. Create a new migration |
|
|
83
|
+
| "Rename + drop in the same migration, save time" | No rollback possible and guaranteed downtime if code still reads the old name. Expand then contract, separated |
|
|
84
|
+
| "No need for a backfill, new rows are enough" | The old data becomes invisible/inconsistent. Backfill before any constraint |
|
|
85
|
+
| "`NOT NULL` straight on a table with data" | Immediate failure or a long lock. Add nullable → backfill → `NOT NULL` in a separate migration |
|
|
86
|
+
| "The scan is long, I'll just grep the queries" | A forgotten type, seed or spec breaks down the line. Exhaustive scan of every area |
|
|
87
|
+
| "Validated locally on my existing database" | An accumulated database masks a broken migration. Replay from a clean state |
|
|
88
|
+
|
|
89
|
+
## Exit condition
|
|
90
|
+
|
|
91
|
+
- [ ] Complete impact plan: zero schema usage outside the table
|
|
92
|
+
- [ ] Expand, backfill and contract in separate, idempotent migrations
|
|
93
|
+
- [ ] No existing migration modified
|
|
94
|
+
- [ ] Migrations replayed from a clean state (output pasted)
|
|
95
|
+
- [ ] Compile/typecheck + data tests green, server and client (real output, never "it should pass")
|
|
96
|
+
- [ ] Data preserved: no `DROP`/`NOT NULL` before backfill + switch
|
|
97
|
+
|
|
98
|
+
A missing box = do not apply in production.
|
|
99
|
+
|
|
100
|
+
## Tooling
|
|
101
|
+
|
|
102
|
+
- Adapt the scan's `grep -rn` to the current project's extensions and folders
|
|
103
|
+
- Migration tool and reset command specific to the project: read the config rather than assume
|
|
104
|
+
|
|
105
|
+
## Changelog
|
|
106
|
+
|
|
107
|
+
- 1.0.0 (2026-06-19) - initial version; provider-agnostic generalization of `bulk-db-migration` (acme-app) into a zero-downtime expand-contract protocol
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# `ddd-backend-implementation`
|
|
2
|
+
|
|
3
|
+
> Build a backend feature layer by layer - domain first, edge last - so business logic stays in the aggregates and every dependency points inward.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `feature` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | None (project-specific fmt/lint/test/build) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`ddd-backend-implementation` is the *implementation* half of a two-skill pair. Once a domain model has been designed (aggregates, invariants, bounded contexts, ports), this skill governs the act of turning that model into code without letting the model rot. It fixes the **order** the layers are written in and the **direction** their dependencies may point.
|
|
15
|
+
|
|
16
|
+
The output is working, tested code across four layers - domain, application, infrastructure, handler - plus integration tests that exercise the whole path.
|
|
17
|
+
|
|
18
|
+
## Why it exists
|
|
19
|
+
|
|
20
|
+
Anemic domain models are the default failure mode of backend work. They happen when code is written outward-in: someone starts from the HTTP handler or the database table, and the "domain" ends up as a bag of getters and setters while the real rules leak into controllers, services, and repositories. From there every invariant is unguaranteed and re-duplicated at each new caller.
|
|
21
|
+
|
|
22
|
+
This skill blocks that drift with two rules that are never negotiable:
|
|
23
|
+
|
|
24
|
+
1. **Layer order** - domain → application → infrastructure → handler, each tested before the next. You cannot follow the shape of the API or the tables if you build the core first.
|
|
25
|
+
2. **Dependency direction** - everything points toward the domain. The domain imports nothing from infrastructure or the framework, so it stays testable without I/O.
|
|
26
|
+
|
|
27
|
+
## When it triggers
|
|
28
|
+
|
|
29
|
+
Invoke it while implementing a backend feature, specifically when you are:
|
|
30
|
+
|
|
31
|
+
- writing the code for a feature whose model is already settled
|
|
32
|
+
- deciding where a piece of business logic, validation, or I/O belongs
|
|
33
|
+
- enforcing the dependency direction toward the domain
|
|
34
|
+
- splitting commands from queries (CQRS)
|
|
35
|
+
|
|
36
|
+
It runs **after** `domain-modeling-design` and **during** implementation - not before. If aggregates and placement are still open questions, go design them first.
|
|
37
|
+
|
|
38
|
+
## How it works
|
|
39
|
+
|
|
40
|
+
The code is built core-outward - domain, then application, then infrastructure, then handler - each layer tested before the next, with every dependency pointing inward toward the domain. Business rules live in the aggregates; the outer layers only adapt (parse, persist, serialize). Commands and queries stay split (CQRS), ports are declared in application and implemented in infrastructure, and integration tests exercise the whole path from the edge to persistence on both the happy path and an invariant rejection.
|
|
41
|
+
|
|
42
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
43
|
+
|
|
44
|
+
### Gather context first
|
|
45
|
+
|
|
46
|
+
Before writing anything, read the project's manifest/CI for the fmt/lint/test/build commands, and read one already-implemented neighboring module - copy its layer split, naming, error handling and route wiring rather than inventing a fresh structure.
|
|
47
|
+
|
|
48
|
+
## Worked example
|
|
49
|
+
|
|
50
|
+
> You add a "cancel subscription" feature. The model (a `Subscription` aggregate with a `cancel()` transition and an invariant "cannot cancel an already-cancelled subscription") is already designed.
|
|
51
|
+
|
|
52
|
+
1. **Domain**: add `Subscription.cancel()` that flips state and rejects the double-cancel invariant in the method itself. Write pure unit tests: cancel a live subscription (ok), cancel a cancelled one (rejected). Green before moving on.
|
|
53
|
+
2. **Application**: add a `CancelSubscription` command and its handler - load the aggregate via the repo port, call `cancel()`, persist. No rule in the handler. Keep the read side (`GetSubscription` query returning a DTO) separate.
|
|
54
|
+
3. **Infrastructure**: implement the repo port against the DB with parameterized queries.
|
|
55
|
+
4. **Handler**: an endpoint that parses the subscription id, checks auth at the edge, calls the command, serializes the result.
|
|
56
|
+
5. **Integration test**: hit the endpoint on a live subscription (happy path) and on a cancelled one (invariant rejection surfaces as the right error).
|
|
57
|
+
|
|
58
|
+
Finally run fmt / lint / typecheck / build for the scope and paste the output.
|
|
59
|
+
|
|
60
|
+
## Related artifacts
|
|
61
|
+
|
|
62
|
+
- [`domain-modeling-design`](../domain-modeling-design/) - designs the model this skill implements; its spec is this skill's input.
|
|
63
|
+
- the Superpowers `test-driven-development` skill - complements this skill: it says how to write each layer (red → green) while this skill says where the code goes.
|