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,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ddd-backend-implementation
|
|
3
|
+
description: Use when implementing a backend feature in DDD layers, deciding where business logic / validation / I-O belongs during implementation, respecting the dependency direction toward the domain, or splitting commands from queries (CQRS). Use AFTER the model is designed, DURING implementation - "implement this backend feature", "implémente cette feature backend", "code these DDD layers", "implémente les couches DDD".
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: feature
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# DDD Backend Implementation - build a feature layer by layer
|
|
11
|
+
|
|
12
|
+
> If the current repo has a specific implementation skill (e.g. acme-app → `feature-implementation-rust-axum`), it wins - it knows the stack, the paths and the project commands.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: the model is settled and you write the code layer by layer (domain → application → infrastructure → handler)
|
|
17
|
+
- **`domain-modeling-design`** instead if: aggregates, invariants and placement are not decided yet (upstream of this skill - its output is this skill's input)
|
|
18
|
+
- **`superpowers:test-driven-development`** as a complement: this skill says *where* the code goes and in what order; TDD says *how* to write each layer (red test → green)
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
The implementation respects two non-negotiable constraints: **the order of the layers** (from the core outward) and **the direction of dependencies** (everything points toward the domain, never the reverse). The domain knows nothing of the database, the network, or the web framework. Business logic lives in the aggregates; the outer layers only adapt (parse, persist, serialize). Short-circuiting the order or inverting a dependency produces an anemic model with logic scattered around.
|
|
23
|
+
|
|
24
|
+
## Context to gather (before acting)
|
|
25
|
+
|
|
26
|
+
- Framework + commands: read `package.json` / `Cargo.toml` / `pom.xml` / `Makefile` / CI config for fmt, lint, test, build
|
|
27
|
+
- Read **one already-implemented neighboring module** in the same context and copy its structure (layer split, naming, error handling, route wiring) before inventing anything
|
|
28
|
+
- The architecture in place: where domain / application / infrastructure / API live; how ports are declared and injected (DI, application state)
|
|
29
|
+
- The spec produced by the design phase (aggregates, invariants, commands/queries, ports, events) - if missing, go back to `domain-modeling-design`
|
|
30
|
+
|
|
31
|
+
## Protocol
|
|
32
|
+
|
|
33
|
+
Implement in this order, never the reverse, never a short-circuit. Test each layer before moving to the next.
|
|
34
|
+
|
|
35
|
+
1. **Domain** - aggregate + invariants
|
|
36
|
+
- Value object for every constrained field, never a bare primitive; validate the constraint at construction
|
|
37
|
+
- Invariants validated in the aggregate's **constructor / methods**, nowhere else
|
|
38
|
+
- Methods = domain verbs (transitions, decisions), not getters/setters
|
|
39
|
+
- The domain imports **nothing** from infrastructure or the framework. Pure domain tests, no I/O
|
|
40
|
+
2. **Application** - CQRS + ports
|
|
41
|
+
- Separate **commands** (mutations) and **queries** (reads); a query does not mutate state
|
|
42
|
+
- Define the **ports** (interfaces) here, on the application/domain side; not their implementation
|
|
43
|
+
- A command handler orchestrates: load the aggregate, call its methods, persist through the port - no business rule here
|
|
44
|
+
- Queries return read DTOs, not the domain aggregate
|
|
45
|
+
3. **Infrastructure** - adapters
|
|
46
|
+
- Implement the ports declared in application (repos, network clients, queues)
|
|
47
|
+
- This is the **only** layer that depends on the concrete technology (DB, ORM, queries). Parameterized queries, never string concatenation (injection)
|
|
48
|
+
- Infrastructure depends on domain/application, never the reverse
|
|
49
|
+
4. **Handler / API** - the edge
|
|
50
|
+
- The handler **parses input → calls the command/query → serializes output**. Nothing else
|
|
51
|
+
- Authn/authz and multi-tenancy handled at the edge (extractor / middleware), not in the domain
|
|
52
|
+
- Document the exposed contract (OpenAPI/IDL schema) if the project generates one
|
|
53
|
+
5. **Integration tests** - from the edge down to persistence, on the happy path + at least one invariant rejection
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
- [ ] Domain: aggregate + value objects + invariants, pure tests green
|
|
57
|
+
- [ ] Application: command/query + ports, handler with no business logic
|
|
58
|
+
- [ ] Infrastructure: port adapters, parameterized queries
|
|
59
|
+
- [ ] Handler: parse → CQRS → serialize, auth at the edge
|
|
60
|
+
- [ ] Dependency direction verified: everything points toward the domain
|
|
61
|
+
- [ ] Integration tests happy path + invariant rejection
|
|
62
|
+
- [ ] fmt / lint / typecheck / build of the scope green
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Templates
|
|
66
|
+
|
|
67
|
+
- No fixed template: copy the structure of a neighboring module in the project (local reference code beats a generic skeleton).
|
|
68
|
+
|
|
69
|
+
## Traps & rationalizations
|
|
70
|
+
|
|
71
|
+
| Excuse | Reality |
|
|
72
|
+
|--------|---------|
|
|
73
|
+
| "Just a small validation in the handler, it's faster" | Business logic outside the domain = an unguaranteed invariant, duplicated at the next caller. It lives in the aggregate. |
|
|
74
|
+
| "I put the rule in the repo/infra, I'm already there" | Infrastructure is a replaceable adapter; a rule living there disappears if the tech changes and is untestable without I/O. |
|
|
75
|
+
| "The domain just imports the DB client to go faster" | Domain → infra dependency: the core becomes untestable and coupled to the framework. The domain depends on nothing external. |
|
|
76
|
+
| "I create the structures, the logic will follow" | Anemic model: bags of getters/setters, logic scattered across services. The aggregate carries its rules. |
|
|
77
|
+
| "I code the handler first, I'll work up toward the domain" | The reverse order makes you follow the shape of the API or the tables, not the domain. Domain → application → infra → handler. |
|
|
78
|
+
| "Command and query are the same path, I'll share it" | Reads and writes have different constraints; merging them makes you mutate on a read path and complicates both. |
|
|
79
|
+
|
|
80
|
+
## Exit condition
|
|
81
|
+
|
|
82
|
+
- [ ] All 4 layers exist in order, each tested before the next
|
|
83
|
+
- [ ] No business logic outside the domain (neither handler nor infra)
|
|
84
|
+
- [ ] Dependency direction respected: domain independent of infra and framework
|
|
85
|
+
- [ ] Commands and queries separated; ports in application, implementations in infra
|
|
86
|
+
- [ ] Integration tests green: happy path + at least one invariant rejection
|
|
87
|
+
- [ ] fmt / lint / typecheck / build of the scope run, output pasted - never "it should pass"
|
|
88
|
+
|
|
89
|
+
## Tooling
|
|
90
|
+
|
|
91
|
+
- No generic script: the commands (fmt, lint, test, build) depend on the project, to be read from its manifest / CI config.
|
|
92
|
+
|
|
93
|
+
## Changelog
|
|
94
|
+
|
|
95
|
+
- 1.0.0 (2026-06-19) - initial generic version extracted from a project workflow, decoupled from any stack and any tracker
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# `design-system-component-lifecycle`
|
|
2
|
+
|
|
3
|
+
> A design system component is a file *plus* its enforcement - create it, migrate every raw call site, and make the raw pattern a lint error, or it stays decorative.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `frontend` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | [`templates/component-contract.md`](templates/component-contract.md) (stack-specific grep/lint) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`design-system-component-lifecycle` governs the full life of a shared UI component: the **decision** to create it, the **contract** that defines its API, and - the part that usually gets skipped - the **enforcement** that keeps the raw pattern it replaces from creeping back in. It treats "add a component" as a four-step batch, not a single file drop.
|
|
15
|
+
|
|
16
|
+
## Why it exists
|
|
17
|
+
|
|
18
|
+
Design systems decay in a predictable way. Someone builds a proper component, migrates the one call site that prompted it, and moves on. The raw pattern (an inline `<input>` with hardcoded styles, a bespoke card, a literal `#3b82f6`) is still legal everywhere else, so the next person copies it again. The DS component becomes decorative - one blessed usage surrounded by duplicated one-offs, exactly the mess it was meant to end.
|
|
19
|
+
|
|
20
|
+
The fix is to make the raw pattern **impossible to reintroduce silently**. That requires three synchronized layers of enforcement, and a component isn't "done" until all three exist.
|
|
21
|
+
|
|
22
|
+
## When it triggers
|
|
23
|
+
|
|
24
|
+
Invoke it when you are:
|
|
25
|
+
|
|
26
|
+
- creating a new DS component or adding a variant
|
|
27
|
+
- covering a repeated raw element/pattern with a reusable component
|
|
28
|
+
- defining a reusable component contract (props/slots/events, tokens)
|
|
29
|
+
- enforcing token usage over hardcoded values
|
|
30
|
+
- reacting to "add a component", "we need a component for", or an element repeated across pages
|
|
31
|
+
|
|
32
|
+
Use `refactoring-shared-component-api` instead when the component already exists and you are only changing its API. Use `frontend-spec-call-site-audit` upstream when you are specifying a feature that merely *consumes* the DS.
|
|
33
|
+
|
|
34
|
+
## How it works
|
|
35
|
+
|
|
36
|
+
Adding a component is treated as a four-step batch, not a file drop: a **decision** (no existing DS component or external primitive already covers the need; atom vs molecule), a **contract** (two-way API, state props, tokens instead of hardcoded values, pass-through `testid`), **implementation + migration** of every raw call site until its grep drops to 0, and **enforcement** across three synchronized layers - doc (DS index mapping), lint (raw pattern becomes an error), and test (unit + runtime audit). Enforcement is the part that usually gets skipped and the reason a component stays decorative without it.
|
|
37
|
+
|
|
38
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
39
|
+
|
|
40
|
+
The [`component-contract.md`](templates/component-contract.md) template gives you a fill-in-the-blanks form covering the decision, API table, token mapping, testid, call-site list, and the enforcement checklist.
|
|
41
|
+
|
|
42
|
+
## Worked example
|
|
43
|
+
|
|
44
|
+
> Three pages each hand-roll a labelled text field: a bare `<input>` with an adjacent `<label>` and inline `padding: 8px; border: 1px solid #ccc`.
|
|
45
|
+
|
|
46
|
+
1. **Decision**: the DS has no field component and the external lib only ships an unstyled `<input>`. This is an atom, named per the project prefix. `grep` finds the pattern in 3 files.
|
|
47
|
+
2. **Contract**: fill the template - value + update event (two-way), `label`/`hint`/`error`/`disabled`/`required`, `size` variant, all styling via tokens (spacing token instead of `8px`, border/color tokens instead of `#ccc`), `testid` passed through.
|
|
48
|
+
3. **Implementation**: build the atom, migrate all 3 call sites; the raw-`<input>` grep now returns 0.
|
|
49
|
+
4. **Enforcement**: document the atom in the DS index (map the raw `<input>` pattern to it), add a lint rule flagging inline-styled bare inputs with a dedicated message (tested across `<src>`), and add a unit test for testid/value/states.
|
|
50
|
+
|
|
51
|
+
Then run lint + typecheck + tests and paste the output.
|
|
52
|
+
|
|
53
|
+
## Related artifacts
|
|
54
|
+
|
|
55
|
+
- [`refactoring-shared-component-api`](../refactoring-shared-component-api/) - for changing the API of a component that already exists.
|
|
56
|
+
- [`frontend-spec-call-site-audit`](../frontend-spec-call-site-audit/) - upstream, when specifying a feature that consumes the DS without extending it.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: design-system-component-lifecycle
|
|
3
|
+
description: Use when creating or extending a design system component, defining a reusable component contract (props/slots/events, tokens), enforcing token usage over hardcoded values, or avoiding duplicated one-off components - "add a component", "a component is needed for", "ajoute un composant", "il manque un composant pour", element/pattern repeated across pages.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: frontend
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Design system component lifecycle - decision → contract → enforcement
|
|
11
|
+
|
|
12
|
+
> If the current repo has an equivalent skill (e.g. acme-app → `design-system-extension`), it wins - it knows the component prefix, the lint rules, and the project's audit specs.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: creating a new DS component, adding a variant, covering a repeated raw pattern/element with a reusable component, or enforcing token usage
|
|
17
|
+
- **`refactoring-shared-component-api`** instead if: evolving the API (props/slots/events) of an **already-shared** component - no creation decision
|
|
18
|
+
- **`frontend-spec-call-site-audit`** upstream if: specifying a feature that consumes the DS without extending it
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
A DS component is not just a view file: it is a file **+ its enforcement**. Without enforcement (doc, lint, test), the raw pattern stays allowed elsewhere and the component becomes decorative - you fall back into the duplicated one-offs it was meant to eliminate. The expected output: component created, **all** the call sites of the raw pattern migrated, and the raw pattern now detected as an error.
|
|
23
|
+
|
|
24
|
+
## Context to gather (before acting)
|
|
25
|
+
|
|
26
|
+
- **Inventory the existing DS**: does a component already cover the need? Read the components index/README (atoms, molecules) and the token library before inventing anything
|
|
27
|
+
- **External library**: does a primitive from an existing third-party UI lib cover the need? Reuse before creating
|
|
28
|
+
- **Atom or molecule?** Atom = primitive/control with no business logic · molecule = composition of atoms. Follow the project's naming/folder convention (a prefix often serves as the lint exemption)
|
|
29
|
+
- **Inventory ALL the call sites of the raw pattern** (`grep -rn '<raw pattern>' <src>`) - migrating them is part of the batch, not just the requesting call site
|
|
30
|
+
- Lint / typecheck / test commands: read `package.json` / CI config
|
|
31
|
+
|
|
32
|
+
## Protocol
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
- [ ] 1. Decision: justify that no existing component nor external primitive covers the need
|
|
36
|
+
- [ ] 2. Contract: props/slots/events, tokens, testid, state (label/hint/error/disabled…)
|
|
37
|
+
- [ ] 3. Implementation: component + migration of ALL raw call sites
|
|
38
|
+
- [ ] 4. Enforcement: doc + lint + tests synchronized (all 3 layers)
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### 1. Decision (in this order)
|
|
42
|
+
|
|
43
|
+
1. Does an existing DS component cover the need (possibly via a variant)?
|
|
44
|
+
2. Does a primitive from an external UI lib cover it?
|
|
45
|
+
3. Atom or molecule? Place/name it per the project convention
|
|
46
|
+
4. List every call site of the raw pattern to migrate
|
|
47
|
+
|
|
48
|
+
### 2. Component contract
|
|
49
|
+
|
|
50
|
+
- **Two-way API** aligned with the project convention (a single name for the value + its update event), not a mix of conventions
|
|
51
|
+
- **State props** aligned with a reference neighboring component (`label`, `hint`, `error`, `disabled`, `required`, `size`) rather than reinvented
|
|
52
|
+
- **Tokens, no hardcoded values**: colors/spacing/typography go through the DS tokens - a literal value (hex, px) bypasses the contract
|
|
53
|
+
- **`testid` as pass-through** from the call site, never hardcoded in the component (two instances on the same page = collision)
|
|
54
|
+
- Variant with no safe default → make it **required** rather than picking an arbitrary default
|
|
55
|
+
|
|
56
|
+
### 3. Implementation + migration
|
|
57
|
+
|
|
58
|
+
- Migrate each call site listed in step 1; grep of the raw pattern = **0 occurrences** outside an explicit exemption
|
|
59
|
+
- Anti-orphan: the new component has ≥ 1 real usage
|
|
60
|
+
|
|
61
|
+
### 4. Enforcement (the heart of the skill) - 3 synchronized layers
|
|
62
|
+
|
|
63
|
+
| Layer | Goal | Action |
|
|
64
|
+
|-------|------|--------|
|
|
65
|
+
| Doc | discoverability | Add the component to the DS index/README (raw pattern → component mapping) |
|
|
66
|
+
| Lint | prevent recurrence | Remove the raw pattern from the exemptions and give it a dedicated error message; autofix **only** if the transformation is mechanically safe. Test the rule on a witness file then on the whole `<src>` |
|
|
67
|
+
| Test | runtime proof | Component unit test (testid, value, states) + visual snapshot if the render is non-trivial + runtime audit that fails if the raw pattern reappears (when the DOM signal is reliable) |
|
|
68
|
+
|
|
69
|
+
## Templates
|
|
70
|
+
|
|
71
|
+
- `templates/component-contract.md` - component contract to fill in (API, tokens, testid, enforcement)
|
|
72
|
+
|
|
73
|
+
## Traps & rationalizations
|
|
74
|
+
|
|
75
|
+
| Excuse | Reality |
|
|
76
|
+
|--------|---------|
|
|
77
|
+
| "I'll just make a quick local component for this page" | That's a duplicated one-off. Inventory the DS first; if the need is reusable, it goes in the DS. |
|
|
78
|
+
| "This exact hex/px isn't in the tokens" | Either the token exists and must be used, or the token is missing and must be added - not a hardcoded value that escapes the contract. |
|
|
79
|
+
| "The component works, enforcement can come later" | Without lint/test, the raw pattern stays allowed elsewhere: the component is decorative, not a DS extension. |
|
|
80
|
+
| "The requesting call site is migrated, that's enough" | The other raw call sites remain debt; the grep of the pattern must drop to 0. |
|
|
81
|
+
|
|
82
|
+
## Exit condition
|
|
83
|
+
|
|
84
|
+
- [ ] Decision documented: why neither an existing component nor an external primitive
|
|
85
|
+
- [ ] Contract defined: consistent two-way API, tokens (zero hardcoded value), testid as pass-through
|
|
86
|
+
- [ ] ALL call sites of the raw pattern migrated (grep = 0 outside an exemption)
|
|
87
|
+
- [ ] Anti-orphan: ≥ 1 real usage of the new component
|
|
88
|
+
- [ ] Enforcement: doc + lint (exemption removed) + test/audit - all 3 layers
|
|
89
|
+
- [ ] Lint + typecheck + tests run, output pasted - never "it should pass"
|
|
90
|
+
|
|
91
|
+
## Tooling
|
|
92
|
+
|
|
93
|
+
- No generic script: raw-pattern detection (`grep`) and the lint rule are stack-specific; tool them in the project skill.
|
|
94
|
+
|
|
95
|
+
## Changelog
|
|
96
|
+
|
|
97
|
+
- 1.0.0 (2026-06-19) - initial version generalized from acme-app's design-system-extension workflow
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Component contract - `<ComponentName>`
|
|
2
|
+
|
|
3
|
+
## Decision
|
|
4
|
+
- No existing DS component covers: <why>
|
|
5
|
+
- No external primitive covers: <why>
|
|
6
|
+
- Type: atom | molecule - location/naming: <…>
|
|
7
|
+
|
|
8
|
+
## API
|
|
9
|
+
| Element | Name | Type | Required | Default | Note |
|
|
10
|
+
|---------|------|------|----------|---------|------|
|
|
11
|
+
| value (two-way) | | | | | associated update event: |
|
|
12
|
+
| prop | label | string | no | | |
|
|
13
|
+
| prop | hint | string | no | | |
|
|
14
|
+
| prop | error | string | no | | |
|
|
15
|
+
| prop | disabled | boolean | no | false | |
|
|
16
|
+
| prop | required | boolean | no | false | |
|
|
17
|
+
| prop | size | enum | no | | |
|
|
18
|
+
| prop | variant | enum | yes | - | no arbitrary default |
|
|
19
|
+
| slot | | | | | |
|
|
20
|
+
| event | | | | | |
|
|
21
|
+
|
|
22
|
+
## Tokens (zero hardcoded value)
|
|
23
|
+
| Aspect | Token used |
|
|
24
|
+
|--------|------------|
|
|
25
|
+
| color | |
|
|
26
|
+
| spacing | |
|
|
27
|
+
| typography | |
|
|
28
|
+
| radius / border | |
|
|
29
|
+
|
|
30
|
+
## testid
|
|
31
|
+
- Pass-through from the call site: yes
|
|
32
|
+
- Internal sub-elements (derived suffix): <…>
|
|
33
|
+
|
|
34
|
+
## Call sites of the raw pattern to migrate
|
|
35
|
+
- [ ] <file:line>
|
|
36
|
+
- [ ] grep of the raw pattern = 0 occurrences outside an exemption
|
|
37
|
+
|
|
38
|
+
## Enforcement
|
|
39
|
+
- [ ] Doc / DS index updated
|
|
40
|
+
- [ ] Lint: raw pattern removed from exemptions, dedicated message, tested
|
|
41
|
+
- [ ] Unit test (testid, value, states)
|
|
42
|
+
- [ ] Visual snapshot (if the render is non-trivial)
|
|
43
|
+
- [ ] Runtime audit (if the DOM signal is reliable)
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# `detection-sweep`
|
|
2
|
+
|
|
3
|
+
> Sweep the whole project, turn every failure into a tracker ticket, and change zero lines of code - detection, never repair.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `audit` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | [`scripts/sweep.ts`](scripts/sweep.ts) (read-only heuristic scan) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`detection-sweep` is a whole-codebase health check. It runs every available check block (typecheck, lint, tests, security audit), and for each failure it files a **ticket in the tracker** - nothing more. Its two outputs are tickets and a report. It never edits code and never commits.
|
|
15
|
+
|
|
16
|
+
## Why it exists
|
|
17
|
+
|
|
18
|
+
The failure mode of an audit is the audit that starts fixing things. Once a sweep begins editing, its report stops being trustworthy (was that failure real, or did you already fix it?), and the fixes ship unreviewed and untracked. So the skill draws a hard line: **detect only**. The value is a complete, verifiable map of the project's problems, each one durable as a ticket with a reproduction command - not a pile of half-fixes and "recommendations" that evaporate.
|
|
19
|
+
|
|
20
|
+
## When it triggers
|
|
21
|
+
|
|
22
|
+
Invoke it when asked to:
|
|
23
|
+
|
|
24
|
+
- "check the whole project", "detect the problems", "run a sweep"
|
|
25
|
+
- do a periodic health check of a codebase
|
|
26
|
+
- run a pre-release audit
|
|
27
|
+
|
|
28
|
+
Use `writing-robust-tests` instead to cover one targeted file, and `bug-ticket-root-cause` instead to document a single observed bug in depth.
|
|
29
|
+
|
|
30
|
+
## How it works
|
|
31
|
+
|
|
32
|
+
The sweep detects the project's available check blocks (typecheck, lint, tests, security audit), runs them all fastest-to-slowest even past failures, and turns each distinct failure cause into one tracker ticket carrying its reproduction command, output, files, and labels. Anti-duplicate signatures and a per-pass creation cap keep the ticket stream sane, and a final `block | status | tickets` report - with skipped blocks called out - closes the pass. No code is edited, nothing is committed.
|
|
33
|
+
|
|
34
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
35
|
+
|
|
36
|
+
### The helper script
|
|
37
|
+
|
|
38
|
+
[`scripts/sweep.ts`](scripts/sweep.ts) is a read-only, dependency-free heuristic scan (`npx tsx scripts/sweep.ts [path]`). It walks the source tree and counts broad signals: flagged debt (TODO/FIXME, lint suppressions), debug leftovers, fragile or disabled tests, swallowed errors, potential secret patterns, and oversized files. It writes nothing - it just prints counts for the skill to triage into tickets (one per cause).
|
|
39
|
+
|
|
40
|
+
### Red flags that mean STOP
|
|
41
|
+
|
|
42
|
+
An Edit/Write on a code file, a `git commit`, or a "recommendation" with no ticket number against it - any of these means the sweep has drifted out of detection.
|
|
43
|
+
|
|
44
|
+
## Worked example
|
|
45
|
+
|
|
46
|
+
> A pre-release sweep of `acme-app`.
|
|
47
|
+
|
|
48
|
+
1. Detect blocks from `package.json`: `typecheck`, `lint`, `test`, `test:e2e`, plus `npm audit`. Run all, in that order.
|
|
49
|
+
2. `lint` is clean; `typecheck` throws 9 errors all from one renamed type (→ **1 ticket**); `test` has 2 unrelated failures (→ **2 tickets**); `npm audit` reports a high-severity CVE (→ **1 ticket** with the proposed `npm audit fix` command *inside* the ticket, not run).
|
|
50
|
+
3. Before creating, search `sweep`-labelled tickets: the CVE already has an open ticket → comment on it instead of a fifth ticket.
|
|
51
|
+
4. Report: a table of the five blocks with status and the three new ticket numbers, total 3 created / 1 commented, and the run duration.
|
|
52
|
+
|
|
53
|
+
Throughout: no file edited, no commit.
|
|
54
|
+
|
|
55
|
+
## Related artifacts
|
|
56
|
+
|
|
57
|
+
- [`writing-robust-tests`](../writing-robust-tests/) - to cover a single targeted file rather than audit the whole.
|
|
58
|
+
- [`bug-ticket-root-cause`](../bug-ticket-root-cause/) - to document one observed bug in depth.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: detection-sweep
|
|
3
|
+
description: Use when asked to check the whole project and report problems - "check the whole project", "detect the problems", "run a sweep", "vérifie tout le projet", "détecte les problèmes", "lance un sweep", periodic health check of a codebase, before a release audit.
|
|
4
|
+
version: 1.0.2
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-07-20
|
|
7
|
+
category: audit
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Detection Sweep - detect, ticket, fix nothing
|
|
11
|
+
|
|
12
|
+
> If the current repo has a specific sweep skill (e.g. acme-app → `test-sweep`), it wins - it knows the project's blocks and tracker.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: sweeping the whole project and reporting problems (periodic health check, pre-release audit) - detection without fixing
|
|
17
|
+
- **`writing-robust-tests`** instead if: covering a targeted file, not auditing the whole
|
|
18
|
+
- **`bug-ticket-root-cause`** instead if: a single observed bug to document in depth
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
**Detection only.** A sweep that fixes along the way is no longer a sweep: its report becomes unverifiable and the unreviewed fixes ship without a ticket. The output = tickets in the tracker + a report, **zero code changes**.
|
|
23
|
+
|
|
24
|
+
## 1. Build the list of blocks (adapt to the project)
|
|
25
|
+
|
|
26
|
+
Detect the available checks: `package.json` scripts, `Makefile`, `Cargo.toml`, CI config (`.gitlab-ci.yml`, `.github/workflows/`). Order: fastest to slowest:
|
|
27
|
+
|
|
28
|
+
1. Compilation / typecheck (per stack)
|
|
29
|
+
2. Lint (per stack)
|
|
30
|
+
3. Unit tests (per stack)
|
|
31
|
+
4. Integration tests / API contracts
|
|
32
|
+
5. E2E
|
|
33
|
+
6. Dependency security audit (`npm audit`, `cargo audit`, `pip-audit`…)
|
|
34
|
+
|
|
35
|
+
**Run ALL the blocks**, even after failures - a partial sweep gives a false picture of health. Parallelize independent blocks.
|
|
36
|
+
|
|
37
|
+
## 2. One failure = one ticket in the tracker
|
|
38
|
+
|
|
39
|
+
Not a report paragraph, not a "recommended action": **a ticket created** (GitLab/GitHub/Jira depending on the repo - use the project's CLI if it has one, otherwise `glab`/`gh`/API).
|
|
40
|
+
|
|
41
|
+
Granularity: 1 ticket per distinct cause (12 mypy errors of the same kind = 1 ticket; 2 tests failing for 2 reasons = 2 tickets).
|
|
42
|
+
|
|
43
|
+
Mandatory content: reproduction command · error output · files involved · block and sweep date · labels (`bug`, `needs-triage`, `sweep`).
|
|
44
|
+
|
|
45
|
+
**Anti-duplicate**: before creating, extract a signature (file + message) and search the open tickets under the `sweep` label - if found, comment instead of duplicating.
|
|
46
|
+
|
|
47
|
+
**Creation cap (`--cap`, default 5)**: create only the N highest-priority tickets per pass, so as not to drown feature work under debt. Sort by severity (blocking > MUST > SHOULD), create up to the cap, and **explicitly list the capped causes** ("8 detected, 5 created, 3 capped") for the next pass - a cap does not erase the rest, it visibly defers it.
|
|
48
|
+
|
|
49
|
+
## 3. Final report
|
|
50
|
+
|
|
51
|
+
Table block | status | tickets created, then the list of tickets with numbers, total and duration. If a block was skipped (unavailable locally, too long), **say so explicitly** - an un-run block is not a green block.
|
|
52
|
+
|
|
53
|
+
## Forbidden rationalizations
|
|
54
|
+
|
|
55
|
+
| Excuse | Reality |
|
|
56
|
+
|--------|---------|
|
|
57
|
+
| "It's an obvious one-line fix" | That's exactly how a sweep drifts. Ticket it. The fix will take 2 min… in a reviewed branch. |
|
|
58
|
+
| "A report is enough, I'll ticket later" | "Later" never comes. Actions with no ticket number get lost (verified: 4 P1 actions lost that way). |
|
|
59
|
+
| "12 errors = 12 tickets, that's too many" | Group by cause, not by occurrence. But grouping ≠ omitting. |
|
|
60
|
+
| "The CVE, I'll run npm audit fix" | That's a code change. Ticket it with the proposed command inside. |
|
|
61
|
+
|
|
62
|
+
## Red flags - STOP
|
|
63
|
+
|
|
64
|
+
- An Edit/Write on a code file during the sweep
|
|
65
|
+
- A `git commit` during the sweep
|
|
66
|
+
- The final report contains "recommendations" with no ticket number against them
|
|
67
|
+
|
|
68
|
+
## Exit condition
|
|
69
|
+
|
|
70
|
+
- [ ] All detected blocks were run (or explicitly marked skipped in the report)
|
|
71
|
+
- [ ] Each failure has a ticket in the tracker (1 per cause), with repro + error output + files
|
|
72
|
+
- [ ] Anti-duplicate checked (`sweep` label) before each creation
|
|
73
|
+
- [ ] **Zero code changes, zero commits** during the sweep
|
|
74
|
+
- [ ] Final report: table block | status | tickets, list of numbers, total and duration
|
|
75
|
+
|
|
76
|
+
## Common options
|
|
77
|
+
|
|
78
|
+
Workflow directives for the sweep as a whole (state them when invoking the skill - they are NOT `sweep.ts` flags):
|
|
79
|
+
`--dry-run` (show without creating) · `--quick` (static blocks only) · `--skip <block>` (note it in the report) · `--cap N` (cap on tickets created per pass, default 5).
|
|
80
|
+
|
|
81
|
+
## Tooling
|
|
82
|
+
|
|
83
|
+
- Test procedure: `scripts/sweep.test.ts` - deterministic behavioral test of the script (positive + negative fixture). Run `npx tsx scripts/sweep.test.ts` from the canonical repo after any change to the script (also picked up by `npm test`). Not distributed to target repos.
|
|
84
|
+
|
|
85
|
+
- `scripts/sweep.ts [path]` - read-only detection sweep (`npx tsx scripts/sweep.ts`); its only argument is the path to scan. Detects: flagged debt (TODO/FIXME, lint suppressions), debug leftovers, fragile/disabled tests, swallowed errors, potential secrets, large files. Produces a report to triage (1 ticket per cause, not per occurrence).
|
|
86
|
+
|
|
87
|
+
## Changelog
|
|
88
|
+
|
|
89
|
+
- 1.0.2 (2026-07-20) - co-located test procedure for sweep.ts (scripts/sweep.test.ts)
|
|
90
|
+
|
|
91
|
+
- 1.0.1 (2026-07-20) - workflow directives clarified as skill options, not sweep.ts flags
|
|
92
|
+
|
|
93
|
+
- 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
#!/usr/bin/env -S npx tsx
|
|
2
|
+
/**
|
|
3
|
+
* Generic, read-only detection sweep: flags common problems to triage.
|
|
4
|
+
* Paired with the detection-sweep skill. Writes/modifies nothing - produces a report.
|
|
5
|
+
*
|
|
6
|
+
* npx tsx sweep.ts [path] # default: current directory
|
|
7
|
+
*
|
|
8
|
+
* Broad heuristics (false positives accepted): the skill decides what to ticket.
|
|
9
|
+
*/
|
|
10
|
+
import { readdirSync, readFileSync, type Dirent } from "node:fs";
|
|
11
|
+
import { join } from "node:path";
|
|
12
|
+
|
|
13
|
+
const root = process.argv[2] ?? ".";
|
|
14
|
+
const PRUNE = new Set(["node_modules", "target", "dist", "build", ".git", "vendor", ".nuxt", ".next"]);
|
|
15
|
+
const EXT = /\.(ts|tsx|js|vue|py|go|rs|php|java)$/;
|
|
16
|
+
const BIG_FILE_LINES = 800; // beyond this, a file is a candidate for splitting
|
|
17
|
+
|
|
18
|
+
function walk(dir: string, acc: string[] = []): string[] {
|
|
19
|
+
let entries: Dirent[];
|
|
20
|
+
try {
|
|
21
|
+
entries = readdirSync(dir, { withFileTypes: true });
|
|
22
|
+
} catch {
|
|
23
|
+
return acc;
|
|
24
|
+
}
|
|
25
|
+
for (const e of entries) {
|
|
26
|
+
if (e.isDirectory()) {
|
|
27
|
+
if (!PRUNE.has(e.name)) walk(join(dir, e.name), acc);
|
|
28
|
+
} else if (EXT.test(e.name)) {
|
|
29
|
+
acc.push(join(dir, e.name));
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
return acc;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const files = walk(root).map((f) => {
|
|
36
|
+
try {
|
|
37
|
+
return { f, lines: readFileSync(f, "utf8").split("\n") };
|
|
38
|
+
} catch {
|
|
39
|
+
return { f, lines: [] as string[] };
|
|
40
|
+
}
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
function count(re: RegExp): number {
|
|
44
|
+
let n = 0;
|
|
45
|
+
for (const { lines } of files) for (const l of lines) if (re.test(l)) n++;
|
|
46
|
+
return n;
|
|
47
|
+
}
|
|
48
|
+
function section(title: string): void {
|
|
49
|
+
console.log(`\n=== ${title} ===`);
|
|
50
|
+
}
|
|
51
|
+
function row(label: string, re: RegExp): void {
|
|
52
|
+
console.log(label.padEnd(40) + count(re));
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
section("Flagged debt");
|
|
56
|
+
row("TODO/FIXME/HACK", /TODO|FIXME|HACK|XXX/);
|
|
57
|
+
row("Lint/type suppressions", /@ts-ignore|@ts-nocheck|eslint-disable|type:\s*ignore|#\[allow\(/);
|
|
58
|
+
|
|
59
|
+
section("Debug leftovers (lines to check)");
|
|
60
|
+
row("Debug statements", /console\.(log|debug)|debugger;|dbg!\(|var_dump|binding\.pry|fmt\.Println/);
|
|
61
|
+
|
|
62
|
+
section("Fragile / disabled tests");
|
|
63
|
+
row("Hardcoded waits", /waitForTimeout|sleep\(|Thread\.sleep/);
|
|
64
|
+
row("Disabled tests", /\.skip\(|xit\(|xdescribe\(|#\[ignore\]|@Disabled|@pytest\.mark\.skip/);
|
|
65
|
+
|
|
66
|
+
section("Suspicious error handling");
|
|
67
|
+
row("Swallowed errors / unwrap", /catch\s*\([^)]*\)\s*\{\s*\}|except[^:]*:\s*pass|\.unwrap\(\)|panic!\(/);
|
|
68
|
+
|
|
69
|
+
section("Potential secrets (check)");
|
|
70
|
+
row("Secret patterns", /AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|sk_live_|glpat-|ghp_/);
|
|
71
|
+
|
|
72
|
+
section(`Large files (> ${BIG_FILE_LINES} lines)`);
|
|
73
|
+
files
|
|
74
|
+
.map(({ f, lines }) => ({ f, n: lines.length }))
|
|
75
|
+
.filter(({ n }) => n > BIG_FILE_LINES)
|
|
76
|
+
.sort((a, b) => b.n - a.n)
|
|
77
|
+
.slice(0, 15)
|
|
78
|
+
.forEach(({ f, n }) => console.log(`${String(n).padStart(6)} ${f}`));
|
|
79
|
+
|
|
80
|
+
console.log("\n→ Triage these signals: 1 ticket per root cause, not 1 per occurrence (see the detection-sweep skill).");
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# `domain-modeling-design`
|
|
2
|
+
|
|
3
|
+
> Design the domain model - aggregates, invariants, bounded contexts, placement - as a spec *before* any code, so the model follows the business and not the database tables.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `feature` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | None (manual design; output is a spec) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`domain-modeling-design` is the *design* half of a two-skill pair. It runs before a single line of implementation code is written and produces a **spec**, not code: aggregates and their invariants, the bounded contexts and their relationships, a justified placement decision, and the command/query/port/event contracts. That spec becomes the input to `ddd-backend-implementation`.
|
|
15
|
+
|
|
16
|
+
## Why it exists
|
|
17
|
+
|
|
18
|
+
If you skip modeling and start coding, the model does not disappear - it gets inferred, badly. It gets read off the shape of the database tables and whatever the first layer written happens to need. The result is the anemic model: entities that are bags of getters and setters, with the real business rules scattered across controllers and services where no invariant is guaranteed.
|
|
19
|
+
|
|
20
|
+
Designing up front prevents that. The skill is deliberately **blocking**: until placement and invariants are decided, it refuses to implement. The cost of a wrong boundary is far higher once code depends on it.
|
|
21
|
+
|
|
22
|
+
## When it triggers
|
|
23
|
+
|
|
24
|
+
Invoke it when you are:
|
|
25
|
+
|
|
26
|
+
- modeling a new domain or aggregate before writing code
|
|
27
|
+
- deciding where a piece of business logic belongs
|
|
28
|
+
- defining invariants or bounded contexts
|
|
29
|
+
- asking "where does this logic go" / "how do I design this domain"
|
|
30
|
+
|
|
31
|
+
It runs **before** implementation, never during. If the model is already settled, go to `ddd-backend-implementation`. If the product need itself is still fuzzy, back up to `superpowers:brainstorming`.
|
|
32
|
+
|
|
33
|
+
## How it works
|
|
34
|
+
|
|
35
|
+
The design produces a spec, not code: identify the aggregates and the invariants they must always hold (one transaction = one aggregate marks the consistency boundary), delimit the bounded contexts and their dependency directions, decide placement by justifying both the choice and the rejected alternatives (the deciding question - must this rule be testable without I/O?), and define the command/query/port contracts plus a domain event for every silent decision. It stays deliberately blocking: no implementation until placement and invariants are settled.
|
|
36
|
+
|
|
37
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
38
|
+
|
|
39
|
+
### Gather context first
|
|
40
|
+
|
|
41
|
+
Map the existing bounded contexts and modules, read a neighboring already-modeled aggregate and copy its conventions, learn the ubiquitous language (business names, not technical ones), and check which cross-cutting project rules apply to the new concept.
|
|
42
|
+
|
|
43
|
+
## Worked example
|
|
44
|
+
|
|
45
|
+
> The product team asks for "subscription pauses": a user can pause a subscription, and it auto-resumes after a set date.
|
|
46
|
+
|
|
47
|
+
1. **Aggregates/invariants**: `Subscription` is the aggregate (own lifecycle: active → paused → active/cancelled). Invariant: "a cancelled subscription cannot be paused"; "pause end date must be in the future". A `PausePeriod` is a value object carried by the aggregate.
|
|
48
|
+
2. **Contexts**: pausing lives in the existing Billing context - it is a continuation of subscription lifecycle, not a new domain. Note that "pause" in Billing is unrelated to a UI "pause" elsewhere; keep them separate.
|
|
49
|
+
3. **Placement**: extend the Billing context (rejected alternative: a new "Pauses" context - overkill, no independent lifecycle). Documented.
|
|
50
|
+
4. **Contracts**: `PauseSubscription` and `ResumeSubscription` commands (reject on the invariants above); a `SubscriptionAutoResumed` **domain event** so the silent auto-resume is debuggable in operations.
|
|
51
|
+
|
|
52
|
+
Output: the spec above, with no code written yet - ready for `ddd-backend-implementation`.
|
|
53
|
+
|
|
54
|
+
## Related artifacts
|
|
55
|
+
|
|
56
|
+
- [`ddd-backend-implementation`](../ddd-backend-implementation/) - implements the spec this skill produces, layer by layer.
|
|
57
|
+
- the Superpowers `brainstorming` skill - upstream, when the product need itself is still unclear.
|