ronce-racine 0.5.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/AGENTS.md +7 -2
  2. package/README.md +213 -207
  3. package/agents/code-reviewer.md +1 -1
  4. package/dist/hooks/README.md +62 -0
  5. package/dist/hooks/readme-freshness.mjs +159 -0
  6. package/dist/hooks/truncate-output.mjs +13 -5
  7. package/dist/install.js +114 -711
  8. package/dist/src/catalog.js +80 -0
  9. package/dist/src/detect.js +140 -0
  10. package/dist/src/lock.js +200 -0
  11. package/dist/src/paths.js +25 -0
  12. package/dist/src/selector.js +324 -0
  13. package/dist/src/settings.js +55 -0
  14. package/dist/src/uninstall.js +170 -0
  15. package/docs/adopting-a-repo.md +29 -22
  16. package/docs/architecture.md +9 -10
  17. package/docs/catalog.md +86 -0
  18. package/docs/decisions.md +31 -13
  19. package/docs/developing.md +69 -29
  20. package/docs/distribution-model.md +130 -0
  21. package/docs/evaluating-skills.md +42 -2
  22. package/docs/git-worktrees.md +2 -2
  23. package/docs/quality-bar.md +55 -0
  24. package/docs/templates/rule.template.md +2 -1
  25. package/docs/writing-a-rule.md +13 -3
  26. package/docs/writing-a-skill.md +16 -7
  27. package/package.json +17 -4
  28. package/skills/adversarial-feature-challenge/SKILL.md +5 -3
  29. package/skills/api-contract-versioning/SKILL.md +6 -4
  30. package/skills/bug-ticket-root-cause/SKILL.md +5 -3
  31. package/skills/bug-triage-structured/SKILL.md +5 -3
  32. package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
  33. package/skills/commit-readiness-review/SKILL.md +7 -3
  34. package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
  35. package/skills/comprehensive-test-strategy/SKILL.md +5 -3
  36. package/skills/daily-workflow-optimization/SKILL.md +6 -4
  37. package/skills/database-schema-evolution/SKILL.md +6 -4
  38. package/skills/ddd-backend-implementation/SKILL.md +5 -3
  39. package/skills/design-system-component-lifecycle/SKILL.md +6 -4
  40. package/skills/detection-sweep/SKILL.md +7 -3
  41. package/skills/detection-sweep/scripts/sweep.ts +3 -3
  42. package/skills/domain-glossary/README.md +44 -0
  43. package/skills/domain-glossary/SKILL.md +166 -0
  44. package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
  45. package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
  46. package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
  47. package/skills/merge-request-review/SKILL.md +5 -3
  48. package/skills/performance-profiling/README.md +69 -0
  49. package/skills/performance-profiling/SKILL.md +223 -0
  50. package/skills/performance-profiling/reference/go.md +235 -0
  51. package/skills/performance-profiling/reference/native.md +148 -0
  52. package/skills/performance-profiling/reference/node-web.md +157 -0
  53. package/skills/performance-profiling/reference/statistics.md +181 -0
  54. package/skills/performance-profiling/reference/tracy.md +137 -0
  55. package/skills/production-incident-diagnostic/SKILL.md +5 -3
  56. package/skills/qa-session-intake/SKILL.md +5 -3
  57. package/skills/recording-decisions/SKILL.md +5 -3
  58. package/skills/recurring-bug-root-cause/SKILL.md +5 -3
  59. package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
  60. package/skills/refactoring-shared-component-api/SKILL.md +7 -3
  61. package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
  62. package/skills/validating-features-end-to-end/SKILL.md +5 -3
  63. package/skills/visual-regression-check/SKILL.md +6 -4
  64. package/skills/writing-robust-tests/SKILL.md +8 -4
