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,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: domain-modeling-design
|
|
3
|
+
description: Use when modeling a new domain or aggregate before writing code, deciding where a piece of business logic belongs, defining invariants or bounded contexts, or asking "where does this logic go" / "how to design this domain" / "où mettre cette logique" / "comment concevoir ce domaine". Use BEFORE any implementation, not during it.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: feature
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Domain Modeling - design the model BEFORE the code
|
|
11
|
+
|
|
12
|
+
> If the current repo has a specific design skill, it wins - it knows its contexts, its stack and its placement conventions.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: designing the domain model (aggregates, bounded contexts, invariants, placement) **before** writing a single line; deciding where a business rule lives
|
|
17
|
+
- **`ddd-backend-implementation`** (neighboring skill) instead if: the model is settled and you implement it layer by layer (application/infrastructure)
|
|
18
|
+
- **`superpowers:brainstorming`** instead if: the product need itself is fuzzy (upstream of this skill)
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
A good domain model is designed **before** the code, otherwise it gets inferred from the shape of the tables and the first layer written - and you inherit an anemic model. The output of this skill is a **spec** (aggregates, contexts, invariants, contracts, justified placement), not code. Until placement and invariants are decided, refuse to implement.
|
|
23
|
+
|
|
24
|
+
## Context to gather (before acting)
|
|
25
|
+
|
|
26
|
+
- Map the existing landscape: which bounded contexts / modules already exist, where neighboring concepts live
|
|
27
|
+
- Read an already-modeled neighboring aggregate and copy its conventions (naming, boundary, events) before inventing anything
|
|
28
|
+
- The domain's ubiquitous language: names of concepts as the business uses them, not technical terms
|
|
29
|
+
- The project's cross-cutting business rules that may apply to the new concept
|
|
30
|
+
|
|
31
|
+
## Protocol
|
|
32
|
+
|
|
33
|
+
1. **Identify the aggregates and their invariants**
|
|
34
|
+
- Distinguish aggregate (consistency root + own lifecycle), entity (identity within an aggregate), value object (no own lifecycle, carried by the aggregate)
|
|
35
|
+
- One transaction modifies **a single aggregate**: that is the consistency boundary. If a rule requires modifying two aggregates atomically, the boundary is misplaced
|
|
36
|
+
- List the invariants the aggregate guarantees at all times (always true whatever the state)
|
|
37
|
+
2. **Delimit the bounded contexts**
|
|
38
|
+
- The same word can name different concepts depending on the context - separate rather than force-unify
|
|
39
|
+
- Define the relationships between contexts (who depends on whom, in which direction)
|
|
40
|
+
3. **Decide the placement** - in this order, document both the choice AND the rejection of the alternatives:
|
|
41
|
+
- Extend an existing context if the concept is a continuation of it
|
|
42
|
+
- New module in an existing context if CRUD/orchestration, few invariants
|
|
43
|
+
- New bounded context **reserved for**: rich business invariants + own lifecycle + need for pure domain tests
|
|
44
|
+
- Deciding criterion: "must the rule be testable without I/O (DB, network)?" → logic in the domain, isolated from infrastructure
|
|
45
|
+
4. **Define the contracts**
|
|
46
|
+
- Commands/queries that evolve the aggregate; what they reject (invariant violation)
|
|
47
|
+
- Ports (interfaces) on the domain/application side, implementations on the infrastructure side - the domain does not depend on infra
|
|
48
|
+
- **A domain event for every silent decision** (deletion, skip, auto-resolution): without an event, no one can answer "why did nothing happen?"
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
- [ ] Aggregates / entities / VOs identified, consistency boundary justified
|
|
52
|
+
- [ ] Invariants listed (own + project cross-cutting)
|
|
53
|
+
- [ ] Bounded contexts delimited + relationships
|
|
54
|
+
- [ ] Placement decided, rejected alternatives documented
|
|
55
|
+
- [ ] Commands/queries + ports + events defined
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Traps & rationalizations
|
|
59
|
+
|
|
60
|
+
| Excuse | Reality |
|
|
61
|
+
|--------|---------|
|
|
62
|
+
| "I create the data structures, the logic will come after" | That's the anemic model: bags of getters/setters, business logic scattered across services. The aggregate must carry its rules. |
|
|
63
|
+
| "This validation rule, I'll put it in the controller / the application service" | Business logic outside the domain = an unguaranteed invariant, duplicated at the next call site. The rule lives in the aggregate. |
|
|
64
|
+
| "One big context is simpler" | Homonym concepts force-merged = coupling and an unreadable model. Separate the bounded contexts. |
|
|
65
|
+
| "We'll decide placement while implementing" | Placement decided under the pressure of the code follows the tables, not the domain. A blocking decision before the code. |
|
|
66
|
+
| "No need for an event, the deletion is obvious" | A silent decision is undebuggable in operations. Every notable side effect emits an event. |
|
|
67
|
+
|
|
68
|
+
## Exit condition
|
|
69
|
+
|
|
70
|
+
- [ ] Aggregates, entities, value objects identified; consistency boundary (1 transaction = 1 aggregate) justified
|
|
71
|
+
- [ ] Own + cross-cutting invariants enumerated and attached to their aggregate
|
|
72
|
+
- [ ] Bounded contexts delimited, relationships between contexts explicit
|
|
73
|
+
- [ ] Placement decided with rejected alternatives documented
|
|
74
|
+
- [ ] Commands/queries, ports and domain events defined
|
|
75
|
+
- [ ] Spec produced, NO implementation started
|
|
76
|
+
|
|
77
|
+
## Tooling
|
|
78
|
+
|
|
79
|
+
- No script: manual design. The output (domain spec) then feeds the layer-by-layer implementation skill.
|
|
80
|
+
|
|
81
|
+
## Changelog
|
|
82
|
+
|
|
83
|
+
- 1.0.0 (2026-06-19) - initial generic version extracted from a project workflow, decoupled from any stack and any tracker
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# `frontend-fullstack-implementation`
|
|
2
|
+
|
|
3
|
+
> Build a frontend feature in strictly separated layers - model to presentation - so logic never leaks into components, subscriptions never leak memory, and every element stays testable.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `frontend` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | None generic (reuse the project's own test/typecheck/lint commands) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`frontend-fullstack-implementation` is a construction discipline for interactive UI. It takes a written spec and turns it into a feature built **bottom-up in five strict layers** - types, store/state, composable/hook, page, components - with two cross-cutting rules that hold at every layer: a `data-testid` on every locator, and an explicit teardown for every subscription.
|
|
15
|
+
|
|
16
|
+
It is deliberately stack-agnostic. When the current repo has its own implementation skill that knows the framework and paths, that one wins; this skill is the fallback that encodes the layering principle everywhere.
|
|
17
|
+
|
|
18
|
+
## Why it exists
|
|
19
|
+
|
|
20
|
+
The two most expensive frontend mistakes are structural, not visual:
|
|
21
|
+
|
|
22
|
+
1. **Logic in the component.** It looks faster in the moment, but it becomes untestable, non-reusable, and re-runs on every mount. The fix is architectural: logic lives in the store or the composable, and the component only receives props and emits events.
|
|
23
|
+
2. **The uncleaned subscription.** A `subscribe`/`watch`/listener without a teardown leaks memory, accumulates ghost callbacks, and fires updates on unmounted components. The fix is a hard rule: every subscription has a matching teardown.
|
|
24
|
+
|
|
25
|
+
Two more recurring regressions - missing empty/error states and text/class-based test locators - are prevented by the same up-front discipline: handle all four states from the page, and anchor every locator with a `data-testid`.
|
|
26
|
+
|
|
27
|
+
## When it triggers
|
|
28
|
+
|
|
29
|
+
Invoke it when implementing a frontend feature end-to-end, once the spec exists:
|
|
30
|
+
|
|
31
|
+
- "implement the frontend for X" / "add the X page"
|
|
32
|
+
- structuring the types/state/logic/UI layers of a new screen or interactive component
|
|
33
|
+
- adding `data-testid` attributes for testability
|
|
34
|
+
- guarding against subscription leaks
|
|
35
|
+
|
|
36
|
+
If the spec/ticket is **not** written yet, use [`frontend-spec-call-site-audit`](../frontend-spec-call-site-audit/) first.
|
|
37
|
+
|
|
38
|
+
## How it works
|
|
39
|
+
|
|
40
|
+
The feature is built bottom-up in five strictly separated layers - types/models, store/state, composable/hook, page (handling all four loading/error/empty/success states), then pure presentation components - with logic never descending into the component. Two non-negotiable cross-cutting rules hold at every layer: a stable `data-testid` on every locator (never a text- or class-based one), and an explicit teardown for every subscription, watcher, listener or timer. Validation (tests + typecheck + lint) is run and its real output pasted, never "it should pass".
|
|
41
|
+
|
|
42
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
43
|
+
|
|
44
|
+
## Worked example
|
|
45
|
+
|
|
46
|
+
> The spec asks for a "Webhooks" list page in an existing app.
|
|
47
|
+
|
|
48
|
+
1. **types**: `Webhook` DTO with `status: 'active' | 'paused' | 'failed'`, `createdAt: string`.
|
|
49
|
+
2. **store**: `webhooks`, `loading`, `error`; a `fetchWebhooks()` action calling the project's authenticated fetch helper.
|
|
50
|
+
3. **composable**: `useWebhooks()` exposing `isEmpty` and a filtered view - derived, not stored.
|
|
51
|
+
4. **page**: renders `webhooks-loading` / `webhooks-error` / `webhooks-empty` (message + CTA) / `webhooks-list`, no inline logic.
|
|
52
|
+
5. **components**: a `WebhookRow` taking a typed prop and emitting `pause`/`resume`, with `data-testid="webhooks-item-${id}"`.
|
|
53
|
+
6. **cleanup**: the polling that refreshes statuses is torn down on unmount.
|
|
54
|
+
7. **validation**: tests + typecheck + lint run, output pasted.
|
|
55
|
+
|
|
56
|
+
## Related artifacts
|
|
57
|
+
|
|
58
|
+
- [`frontend-spec-call-site-audit`](../frontend-spec-call-site-audit/) - run first when the spec/ticket does not exist yet.
|
|
59
|
+
- [`refactoring-shared-component-api`](../refactoring-shared-component-api/) - when changing the public API of an already-shared component, with no new feature.
|
|
60
|
+
- [`writing-robust-tests`](../writing-robust-tests/) - to cover the feature once implemented.
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend-fullstack-implementation
|
|
3
|
+
description: Use when implementing a frontend feature end-to-end - "implement the frontend for X", "add the X page", "implémente le frontend pour X", "ajoute la page X", structuring types/state/logic/UI layers, adding data-testid attributes, or avoiding subscription leaks. Use for any new screen or interactive component once the spec exists.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-06-19
|
|
7
|
+
category: frontend
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Frontend feature implementation - strict layer separation
|
|
11
|
+
|
|
12
|
+
> If the current repo has a specific implementation skill (e.g. acme-app → `feature-implementation-vue-nuxt`), it wins - it knows the stack, the paths, the fetch helpers and the project commands.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: coding a frontend feature end-to-end (page, screen, interactive component) from an existing spec
|
|
17
|
+
- **frontend-spec-call-site-audit** instead if: the spec/ticket is not written yet (call-site audit + acceptance criteria BEFORE implementing)
|
|
18
|
+
- **refactoring-shared-component-api** instead if: changing the public API of an already-shared component, with no new feature
|
|
19
|
+
- **writing-robust-tests** in addition: to cover the feature once implemented
|
|
20
|
+
|
|
21
|
+
## Principle
|
|
22
|
+
|
|
23
|
+
A frontend feature is built in **strictly separated layers**, in order, from model to presentation:
|
|
24
|
+
|
|
25
|
+
1. **types/models** - DTOs mirroring the API contract
|
|
26
|
+
2. **store/state** - shared state + actions (mutations), never scattered fetches
|
|
27
|
+
3. **composable/hook** - reusable logic derived from state
|
|
28
|
+
4. **page** - routing + selecting the state to display
|
|
29
|
+
5. **components** - pure presentation, driven by props
|
|
30
|
+
|
|
31
|
+
Two non-negotiable cross-cutting disciplines: **`data-testid` on every locator** (nothing is testable without a stable anchor) and **cleanup of every subscription** (a `subscribe`/`watch`/listener without teardown leaks). Logic **never** descends into the component.
|
|
32
|
+
|
|
33
|
+
## Context to gather (before acting)
|
|
34
|
+
|
|
35
|
+
- Framework + commands: read `package.json` / CI config for the `test`, `typecheck`, `lint` scripts
|
|
36
|
+
- **Read a neighbouring feature already shipped** and copy its conventions (layer naming, authenticated fetch helper, empty states, i18n) before inventing
|
|
37
|
+
- Project request helper: is there a wrapper (auth/JWT, 401 handling) to use instead of the raw HTTP call?
|
|
38
|
+
- Does the compiler check templates and props strictly? If not, manually check every prop passed
|
|
39
|
+
|
|
40
|
+
## Protocol
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
- [ ] 1. types/models: DTOs mirroring the API contract, statuses as literal unions
|
|
44
|
+
- [ ] 2. store/state: minimal state (loading/error/data), actions = only mutation point, no raw fetch
|
|
45
|
+
- [ ] 3. composable/hook: derived values (computed), no state duplication
|
|
46
|
+
- [ ] 4. page: route + 4 explicit states (loading / error / empty / success), zero inline logic
|
|
47
|
+
- [ ] 5. components: pure presentation, typed props, no direct store access
|
|
48
|
+
- [ ] 6. data-testid on every locator (page, each state, each interactive element, list items)
|
|
49
|
+
- [ ] 7. cleanup: every subscription / watch / listener has its teardown
|
|
50
|
+
- [ ] 8. validation: tests + typecheck + lint run, output pasted
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### 1. types/models
|
|
54
|
+
|
|
55
|
+
Types mirror the API contract (statuses as literal unions, ISO dates as `string`). If a generator exists (OpenAPI → types), use it; otherwise write them by hand.
|
|
56
|
+
|
|
57
|
+
### 2. store/state
|
|
58
|
+
|
|
59
|
+
Minimal state: data + `loading` + `error`. **Every mutation goes through an action**, never from the presentation layer. No derived data stored - derive it as `computed`. Go through the project fetch helper (auth, 401), not the raw HTTP call.
|
|
60
|
+
|
|
61
|
+
### 3. composable/hook
|
|
62
|
+
|
|
63
|
+
Encapsulates reusable logic (selecting the current item, `isEmpty`, filters) as derived values. No copy of the store state.
|
|
64
|
+
|
|
65
|
+
### 4. page
|
|
66
|
+
|
|
67
|
+
Wires the route, triggers loading, and renders **all four states** - each with a distinct `data-testid`:
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
loading → data-testid="<domain>-loading"
|
|
71
|
+
error → data-testid="<domain>-error"
|
|
72
|
+
empty → data-testid="<domain>-empty"
|
|
73
|
+
success → data-testid="<domain>-list"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
No logic in the template: delegate to the composable.
|
|
77
|
+
|
|
78
|
+
### 5. components
|
|
79
|
+
|
|
80
|
+
Pure presentation: typed props in, events out. No direct store access. Reuse an existing component before creating a new one; check that no created component is orphaned (actually mounted somewhere).
|
|
81
|
+
|
|
82
|
+
### 6. data-testid
|
|
83
|
+
|
|
84
|
+
On **every locator**: page container, each state, each interactive element (button, input, link), each list item (`data-testid="<domain>-item-${id}"`). A locator by CSS class or by text is fragile - it breaks on the slightest restyle or label change.
|
|
85
|
+
|
|
86
|
+
### 7. subscription cleanup
|
|
87
|
+
|
|
88
|
+
Every subscription has an explicit teardown, on component unmount:
|
|
89
|
+
- manual subscription (`subscribe`, stream subscription) → keep the handle and release it
|
|
90
|
+
- watcher / effect → release its handle, or use an auto-disposed effect
|
|
91
|
+
- DOM listener / timer → `removeEventListener` / `clearInterval`
|
|
92
|
+
- framework-idiomatic mechanism (destroy signal, teardown hook) → use it systematically
|
|
93
|
+
|
|
94
|
+
### 8. validation
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
npm run test # or the project equivalent
|
|
98
|
+
npm run typecheck
|
|
99
|
+
npm run lint
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Templates
|
|
103
|
+
|
|
104
|
+
- No file template: copy the structure of a neighbouring feature in the repo (naming conventions, fetch helper, empty states).
|
|
105
|
+
|
|
106
|
+
## Traps & rationalizations
|
|
107
|
+
|
|
108
|
+
| Excuse | Reality |
|
|
109
|
+
|--------|---------|
|
|
110
|
+
| "I'll put the logic straight in the component, it's faster" | Untestable, non-reusable logic that re-fetches on every mount. It lives in the store or the composable. |
|
|
111
|
+
| "I'll fetch directly, no need for the helper" | You lose auth, 401 handling and centralized error handling. Always the project helper. |
|
|
112
|
+
| "No need for data-testid, I'll target by text/class" | A locator by text breaks on the 1st translation, by class on the 1st restyle. data-testid on every locator. |
|
|
113
|
+
| "The subscription will clean itself up" | No: it leaks, accumulates callbacks and triggers updates on an unmounted component. Explicit teardown. |
|
|
114
|
+
| "Empty / error state, I'll do it later" | The 4 missing states are the most frequent regressions. All 4 from the page onward. |
|
|
115
|
+
| "The component accesses the store just to be faster" | Presentation↔state coupling: the component becomes untestable in isolation. Props in, events out. |
|
|
116
|
+
|
|
117
|
+
## Exit condition
|
|
118
|
+
|
|
119
|
+
- [ ] Layers shipped in order: types → state → logic → page → components
|
|
120
|
+
- [ ] Every state mutation goes through an action; no raw fetch outside the project helper
|
|
121
|
+
- [ ] The 4 states (loading/error/empty/success) handled, each with a distinct `data-testid`
|
|
122
|
+
- [ ] `data-testid` on every locator (interactive + list items)
|
|
123
|
+
- [ ] Every subscription/watch/listener has a teardown; grep of subscriptions without cleanup = 0
|
|
124
|
+
- [ ] No orphaned component; zero logic in templates
|
|
125
|
+
- [ ] Tests + typecheck + lint run, output pasted - never "it should pass"
|
|
126
|
+
|
|
127
|
+
## Tooling
|
|
128
|
+
|
|
129
|
+
- Reuse the current repo's scripts and commands (lint, typecheck, type generation). No generic tool provided here: detecting uncleaned subscriptions is framework-dependent - write it in the project skill.
|
|
130
|
+
|
|
131
|
+
## Changelog
|
|
132
|
+
|
|
133
|
+
- 1.0.0 (2026-06-19) - initial version, generalized from acme-app's Vue/Nuxt/Pinia workflow (stack coupling removed)
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# `frontend-spec-call-site-audit`
|
|
2
|
+
|
|
3
|
+
> Before writing a frontend ticket, map the graph the component lives in - call sites, incoming links, global navigation - so the spec never ships an isolated feature that breaks its neighbours.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `frontend` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | [`scripts/audit-entry-points.ts`](scripts/audit-entry-points.ts) · [`templates/ticket-frontend.md`](templates/ticket-frontend.md) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`frontend-spec-call-site-audit` is a **pre-spec discipline**. It sits before any frontend ticket is written and forces a codebase audit first: no page or component is designed in a vacuum, so the acceptance criteria are only drafted once the surrounding graph - sidebar, creation menus, breadcrumbs, parent pages, incoming links - is mapped and cited in the ticket.
|
|
15
|
+
|
|
16
|
+
Its hard rule: **refuse to draft acceptance criteria until the audit is done.**
|
|
17
|
+
|
|
18
|
+
## Why it exists
|
|
19
|
+
|
|
20
|
+
A ticket that describes a component in isolation produces a feature that works on its own screen and breaks everything around it: an orphaned component nobody mounts, a sidebar entry that no longer routes, a missing "+ New" creation path. These call-site breakages are invisible at review time and discovered in production.
|
|
21
|
+
|
|
22
|
+
The other chronic gap is edge cases. The empty state (0 entities) and the single-item case (1 entity) are the most frequently forgotten and the most frequently regressed. Enumerating 0/1/N + error + loading up front turns them from afterthoughts into acceptance criteria.
|
|
23
|
+
|
|
24
|
+
## When it triggers
|
|
25
|
+
|
|
26
|
+
Invoke it **before** writing any frontend feature ticket or spec:
|
|
27
|
+
|
|
28
|
+
- a new page, a new component, a new dashboard section - "add an X page"
|
|
29
|
+
- drafting acceptance criteria for a UI change in an existing app
|
|
30
|
+
|
|
31
|
+
Use a sibling instead when: the component's public API is changing with no new ticket ([`refactoring-shared-component-api`](../refactoring-shared-component-api/)), or the feature is already coded and needs coverage ([`writing-robust-tests`](../writing-robust-tests/)).
|
|
32
|
+
|
|
33
|
+
## How it works
|
|
34
|
+
|
|
35
|
+
The skill runs a blocking 6-point audit - call sites, incoming links, global navigation, data scope, UX edge cases (0/1/N + error + loading), i18n - whose grep results are pasted straight into the ticket. Only once that graph is mapped are acceptance criteria drafted, and at least one of them must be a full user flow rather than an isolated click.
|
|
36
|
+
|
|
37
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
38
|
+
|
|
39
|
+
### Criteria as flows, not isolated actions
|
|
40
|
+
|
|
41
|
+
At least one scenario must be a complete user flow - "How do you create an X from any page?", "What does the page look like at 0/1/N entities?", "The user goes back: what is preserved?" - because "click card → see detail" says nothing about the navigation graph.
|
|
42
|
+
|
|
43
|
+
### The tooling
|
|
44
|
+
|
|
45
|
+
- **[`scripts/audit-entry-points.ts`](scripts/audit-entry-points.ts)** `<ComponentName|-> <route|-> [rootDir]` - a zero-dependency scanner that pre-fills the audit: it greps call sites of the component, incoming links to the route, and heuristically lists the navigation files (sidebar/header/menu/breadcrumb/layout) to check by hand. Pass `-` to skip either criterion.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npx tsx audit-entry-points.ts WebhookList /webhooks ./frontend
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- **[`templates/ticket-frontend.md`](templates/ticket-frontend.md)** - a ticket skeleton whose audit section is blocking: no acceptance criteria until it is filled.
|
|
52
|
+
|
|
53
|
+
## Worked example
|
|
54
|
+
|
|
55
|
+
> "Add a Webhooks page" in an existing dashboard app.
|
|
56
|
+
|
|
57
|
+
1. Run `audit-entry-points.ts WebhookList /webhooks ./frontend`. It reports: `WebhookList` is not yet used anywhere (new component), no incoming links to `/webhooks`, and flags `AppSidebar.vue` + `GlobalCreateMenu.vue` to check.
|
|
58
|
+
2. Fill the ticket audit: sidebar gains a "Webhooks" entry, the "+ New" menu gains "New webhook", data scope is per-organization → URL is `/orgs/:id/webhooks`.
|
|
59
|
+
3. Enumerate edge cases: 0 → empty state with "Create your first webhook", 1 → single row (no giant table chrome), N → paginated, error → retry, loading → skeleton.
|
|
60
|
+
4. Write scenario 1 as a flow: "From any org page, the user opens '+ New → New webhook', fills the form, and lands back on the list with the new row visible."
|
|
61
|
+
|
|
62
|
+
## Related artifacts
|
|
63
|
+
|
|
64
|
+
- [`frontend-fullstack-implementation`](../frontend-fullstack-implementation/) - implement the feature once this audit and spec are done.
|
|
65
|
+
- [`refactoring-shared-component-api`](../refactoring-shared-component-api/) - when the change is to a shared component's API, not a new ticket.
|
|
66
|
+
- [`writing-robust-tests`](../writing-robust-tests/) - to cover the feature after it is coded.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend-spec-call-site-audit
|
|
3
|
+
description: Use BEFORE writing any frontend feature ticket or spec - new page, new component, new dashboard section, "add an X page", "ajoute une page X". Use when drafting acceptance criteria for a UI change in an existing app.
|
|
4
|
+
version: 1.0.1
|
|
5
|
+
metadata:
|
|
6
|
+
last-reviewed: 2026-07-20
|
|
7
|
+
category: frontend
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Codebase audit before a frontend spec
|
|
11
|
+
|
|
12
|
+
> If the current repo has a specific spec skill (e.g. acme-app → `frontend-feature-spec`), it wins.
|
|
13
|
+
|
|
14
|
+
## This skill vs. others
|
|
15
|
+
|
|
16
|
+
- **This skill** when: drafting a frontend ticket/spec or acceptance criteria for a page/component in an existing app
|
|
17
|
+
- **refactoring-shared-component-api** instead if: changing the API of an already-shipped component (props/emits/slots) with no new ticket
|
|
18
|
+
- **writing-robust-tests** instead if: the feature is coded and needs coverage
|
|
19
|
+
|
|
20
|
+
## Principle
|
|
21
|
+
|
|
22
|
+
A frontend ticket **never** describes a component in a vacuum. Every page/component lives in a graph: side navigation, global menus ("+ New"), breadcrumbs, parent pages, incoming links. Specifying without mapping that graph = shipping an isolated feature and breaking the adjacent call sites (orphaned component, menu that no longer routes, missing creation entry).
|
|
23
|
+
|
|
24
|
+
**Refuse to draft the acceptance criteria until the audit is done.**
|
|
25
|
+
|
|
26
|
+
## Context to gather (before acting)
|
|
27
|
+
|
|
28
|
+
- Router + navigation files: read the route config, the sidebar/header/global menu to know where an entry gets added
|
|
29
|
+
- Read a neighbouring page already specced and copy its conventions (empty states, breadcrumbs, i18n) before inventing
|
|
30
|
+
- Data scope: global / per organization / per project - determines where the page lives and which menus are affected
|
|
31
|
+
|
|
32
|
+
## Audit checklist - to paste into the ticket
|
|
33
|
+
|
|
34
|
+
1. **Call sites of the main component**: grep the frontend code; list every page/component that uses it
|
|
35
|
+
2. **Routes / incoming links**: grep the target route; who points at it (sidebar, header, breadcrumb, links)?
|
|
36
|
+
3. **Global navigation**: do the sidebar / creation menu ("+ New") need to gain or change an entry?
|
|
37
|
+
4. **Data scope**: is the entity global, per organization, per project? (determines where the page lives and which menus are affected)
|
|
38
|
+
5. **UX edge cases enumerated**:
|
|
39
|
+
- 0 entities → empty state with message + CTA
|
|
40
|
+
- 1 entity → does the visualization hold up? (no giant canvas for a single node)
|
|
41
|
+
- N entities → pagination/scroll, responsive layout
|
|
42
|
+
- Backend error → display + retry · Loading → skeleton/spinner
|
|
43
|
+
6. **i18n**: required keys listed (or "not applicable" justified)
|
|
44
|
+
|
|
45
|
+
## Acceptance criteria: flows, not isolated actions
|
|
46
|
+
|
|
47
|
+
At least **1 scenario expressed as a complete user flow**:
|
|
48
|
+
- "How do you create an X from any page?"
|
|
49
|
+
- "When the app has 0 / 1 / N entities, what does the page look like?"
|
|
50
|
+
- "The user goes back: what is preserved (URL, scroll, filters)?"
|
|
51
|
+
|
|
52
|
+
A scenario like "I click the card → I see the detail" says nothing about the sidebar, the creation menu, or the other pages that display the same card.
|
|
53
|
+
|
|
54
|
+
## Traps & rationalizations
|
|
55
|
+
|
|
56
|
+
| Excuse | Reality |
|
|
57
|
+
|--------|---------|
|
|
58
|
+
| "The component is isolated, no need to audit call sites" | No component is isolated: sidebar, creation menu and breadcrumb point at it. Grep first. |
|
|
59
|
+
| "The ticket already describes clicking the card → detail" | An isolated action says nothing about global navigation or the other pages showing the same card. Full flow required. |
|
|
60
|
+
| "I'll write the criteria, we'll audit at implementation" | Broken call sites are found in prod. The audit is blocking before the criteria. |
|
|
61
|
+
| "0/1/N entities, the default UX will do" | The empty state and the single-node case are the most frequent regressions. Enumerated or not shipped. |
|
|
62
|
+
|
|
63
|
+
## Exit condition
|
|
64
|
+
|
|
65
|
+
- [ ] Audit of the 6 points complete, **grep results cited** in the ticket (call sites, incoming links, global navigation)
|
|
66
|
+
- [ ] At least 1 criterion expressed as a complete user flow
|
|
67
|
+
- [ ] Edge cases 0 / 1 / N + error + loading enumerated
|
|
68
|
+
- [ ] i18n keys listed or "not applicable" justified
|
|
69
|
+
- [ ] No acceptance criteria drafted before the audit
|
|
70
|
+
|
|
71
|
+
## Tooling
|
|
72
|
+
|
|
73
|
+
- Test procedure: `scripts/audit-entry-points.test.ts` - deterministic behavioral test of the script (positive + negative fixture). Run `npx tsx scripts/audit-entry-points.test.ts` from the canonical repo after any change to the script (also picked up by `npm test`). Not distributed to target repos.
|
|
74
|
+
|
|
75
|
+
- `scripts/audit-entry-points.ts <ComponentName|-> <route|-> [rootDir]` - pre-fills the audit: call sites, incoming links to the route, navigation files (sidebar/header/menu) to check
|
|
76
|
+
- `templates/ticket-frontend.md` - ticket skeleton with the blocking audit section
|
|
77
|
+
|
|
78
|
+
## Changelog
|
|
79
|
+
|
|
80
|
+
- 1.0.1 (2026-07-20) - co-located test procedure for audit-entry-points.ts (scripts/audit-entry-points.test.ts)
|
|
81
|
+
|
|
82
|
+
- 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
#!/usr/bin/env npx tsx
|
|
2
|
+
/**
|
|
3
|
+
* Pre-fills the codebase audit of a frontend ticket: call sites, incoming links
|
|
4
|
+
* to the route, global navigation files (sidebar/header/menu) affected.
|
|
5
|
+
* Usage: npx tsx audit-entry-points.ts <ComponentName|-> <route|-> [rootDir]
|
|
6
|
+
* e.g. audit-entry-points.ts WebhookList /webhooks ./frontend
|
|
7
|
+
* "-" to omit either of the two criteria.
|
|
8
|
+
* Zero dependencies - node builtins only.
|
|
9
|
+
*/
|
|
10
|
+
import * as fs from 'node:fs'
|
|
11
|
+
import * as path from 'node:path'
|
|
12
|
+
|
|
13
|
+
const [component, route, root = process.cwd()] = process.argv.slice(2)
|
|
14
|
+
if (!component) {
|
|
15
|
+
console.error('Usage: audit-entry-points.ts <ComponentName|-> <route|-> [rootDir]')
|
|
16
|
+
process.exit(2)
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const EXT = new Set(['.vue', '.ts', '.tsx', '.js', '.jsx', '.svelte', '.html'])
|
|
20
|
+
const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.nuxt', '.next', '.output', 'coverage'])
|
|
21
|
+
const NAV_HINT = /sidebar|nav|header|menu|breadcrumb|layout/i
|
|
22
|
+
|
|
23
|
+
const files: string[] = []
|
|
24
|
+
function walk(dir: string): void {
|
|
25
|
+
for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
26
|
+
if (e.isDirectory()) {
|
|
27
|
+
if (!SKIP.has(e.name)) walk(path.join(dir, e.name))
|
|
28
|
+
} else if (EXT.has(path.extname(e.name))) files.push(path.join(dir, e.name))
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
walk(root)
|
|
32
|
+
|
|
33
|
+
function grep(pattern: RegExp): Array<{ file: string; line: number; text: string }> {
|
|
34
|
+
const out: Array<{ file: string; line: number; text: string }> = []
|
|
35
|
+
for (const file of files) {
|
|
36
|
+
fs.readFileSync(file, 'utf-8')
|
|
37
|
+
.split('\n')
|
|
38
|
+
.forEach((text, i) => {
|
|
39
|
+
if (pattern.test(text)) out.push({ file: path.relative(root, file), line: i + 1, text: text.trim().slice(0, 100) })
|
|
40
|
+
})
|
|
41
|
+
}
|
|
42
|
+
return out
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
function section(title: string, hits: Array<{ file: string; line: number; text: string }>): void {
|
|
46
|
+
console.log(`\n## ${title}\n`)
|
|
47
|
+
if (!hits.length) {
|
|
48
|
+
console.log('_No results - to interpret: new component/route, or criterion to broaden._')
|
|
49
|
+
return
|
|
50
|
+
}
|
|
51
|
+
for (const h of hits.slice(0, 40)) console.log(`- ${h.file}:${h.line} - ${h.text}`)
|
|
52
|
+
if (hits.length > 40) console.log(`… ${hits.length - 40} more`)
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
console.log(`# Preliminary codebase audit - component: ${component} · route: ${route ?? '-'}\n`)
|
|
56
|
+
console.log(`Scanned root: ${root} (${files.length} files)`)
|
|
57
|
+
|
|
58
|
+
if (component !== '-') {
|
|
59
|
+
const kebab = component
|
|
60
|
+
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
|
|
61
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1-$2')
|
|
62
|
+
.toLowerCase()
|
|
63
|
+
section(`Call sites of ${component}`, grep(new RegExp(`<${component}[\\s/>]|<${kebab}[\\s/>]|\\b${component}\\b`)))
|
|
64
|
+
}
|
|
65
|
+
if (route && route !== '-') {
|
|
66
|
+
const esc = route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
|
|
67
|
+
section(`Incoming links to ${route}`, grep(new RegExp(`["'\`]${esc}`)))
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const navFiles = files.filter((f) => NAV_HINT.test(path.basename(f)))
|
|
71
|
+
console.log(`\n## Global navigation - files to audit manually (sidebar, header, "+ New")\n`)
|
|
72
|
+
for (const f of navFiles.slice(0, 30)) console.log(`- [ ] ${path.relative(root, f)}`)
|
|
73
|
+
if (!navFiles.length) console.log('_No navigation file detected by name heuristic - search manually._')
|
|
74
|
+
|
|
75
|
+
console.log(`\n## Reminders to complete in the ticket
|
|
76
|
+
- [ ] Data scope: global / per organization / per project?
|
|
77
|
+
- [ ] Edge cases: 0 entities (empty+CTA) · 1 entity · N entities (pagination) · backend error · loading
|
|
78
|
+
- [ ] i18n: keys listed or "not applicable" justified
|
|
79
|
+
- [ ] ≥ 1 scenario as a complete user flow (creation from anywhere, going back, 0/1/N)`)
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# [Frontend] <title>
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
<Business need in 1-3 sentences.>
|
|
5
|
+
|
|
6
|
+
## Preliminary codebase audit
|
|
7
|
+
> Output of `audit-entry-points.ts` + answers. **No acceptance criteria until this section is filled in.**
|
|
8
|
+
|
|
9
|
+
- [ ] **Call sites of the main component**: <grep results>
|
|
10
|
+
- [ ] **Incoming links to the route**: <grep results>
|
|
11
|
+
- [ ] **Sidebar**: entry to add / change / not affected - <file>
|
|
12
|
+
- [ ] **Global creation menu ("+ New")**: entry to add / not affected - <file>
|
|
13
|
+
- [ ] **Data scope**: global / per organization / per project → determines the URL and the breadcrumb
|
|
14
|
+
- [ ] **Edge cases**: 0 entities → <empty+CTA> · 1 entity → <layout> · N → <pagination> · error → <retry> · loading → <skeleton>
|
|
15
|
+
- [ ] **i18n**: <keys> (or not applicable)
|
|
16
|
+
|
|
17
|
+
## Acceptance criteria
|
|
18
|
+
|
|
19
|
+
### Scenario 1: <complete user flow - not an isolated action>
|
|
20
|
+
**Given** <state>
|
|
21
|
+
**When** <action from any affected page>
|
|
22
|
+
**Then** <result, including navigation/menus>
|
|
23
|
+
|
|
24
|
+
### Scenario 2: edge case 0 / 1 / N
|
|
25
|
+
### Scenario 3: error case
|
|
26
|
+
|
|
27
|
+
## Technical specifications
|
|
28
|
+
- Files affected:
|
|
29
|
+
- Dependencies:
|
|
30
|
+
|
|
31
|
+
## Estimate
|
|
32
|
+
X SP
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# `merge-request-review`
|
|
2
|
+
|
|
3
|
+
> Reviewing a change before integration means reading the diff line by line and issuing an explicit verdict - a green pipeline is not an approval.
|
|
4
|
+
|
|
5
|
+
| | |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **Type** | Skill (on-demand workflow) |
|
|
8
|
+
| **Category** | `process` |
|
|
9
|
+
| **Artifact** | [`SKILL.md`](SKILL.md) |
|
|
10
|
+
| **Tooling** | [`templates/mr-review-report.md`](templates/mr-review-report.md) |
|
|
11
|
+
|
|
12
|
+
## What it is
|
|
13
|
+
|
|
14
|
+
`merge-request-review` is the discipline for reviewing **someone else's, or not-yet-integrated, work** before it lands on the mainline. It reframes review from a rubber stamp into an obligation: approving means you have read the full diff, worked through a fixed checklist, and issued an explicit verdict - approve or request changes, never a vague "looks good".
|
|
15
|
+
|
|
16
|
+
It is forge- and tracker-agnostic. When the current repo has its own review skill that knows the platform and its API, that one wins.
|
|
17
|
+
|
|
18
|
+
## Why it exists
|
|
19
|
+
|
|
20
|
+
A green pipeline proves the **existing** tests pass. It says nothing about whether the new code is correct, safe, or in scope. The costly leaks slip through exactly where CI is silent:
|
|
21
|
+
|
|
22
|
+
- a secret or a `*.pem`/`.env` committed in a single line
|
|
23
|
+
- a breaking change to a public signature/prop/event that no test in this repo exercises
|
|
24
|
+
- debug leftovers (`console.log`, `dbg!`, `debugger`, unjustified `unwrap`) shipped to prod
|
|
25
|
+
- hard-coded waits (`sleep`, `waitForTimeout`) that make the suite flaky
|
|
26
|
+
- disabled tests (`.skip`, `xit`, `#[ignore]`) quietly hiding a failure
|
|
27
|
+
|
|
28
|
+
Each of these fits in one line, which is why "small diff, no need to read" and "it's urgent, I merge" are the rationalizations the skill explicitly rejects.
|
|
29
|
+
|
|
30
|
+
## When it triggers
|
|
31
|
+
|
|
32
|
+
Invoke it when reviewing a merge/pull request or a branch diff before merge:
|
|
33
|
+
|
|
34
|
+
- "review this MR" / "review this PR" / "validate this branch diff"
|
|
35
|
+
- before integrating someone else's work into the mainline
|
|
36
|
+
|
|
37
|
+
Use a sibling instead when the work is **your own**: [`commit-readiness-review`](../commit-readiness-review/) before committing your changes, the Superpowers `requesting-code-review` skill to get your finished work reviewed, or [`validating-features-end-to-end`](../validating-features-end-to-end/) when the question is "does it work" rather than "is it mergeable".
|
|
38
|
+
|
|
39
|
+
## How it works
|
|
40
|
+
|
|
41
|
+
Gather the real inputs - the full diff (`git diff <remote>/<target>...<remote>/<source>`, not the forge summary), the CI status job by job, the linked ticket, the repo conventions - then read the whole diff before working a fixed checklist that hunts for the leaks CI stays silent on: debug leftovers, hard-coded waits, breaking contract changes, sensitive files, disabled tests, out-of-scope changes. The review closes on an explicit verdict, and no blocking point may remain when approving.
|
|
42
|
+
|
|
43
|
+
Full step-by-step protocol → [`SKILL.md`](SKILL.md).
|
|
44
|
+
|
|
45
|
+
### Record the verdict
|
|
46
|
+
|
|
47
|
+
[`templates/mr-review-report.md`](templates/mr-review-report.md) captures the verdict (APPROVE / REQUEST CHANGES), blocking points (`file:line - problem - expected fix`), minor non-blocking points, and the checklist. As long as a blocking point remains, do not approve.
|
|
48
|
+
|
|
49
|
+
## Worked example
|
|
50
|
+
|
|
51
|
+
> "OK to merge this PR?" - a branch adding a CSV export endpoint.
|
|
52
|
+
|
|
53
|
+
1. Fetch and diff the branch against `main`. CI is green.
|
|
54
|
+
2. Reading the diff line by line: an added `console.log(user.email)` (debug leftover **and** a sensitive-data log), and a renamed response field `created` → `createdAt` that a mobile client consumes (unflagged breaking change).
|
|
55
|
+
3. Verdict: **REQUEST CHANGES**. Blocking: remove the log; either keep the field name or flag and coordinate the breaking change. The green pipeline never surfaced either.
|
|
56
|
+
|
|
57
|
+
## Related artifacts
|
|
58
|
+
|
|
59
|
+
- [`commit-readiness-review`](../commit-readiness-review/) - for reviewing your own changes before commit.
|
|
60
|
+
- [`validating-features-end-to-end`](../validating-features-end-to-end/) - for "does it actually work", functional proof.
|