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