@@ -0,0 +1,166 @@
1
+ ---
2
+ name: domain-glossary
3
+ description: Use when the same thing goes by several names in a codebase, when a term means two different things depending on the file, or when onboarding onto an unfamiliar domain - before naming a new module, table or endpoint. Triggers on "build a glossary", "the naming is inconsistent", "define the domain vocabulary", "three names for the same thing", "construis un glossaire", "le nommage est incohérent", "définis le vocabulaire métier", "trois noms pour la même chose".
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-08-08
7
+ category: process
8
+ ---
9
+
10
+ # Domain glossary - one name per thing, written down
11
+
12
+ > If the current repo already has a glossary, a ubiquitous-language document or
13
+ > an ADR fixing its terms, it wins - extend it rather than starting a rival file.
14
+
15
+ ## When ME and not X
16
+
17
+ - **ME** when: the vocabulary itself is the problem - one concept, several
18
+ names, or one name covering several concepts
19
+ - **domain-modeling-design** instead if: the question is what the aggregates and
20
+ invariants are, not what they are called
21
+ - **recording-decisions** instead if: what must survive is a *choice* (why this
22
+ approach) rather than a *term* (what this word means here)
23
+ - **frontend-spec-call-site-audit** instead if: you need the call sites of an
24
+ existing component, not the name it should have
25
+
26
+ ## Principle
27
+
28
+ **A term that is not written down is renegotiated on every session.** Both by
29
+ people and by agents: an agent asked to add "a client note" will invent
30
+ `ClientNote`, `CustomerComment` or `AccountRemark` with equal confidence,
31
+ because nothing in the repository says which one this codebase already chose.
32
+ The cost is not aesthetic. It is a table nobody finds, a search that returns
33
+ nothing, and a second implementation of something that existed.
34
+
35
+ The output is a `GLOSSARY.md` at the repository root, versioned with the code
36
+ that uses it. Not a wiki page: it must travel in the diff that changes the
37
+ meaning, and it must be readable by whatever opens the repo next.
38
+
39
+ Three properties separate a glossary that works from a list of definitions:
40
+
41
+ 1. **It records what was rejected, and why.** "We say *tenant*, never
42
+ *organization*, because *organization* is a field on the invoice" prevents a
43
+ relapse that a bare definition does not.
44
+ 2. **Each entry points at the code.** A term with no anchor drifts within a
45
+ release. An entry naming the type, table or module is checkable.
46
+ 3. **It is short.** It is read on every naming decision, so anything that is
47
+ not load-bearing costs more than it gives. Prefer removing an obvious term
48
+ to explaining it.
49
+
50
+ ## Context to gather (before writing)
51
+
52
+ - **The candidate terms, from the code, not from memory**: type and class names,
53
+ table names, route segments, event names, queue names. Where the vocabulary
54
+ actually lives is where the compiler enforces it.
55
+ - **The collisions**: the same word in two senses (an `Order` in sales and an
56
+ `Order` in a sort function), and the same sense in two words (`user` /
57
+ `member` / `account`).
58
+ - **The origin of each name**: which one the domain experts say out loud, which
59
+ one exists only because a library used it, which one is a translation artifact.
60
+ - **What the team already fixed elsewhere**: ADRs, an existing README section,
61
+ ticket titles. A term already decided must not be reopened here.
62
+
63
+ ## Protocol
64
+
65
+ ```
66
+ - [ ] 1. Harvest the terms from the code, mechanically
67
+ - [ ] 2. Cluster the synonyms and split the homonyms
68
+ - [ ] 3. Decide one name per concept, with the domain expert if there is one
69
+ - [ ] 4. Anchor each entry to code
70
+ - [ ] 5. Record the rejected terms and the reason
71
+ - [ ] 6. Write GLOSSARY.md, ordered for lookup
72
+ - [ ] 7. Wire it in: point the agent instructions at it
73
+ ```
74
+
75
+ ### 1. Harvest mechanically
76
+
77
+ Read the shapes the code commits to, in this order: schema/migrations, domain
78
+ types, public API routes, event and job names. Names that appear in only one
79
+ function are usually local, not domain.
80
+
81
+ ### 2. Synonyms and homonyms
82
+
83
+ Two distinct failures, two distinct fixes:
84
+
85
+ - **Synonyms** (several names, one concept) → pick one, list the others as
86
+ rejected so a search for them lands on the entry.
87
+ - **Homonyms** (one name, several concepts) → the name cannot stay as-is for
88
+ both. Qualify at least one of them, and say in the entry which context each
89
+ belongs to.
90
+
91
+ ### 3. Decide, do not average
92
+
93
+ If a domain expert is reachable, the word they say wins over the word the code
94
+ happens to hold - that is the whole point of a *ubiquitous* language. If no one
95
+ can arbitrate, prefer the term with the most call sites (cheapest migration) and
96
+ mark the entry as provisional rather than pretending it is settled.
97
+
98
+ ### 4. Anchor each entry
99
+
100
+ Every entry names at least one place the term is real: a type, a table, a route,
101
+ a module. An entry that anchors nowhere is either a term the code does not use -
102
+ delete it - or a gap worth its own ticket.
103
+
104
+ ### 5. Record the rejections
105
+
106
+ The rejected terms are what makes a glossary hold. Without them, the next
107
+ reader re-runs the same debate and may land elsewhere.
108
+
109
+ ### 6. Order for lookup
110
+
111
+ Alphabetical unless the domain has an obvious spine (a lifecycle, a pipeline).
112
+ The reader arrives with a word and wants its meaning; do not make them read the
113
+ document to find one line.
114
+
115
+ ### 7. Wire it in
116
+
117
+ A glossary nobody opens changes nothing. Reference it where naming decisions are
118
+ made: the repository's agent instructions (`CLAUDE.md` / `AGENTS.md`), the
119
+ contributing guide, the pull-request template. One line pointing at it is enough
120
+ - but without that line, the file is decoration.
121
+
122
+ ## Templates
123
+
124
+ ```markdown
125
+ # Glossary
126
+
127
+ Vocabulary of this codebase. One name per concept; the rejected names are listed
128
+ so a search finds its way here. Change a meaning in the same diff as the code.
129
+
130
+ ## <Term>
131
+
132
+ <One sentence, in the domain's words, not the framework's.>
133
+
134
+ | | |
135
+ |---|---|
136
+ | **In the code** | `<type / table / route / module>` |
137
+ | **Not to be confused with** | `<neighbouring term>` - <what separates them> |
138
+ | **We do not say** | `<rejected term>` - <why> |
139
+ | **Status** | settled / provisional (no arbiter yet) |
140
+ ```
141
+
142
+ ## Pitfalls & rationalizations
143
+
144
+ | Excuse | Reality |
145
+ |--------|---------|
146
+ | "Everyone here knows what a *batch* is" | Everyone currently here. The next reader, human or agent, is exactly who this file is for. |
147
+ | "The code is self-documenting" | The code is where the disagreement lives - three names for one concept are all in the code. |
148
+ | "I will write it once the naming settles" | The naming settles *because* it is written down. Waiting is how a third synonym appears. |
149
+ | "Let's keep both terms, they are close enough" | Then every search finds half the call sites, and both keep growing. Pick one; list the other as rejected. |
150
+ | "It belongs in the wiki" | A wiki does not travel in the diff that changed the meaning, and nothing fails when it goes stale. |
151
+ | "It would be a huge document" | A glossary over ~30 entries is describing a codebase, not a domain. Keep the load-bearing terms. |
152
+ | "The ORM already names the tables" | The ORM named them after a framework convention, not after the domain. That is the drift, not the fix. |
153
+
154
+ ## Exit condition
155
+
156
+ - [ ] `GLOSSARY.md` exists at the repository root
157
+ - [ ] Every entry anchors to at least one type, table, route or module that exists
158
+ - [ ] Every synonym cluster resolved to one name, the others listed as rejected
159
+ - [ ] Every homonym either qualified or explicitly scoped per context
160
+ - [ ] Unsettled terms marked provisional rather than presented as decided
161
+ - [ ] The agent instructions (`CLAUDE.md` / `AGENTS.md`) point at the glossary
162
+ - [ ] No entry restates a general programming term the domain does not own
163
+
164
+ ## Changelog
165
+
166
+ - 1.0.0 (2026-08-08) - initial versioned release
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  name: frontend-fullstack-implementation
3
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
4
+ version: 1.0.1
5
5
  metadata:
