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.
- package/AGENTS.md +7 -2
- package/README.md +213 -207
- package/agents/code-reviewer.md +1 -1
- package/dist/hooks/README.md +62 -0
- package/dist/hooks/readme-freshness.mjs +159 -0
- package/dist/hooks/truncate-output.mjs +13 -5
- package/dist/install.js +114 -711
- package/dist/src/catalog.js +80 -0
- package/dist/src/detect.js +140 -0
- package/dist/src/lock.js +200 -0
- package/dist/src/paths.js +25 -0
- package/dist/src/selector.js +324 -0
- package/dist/src/settings.js +55 -0
- package/dist/src/uninstall.js +170 -0
- package/docs/adopting-a-repo.md +29 -22
- package/docs/architecture.md +9 -10
- package/docs/catalog.md +86 -0
- package/docs/decisions.md +31 -13
- package/docs/developing.md +69 -29
- package/docs/distribution-model.md +130 -0
- package/docs/evaluating-skills.md +42 -2
- package/docs/git-worktrees.md +2 -2
- package/docs/quality-bar.md +55 -0
- package/docs/templates/rule.template.md +2 -1
- package/docs/writing-a-rule.md +13 -3
- package/docs/writing-a-skill.md +16 -7
- package/package.json +17 -4
- package/skills/adversarial-feature-challenge/SKILL.md +5 -3
- package/skills/api-contract-versioning/SKILL.md +6 -4
- package/skills/bug-ticket-root-cause/SKILL.md +5 -3
- package/skills/bug-triage-structured/SKILL.md +5 -3
- package/skills/ci-pipeline-orchestration/SKILL.md +5 -3
- package/skills/commit-readiness-review/SKILL.md +7 -3
- package/skills/commit-readiness-review/scripts/precommit-scan.ts +3 -3
- package/skills/comprehensive-test-strategy/SKILL.md +5 -3
- package/skills/daily-workflow-optimization/SKILL.md +6 -4
- package/skills/database-schema-evolution/SKILL.md +6 -4
- package/skills/ddd-backend-implementation/SKILL.md +5 -3
- package/skills/design-system-component-lifecycle/SKILL.md +6 -4
- package/skills/detection-sweep/SKILL.md +7 -3
- package/skills/detection-sweep/scripts/sweep.ts +3 -3
- package/skills/domain-glossary/README.md +44 -0
- package/skills/domain-glossary/SKILL.md +166 -0
- package/skills/frontend-fullstack-implementation/SKILL.md +6 -4
- package/skills/frontend-spec-call-site-audit/SKILL.md +7 -3
- package/skills/frontend-spec-call-site-audit/scripts/audit-entry-points.ts +4 -1
- package/skills/merge-request-review/SKILL.md +5 -3
- package/skills/performance-profiling/README.md +69 -0
- package/skills/performance-profiling/SKILL.md +223 -0
- package/skills/performance-profiling/reference/go.md +235 -0
- package/skills/performance-profiling/reference/native.md +148 -0
- package/skills/performance-profiling/reference/node-web.md +157 -0
- package/skills/performance-profiling/reference/statistics.md +181 -0
- package/skills/performance-profiling/reference/tracy.md +137 -0
- package/skills/production-incident-diagnostic/SKILL.md +5 -3
- package/skills/qa-session-intake/SKILL.md +5 -3
- package/skills/recording-decisions/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/SKILL.md +5 -3
- package/skills/recurring-bug-root-cause/scripts/detect-recurring-fixes.ts +1 -1
- package/skills/refactoring-shared-component-api/SKILL.md +7 -3
- package/skills/refactoring-shared-component-api/scripts/sweep-call-sites.ts +10 -3
- package/skills/validating-features-end-to-end/SKILL.md +5 -3
- package/skills/visual-regression-check/SKILL.md +6 -4
- 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.
|
|
4
|
+
version: 1.0.1
|
|
5
5
|
metadata:
|
|
6
|
-
last-reviewed: 2026-
|
|
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
|
|
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.
|
|
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.
|
|
4
|
+
version: 1.0.3
|
|
5
5
|
metadata:
|
|
6
|
-
last-reviewed: 2026-
|
|
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
|
|
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
|
-
|
|
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.
|
|
4
|
+
version: 1.0.1
|
|
5
5
|
metadata:
|
|
6
|
-
last-reviewed: 2026-
|
|
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
|
|
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
|