6
- last-reviewed: 2026-06-19
6
+ last-reviewed: 2026-08-08
7
7
  category: frontend
8
8
  ---
9
9
 
10
10
  # Frontend feature implementation - strict layer separation
11
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.
12
+ > If the current repo has a specific implementation skill, it wins - it knows the stack, the paths, the fetch helpers and the project commands.
13
13
 
14
14
  ## This skill vs. others
15
15
 
@@ -130,4 +130,6 @@ npm run lint
130
130
 
131
131
  ## Changelog
132
132
 
133
- - 1.0.0 (2026-06-19) - initial version, generalized from acme-app's Vue/Nuxt/Pinia workflow (stack coupling removed)
133
+ - 1.0.1 (2026-08-08) - dropped the fictional example projects from the precedence note
134
+
135
+ - 1.0.0 (2026-06-19) - initial version, generalized from a project-specific Vue/Nuxt/Pinia workflow (stack coupling removed)
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  name: frontend-spec-call-site-audit
3
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
4
+ version: 1.0.3
5
5
  metadata:
6
- last-reviewed: 2026-07-20
6
+ last-reviewed: 2026-08-08
7
7
  category: frontend
8
8
  ---
9
9
 
10
10
  # Codebase audit before a frontend spec
11
11
 
12
- > If the current repo has a specific spec skill (e.g. acme-app → `frontend-feature-spec`), it wins.
12
+ > If the current repo has a specific spec skill, it wins.
13
13
 
14
14
  ## This skill vs. others
15
15
 
@@ -77,6 +77,10 @@ A scenario like "I click the card → I see the detail" says nothing about the s
77
77
 
78
78
  ## Changelog
79
79
 
80
+ - 1.0.3 (2026-08-08) - dropped the fictional example projects from the precedence note
81
+
82
+ - 1.0.2 (2026-08-08) - audit-entry-points.ts escapes the component name before building its regex
83
+
80
84
  - 1.0.1 (2026-07-20) - co-located test procedure for audit-entry-points.ts (scripts/audit-entry-points.test.ts)
81
85
 
82
86
  - 1.0.0 (2026-06-19) - initial versioned release + state-of-the-art enrichment (routing, context, protocol, traps, exit condition)
@@ -60,7 +60,10 @@ if (component !== '-') {
60
60
  .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
61
61
  .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
62
62
  .toLowerCase()
63
- section(`Call sites of ${component}`, grep(new RegExp(`<${component}[\\s/>]|<${kebab}[\\s/>]|\\b${component}\\b`)))
63
+ // component comes from argv: a metacharacter in it would become regex syntax.
64
+ const esc = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
65
+ const [c, k] = [esc(component), esc(kebab)]
66
+ section(`Call sites of ${component}`, grep(new RegExp(`<${c}[\\s/>]|<${k}[\\s/>]|\\b${c}\\b`)))
64
67
  }
65
68
  if (route && route !== '-') {
66
69
  const esc = route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
@@ -1,15 +1,15 @@
1
1
  ---
2
2
  name: merge-request-review
3
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
4
+ version: 1.0.1
5
5
  metadata:
6
- last-reviewed: 2026-06-19
6
+ last-reviewed: 2026-08-08
7
7
  category: process
8
8
  ---
9
9
 
10
10
  # Merge Request Review - reviewing a change before integration
11
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.
12
+ > If the current repo has a specific review skill, it wins - it knows the forge, the tracker, the API commands and the project's optional auto-merge.
13
13
 
14
14
  ## This skill vs. others
15
15
 
@@ -74,4 +74,6 @@ As long as a blocking point remains, do not approve.
74
74
 
75
75
  ## Changelog
76
76
 
77
+ - 1.0.1 (2026-08-08) - dropped the fictional example projects from the precedence note
78
+
77
79
  - 1.0.0 (2026-06-19) - initial version, derived from an MR review workflow; forge/tracker/auto-merge coupling removed
@@ -0,0 +1,69 @@
1
+ # performance-profiling
2
+
3
+ A protocol for finding out why something is slow, and for proving that a fix
4
+ actually helped.
5
+
6
+ ## What it is for
7
+
8
+ You have a program that misses a latency target, grows in memory, or regressed
9
+ between two releases, and you do not yet know why. Or someone hands you a patch
10
+ labelled "30% faster" and you need to know whether that number means anything.
11
+
12
+ The skill covers the whole loop: state the target, measure the noise, profile at
13
+ macro level, read the profile correctly, check what a CPU profile cannot see,
14
+ narrow down by dichotomy, isolate one hypothesis, compare A/B with statistics that
15
+ hold up, and lock the result in against future regressions.
16
+
17
+ It is language-agnostic in the body, with per-ecosystem command sheets in
18
+ `reference/`.
19
+
20
+ ## What it is not for
21
+
22
+ - Scoring frontend rendering maturity against a grid → `audit-performance-frontend`
23
+ - Capacity planning, load testing, scaling strategy → `audit-architecture` (SC-01..07)
24
+ - Checking whether production latency is monitored → `audit-observability` (ob-07/08)
25
+ - A live production incident → `production-incident-diagnostic`
26
+ - Code that is wrong rather than slow → `superpowers:systematic-debugging`
27
+
28
+ ## The three failures it prevents
29
+
30
+ 1. **Optimizing code that does not matter.** Without a macro profile, effort goes
31
+ where it is convenient rather than where the time is. Amdahl's ceiling, computed
32
+ before writing code, kills most bad ideas for free.
33
+ 2. **Reporting an effect smaller than the noise.** A 5% improvement on a machine
34
+ with a 15% noise floor is not an improvement, whatever the p-value says. Hence
35
+ the rule of measuring the same code twice before measuring anything else.
36
+ 3. **Answering a latency question with a CPU profile.** A CPU profile shows time
37
+ *on* the CPU and structurally hides every wait: locks, channels, syscalls,
38
+ scheduler starvation. Flat CPU with rising latency is the signature.
39
+
40
+ ## Files
41
+
42
+ | File | Contents |
43
+ |---|---|
44
+ | `SKILL.md` | The protocol, the rationalization table, the exit condition |
45
+ | `reference/statistics.md` | Noise floor, interleaving, reading benchstat, multiple testing |
46
+ | `reference/go.md` | pprof (CPU/heap/block/mutex), labels, runtime/trace, escape analysis, PGO |
47
+ | `reference/node-web.md` | `--cpu-prof`, clinic, heap snapshots, event loop delay, Web Vitals |
48
+ | `reference/native.md` | perf, flame graphs, differential flame graphs, hardware counters, callgrind |
49
+ | `reference/tracy.md` | When Tracy fits, its MCP server, and when to stay away |
50
+
51
+ ## A note on Tracy
52
+
53
+ Tracy is included because it is excellent at something the sampling profilers are
54
+ bad at: showing you the *individual* slow occurrence rather than an average. That
55
+ matters for frame-based and real-time workloads.
56
+
57
+ It is also included with an explicit warning. Its client is C/C++/Lua, with usable
58
+ Rust bindings; the only Go binding is pinned to Tracy 0.9 and Windows-only. On a
59
+ Go or Node stack, `pprof` and the platform tools are the shorter path, and
60
+ `reference/tracy.md` says so rather than pretending otherwise.
61
+
62
+ ## Output
63
+
64
+ A report with one entry per hypothesis. Each carries a verdict (**confirmed,
65
+ refuted, or inconclusive**), the numbers, the sample count, the p-value, and
66
+ a verbatim command that reproduces it.
67
+
68
+ "Inconclusive" is a first-class outcome. A campaign that refutes three of its own
69
+ hypotheses is worth more than one that confirms all eight.
@@ -0,0 +1,223 @@
1
+ ---
2
+ name: performance-profiling
3
+ description: Use when something is slow, memory-hungry or contended and the cause is not yet established - a latency or throughput target is missed, a benchmark regressed, a service grows in memory, or someone proposes an optimization that has not been measured. Triggers on "profile this", "why is this slow", "find the bottleneck", "optimize the hot path", "performance regression", "profile mon code", "pourquoi c'est lent", "trouve le goulot d'étranglement", "flamegraph", "benchstat".
4
+ version: 1.0.0
5
+ metadata:
6
+ last-reviewed: 2026-07-29
7
+ category: audit
8
+ ---
9
+
10
+ # Performance Profiling - measure, then change, then measure again
11
+
12
+ > If the current repo has its own performance skill or a documented benchmark
13
+ > harness, it wins - it knows the representative workload, which is the hardest
14
+ > part to get right.
15
+
16
+ ## When ME and not X
17
+
18
+ - **ME** when: something is slow and you do not yet know why, or an optimization
19
+ is proposed and its effect is not established
20
+ - **audit-performance-frontend** instead if: scoring frontend rendering maturity
21
+ against a grid (WebKit/JSC, DOM, CSS pipeline) rather than investigating one slowdown
22
+ - **audit-architecture** (SC-01..07) instead if: the question is capacity, load
23
+ testing or scaling strategy, not where the time goes
24
+ - **audit-observability** (ob-07, ob-08) instead if: the question is whether
25
+ production latency is *monitored*, not what causes it
26
+ - **production-incident-diagnostic** instead if: something is on fire right now
27
+ - **superpowers:systematic-debugging** instead if: the code is wrong, not slow
28
+
29
+ ## Principle
30
+
31
+ **No optimization without a measurement that precedes it and a measurement that
32
+ follows it.** The output of this skill is not faster code - it is a demonstrated,
33
+ quantified, reproducible difference. A campaign that refutes its own hypotheses
34
+ is a success; one that confirms every hunch is a warning sign.
35
+
36
+ Three failures account for most wasted performance work, and the protocol below
37
+ exists to prevent them:
38
+
39
+ 1. Optimizing code that does not matter (no macro profile first).
40
+ 2. Reporting an effect smaller than the measurement noise.
41
+ 3. Answering a latency question with a CPU profile, which structurally cannot see waiting.
42
+
43
+ ## Context to gather (before acting)
44
+
45
+ - **The target, as a number.** "It is slow" is not a question. "p99 is 210 ms, we
46
+ need 50" is. Without a number there is no stopping condition and no way to know
47
+ you succeeded. If nobody can give you one, that is the first deliverable.
48
+ - **The representative workload.** What input, what concurrency, what data size.
49
+ A profile of an unrepresentative workload optimizes a fiction.
50
+ - **The constraint being hit**: CPU, memory, I/O wait, lock contention, or
51
+ scheduler. You do not know yet - but write down the hypothesis so you can be
52
+ proven wrong.
53
+ - **The measurement environment** and how noisy it is (step 1).
54
+ - Existing benchmarks, harnesses and past profiles: read `Makefile`, `package.json`,
55
+ `bench/`, CI config before writing anything new.
56
+
57
+ ## Protocol
58
+
59
+ ```
60
+ - [ ] 0. State the question and the numeric success criterion
61
+ - [ ] 1. Stabilize the bench and measure the noise floor
62
+ - [ ] 2. Macro profile under representative load - before any micro work
63
+ - [ ] 3. Read the profile: self vs cumulative, apply Amdahl
64
+ - [ ] 4. Check off-CPU as well as on-CPU
65
+ - [ ] 5. Add labels/zones to make the profile queryable
66
+ - [ ] 6. Narrow down by dichotomy (ablation / bisection / bracketing)
67
+ - [ ] 7. One falsifiable hypothesis + the micro-benchmark that isolates it
68
+ - [ ] 8. A/B honestly: interleaved, count>=10, benchstat, read the p-value
69
+ - [ ] 9. Re-measure at macro level - a micro gain invisible at macro is not a gain
70
+ - [ ] 10. Lock it in with a CI regression guard
71
+ ```
72
+
73
+ ### 0. State the question and the criterion
74
+
75
+ Write both down before touching a profiler. The criterion decides when you stop -
76
+ without it, a performance campaign expands until someone gets bored.
77
+
78
+ ### 1. Stabilize the bench and measure the noise floor
79
+
80
+ **Run the unmodified code twice and compare the two runs.** The difference is
81
+ your noise floor: no effect below it can be claimed, on this machine, today.
82
+
83
+ Close competing workloads, check the load average, prefer a fixed CPU governor.
84
+ If the machine cannot be quiet, do not abandon the campaign - **pivot to metrics
85
+ that resist noise**: allocation counts, retained heap, object counts, instruction
86
+ counts. They answer many questions and barely move under load.
87
+
88
+ Details and thresholds: `reference/statistics.md`.
89
+
90
+ ### 2. Macro before micro
91
+
92
+ Profile the whole system under representative load first. Micro-optimizing before
93
+ the macro profile is the most expensive mistake in this protocol, because it is
94
+ invisible: the code gets faster and the program does not.
95
+
96
+ ### 3. Read the profile properly
97
+
98
+ **self** (own instructions) vs **cumulative** (self + callees). Optimize on self,
99
+ navigate on cumulative.
100
+
101
+ Then apply **Amdahl before writing any code**: a function at 8% cumulative caps
102
+ the achievable gain at 8%. Compute that ceiling and decide whether the work is
103
+ worth it - this single step kills most bad optimization ideas for free.
104
+
105
+ Watch for Gregg's *street light anti-method*: profiling the component you know how
106
+ to profile rather than the one holding the time.
107
+
108
+ ### 4. On-CPU and off-CPU
109
+
110
+ A CPU profile shows time **on** the CPU. It cannot show waiting - locks, channels,
111
+ syscalls, scheduler starvation. Flat CPU with rising latency is the signature, and
112
+ a CPU profile will happily show you a plausible, irrelevant hot spot.
113
+
114
+ Get the block/mutex profile, the execution trace, or an off-CPU flame graph. If
115
+ per-operation cost *rises* with parallelism, you are serialized, not slow.
116
+
117
+ ### 5. Instrument with labels or zones
118
+
119
+ Attach the dimension you will want to slice by - tenant, endpoint, job kind,
120
+ pipeline stage - so the profile becomes queryable:
121
+
122
+ - Go: `pprof.Do` + `pprof.Labels`, then `-tagfocus`
123
+ - Native/games: Tracy zones, `ZoneText`/`ZoneValue`
124
+ - Distributed: OpenTelemetry spans
125
+
126
+ Without labels a profile says "JSON decoding is 30%". With them: "30%, and 27
127
+ points of it are one tenant". Instrument phases first, descend only into the phase
128
+ that is over budget - instrumenting everything produces an unreadable timeline and
129
+ real overhead.
130
+
131
+ ### 6. Dichotomy
132
+
133
+ Three complementary forms:
134
+
135
+ - **Ablation** - remove one stage, keep everything else, compare against a control.
136
+ The control is not optional; it is what turns "it grows" into proof.
137
+ - **Bisection** - `git bisect run` driven by a performance predicate to find the
138
+ commit that introduced a regression.
139
+ - **Bracketing** - measure a deliberately degraded version (the operation removed
140
+ entirely) to get the upper bound on any possible gain, before doing the work.
141
+
142
+ ### 7. One falsifiable hypothesis at a time
143
+
144
+ State it so it can fail: "removing X saves at least N ns/op". Write the smallest
145
+ benchmark that isolates it, with a control arm. Two changes at once means an
146
+ uninterpretable result.
147
+
148
+ ### 8. A/B honestly
149
+
150
+ `-count >= 10`, **interleave the A and B runs** (never all-A then all-B - thermal
151
+ drift maps straight onto your comparison), compare with a statistical tool, read
152
+ the p-value.
153
+
154
+ **Never re-run until it becomes significant.** At p<0.05 one run in twenty is
155
+ significant by chance; re-rolling manufactures exactly that false positive. "No
156
+ measurable effect" is a valid, publishable result.
157
+
158
+ ### 9. Re-measure at macro level
159
+
160
+ Take the macro measurement from step 2 again. A micro gain that does not show up
161
+ at macro level was either irrelevant (Amdahl) or noise. Report the macro number,
162
+ not the micro one.
163
+
164
+ ### 10. Lock it in
165
+
166
+ A gain with no regression guard is reclaimed within months. Add a CI comparison
167
+ against the base branch with a **loose** threshold (10-20%): a flaky performance
168
+ gate gets disabled, which is worse than no gate.
169
+
170
+ ## Templates
171
+
172
+ Report one line per hypothesis, and make the verdict explicit:
173
+
174
+ ```markdown
175
+ ### H<n> - <hypothesis stated so it can fail>
176
+
177
+ | | |
178
+ |---|---|
179
+ | **Verdict** | confirmed / refuted / inconclusive |
180
+ | **Measured** | <numbers, with units and sample count> |
181
+ | **Significance** | p=<value>, n=<samples>, noise floor <x>% |
182
+ | **Command** | `<verbatim, re-runnable>` |
183
+ | **Consequence** | <what this changes - or explicitly: nothing> |
184
+ ```
185
+
186
+ ## Pitfalls & rationalizations
187
+
188
+ | Excuse | Reality |
189
+ |--------|---------|
190
+ | "It is obviously the N+1 query / the regex / the lock" | Obvious causes are wrong often enough that measuring costs less than being wrong. Profile first. |
191
+ | "I will profile after making the obvious fixes" | Then you will never know whether the fix did anything, and you will keep it forever regardless. |
192
+ | "The micro-benchmark shows +30%" | On what fraction of total time? A 30% gain on 2% of runtime is 0.6%. Compute Amdahl before celebrating. |
193
+ | "CPU is at 100%, so it is CPU-bound" | It can be spinning on a lock or thrashing GC. Check off-CPU before rewriting the algorithm. |
194
+ | "The machine is a bit busy but the delta is huge" | Then measure the noise floor and show the delta exceeds it. If it does, fine - that takes five minutes. |
195
+ | "benchstat says `~`, let me run it again" | That is multiple testing. Decide the sample count in advance; `~` is the answer. |
196
+ | "No time to set up a control" | Without a control you have a number, not a result. The control is usually the same command minus one flag. |
197
+ | "I will measure it in production later" | You will not, and by then three other changes will have shipped. |
198
+ | "The profiler overhead distorts everything" | ~5-10% for CPU sampling, uniformly distributed. It shifts absolute values, not the ranking you are reading. |
199
+ | "It is faster on my machine" | One machine, one run, no noise floor, no p-value. That is an anecdote. |
200
+
201
+ ## Exit condition
202
+
203
+ - [ ] Numeric success criterion stated before any measurement
204
+ - [ ] Noise floor measured (same code twice) and reported next to every result
205
+ - [ ] Macro profile collected under representative load, before any micro work
206
+ - [ ] Off-CPU checked, not only CPU
207
+ - [ ] Every hypothesis carries an explicit verdict: confirmed / refuted / **inconclusive**
208
+ - [ ] Every A/B claim reports sample count and p-value, from interleaved runs
209
+ - [ ] Every reported number has a verbatim, re-runnable command
210
+ - [ ] Any gain confirmed at macro level, not only in the micro-benchmark
211
+ - [ ] Regression guard added, or its absence explicitly accepted
212
+
213
+ ## Tooling
214
+
215
+ - `reference/statistics.md` - noise floor, interleaving, reading benchstat, multiple testing
216
+ - `reference/go.md` - pprof (CPU/heap/block/mutex), labels, runtime/trace, escape analysis, PGO
217
+ - `reference/node-web.md` - `--cpu-prof`, clinic, heap snapshots, event loop delay, Web Vitals
218
+ - `reference/native.md` - perf, flame graphs, differential flame graphs, hardware counters, callgrind
219
+ - `reference/tracy.md` - when Tracy is the right tool, its MCP server, and when to stay away
220
+
221
+ ## Changelog
222
+
223
+ - 1.0.0 (2026-07-29) - initial versioned release