kevinveenbirkenbach/skills
1
0 Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

perf(skills): load the advocate checks and break-risk method only when needed

Browse Source 
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-10-30 16:54:37 +01:00
1 parent 6544f01eef
commit 20a47e3916
5 files changed
+152 -125
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

skills/advocate/SKILL.md
+3 -33
View File
@@ -45,39 +45,9 @@ never a blocker of the commit at hand.
## The checks
1. **Inbound code** - every file or block of foreign origin carries a licence
that the project licence can absorb in the direction of distribution. GPL
code cannot enter a project distributed under MIT without relicensing the
whole; Apache-2.0 cannot enter GPL-2.0-only; code without a licence is all
rights reserved.
2. **Dependency licences** - for each added or bumped dependency, read the
licence of the resolved version (lockfile, registry metadata, or the
package's own LICENSE), including the transitive dependencies the lockfile
newly pulls. Watch copyleft reach (GPL, AGPL's network clause, LGPL static
versus dynamic linking), source-available terms that are not open source
(SSPL, BUSL, Commons Clause, "non-commercial"), and an upstream relicensing
between the old and the new version.
3. **Project licence fit** - the project's declarations still hold against
what checks 1 and 2 found: a dependency that forces copyleft forces either
the project licence or the dependency's removal.
4. **Attribution** - retained copyright notices, the licence text shipped
where required, an Apache-2.0 NOTICE propagated, modified-file notices
(Apache-2.0 §4(b), GPL-3.0 §5(a)), SPDX headers where the project uses them,
credit for CC BY material.
5. **Copied snippets** - Stack Overflow content is CC BY-SA (attribution plus
share-alike); gists, blog posts, other repositories, and verbatim
reproductions of well-known code need a traceable origin and licence.
Trivial code without originality (one-liners, usage dictated by an API) is
not a finding.
6. **Data protection (GDPR, TDDDG)** - new collection, storage, logging, or
transfer of personal data; IP addresses sent to third parties through
external fonts, CDNs, analytics, or embeds; storage on the user's device
without consent (§ 25 TDDDG); transfers outside the EU. Name the data flow
and the missing legal basis or consent mechanism.
7. **Trademarks and branding** - third-party logos, icons, and product names
used beyond plain reference: implied endorsement, use in the project's own
name, modified logos. Icon sets carry their own licence, and a free licence
on an icon does not license the trademark it depicts.
Only for a target in scope: read `checks.md` next to this file and apply its
seven checks (inbound code, dependency licences, project licence fit,
attribution, copied snippets, data protection, trademarks).
## Severity
skills/advocate/checks.md
+37
View File
@@ -0,0 +1,37 @@
# Advocate: the checks
Apply each check to a target the `advocate` skill found in scope.
1. **Inbound code** - every file or block of foreign origin carries a licence
that the project licence can absorb in the direction of distribution. GPL
code cannot enter a project distributed under MIT without relicensing the
whole; Apache-2.0 cannot enter GPL-2.0-only; code without a licence is all
rights reserved.
2. **Dependency licences** - for each added or bumped dependency, read the
licence of the resolved version (lockfile, registry metadata, or the
package's own LICENSE), including the transitive dependencies the lockfile
newly pulls. Watch copyleft reach (GPL, AGPL's network clause, LGPL static
versus dynamic linking), source-available terms that are not open source
(SSPL, BUSL, Commons Clause, "non-commercial"), and an upstream relicensing
between the old and the new version.
3. **Project licence fit** - the project's declarations still hold against
what checks 1 and 2 found: a dependency that forces copyleft forces either
the project licence or the dependency's removal.
4. **Attribution** - retained copyright notices, the licence text shipped
where required, an Apache-2.0 NOTICE propagated, modified-file notices
(Apache-2.0 §4(b), GPL-3.0 §5(a)), SPDX headers where the project uses them,
credit for CC BY material.
5. **Copied snippets** - Stack Overflow content is CC BY-SA (attribution plus
share-alike); gists, blog posts, other repositories, and verbatim
reproductions of well-known code need a traceable origin and licence.
Trivial code without originality (one-liners, usage dictated by an API) is
not a finding.
6. **Data protection (GDPR, TDDDG)** - new collection, storage, logging, or
transfer of personal data; IP addresses sent to third parties through
external fonts, CDNs, analytics, or embeds; storage on the user's device
without consent (§ 25 TDDDG); transfers outside the EU. Name the data flow
and the missing legal basis or consent mechanism.
7. **Trademarks and branding** - third-party logos, icons, and product names
used beyond plain reference: implied endorsement, use in the project's own
name, modified logos. Icon sets carry their own licence, and a free licence
on an icon does not license the trademark it depicts.
skills/break-risk/SKILL.md
+24 -75
View File
@@ -9,86 +9,35 @@ description: >
Break risk is the probability the change breaks something it did not intend to
touch. It is not the inverse of fix confidence, and it is not a mood. Derive it
by answering the questions below; a number produced without them is a guess
wearing a percent sign.
by the steps below; a number produced without them is a guess wearing a
percent sign.
## The consumer question, first and always
## Fast path
Enumerate every consumer of every thing the change alters, before naming a
number. A written caveat never licenses a low number; an enumeration does.
A change whose files nothing builds, deploys, or runs (documentation and
comments only, or tests that ran green with it) has no consumers outside
itself. Name the files (`git diff --cached --name-only`), report break risk
under 1%, and skip the method. Any other file takes the full method.
- Search the **committed** state, not just the working tree. A symbol that looks
unused in your branch may still be called from a file you have not opened
(`git grep <symbol> HEAD`). Removing a function with zero external callers is
a different risk class from removing one with nine.
- Enumerate consumers of the **output**, not only of the code: who reads the
variable, renders the template, parses the emitted block, imports the
constant.
- Say the count out loud. "Two consumers, both inside this change set" is
evidence. "I don't think anything else uses it" is not.
## The method
## Measure the delta at the surface that matters
1. **Consumers**: enumerate every consumer of everything the change alters, in
the committed state (`git grep <symbol> HEAD`) and of its output; say the
count. A caveat never licenses a low number; an enumeration does.
2. **Delta**: run the old and the new code on today's inputs and compare at
the surface where the difference shows (rendered output, emitted config,
returned set, wire bytes), not as the source reads.
3. **Live or latent**: per finding, whether a shipped configuration reaches it.
Only live findings move the number materially.
4. **Matrix**: a verdict per deployment axis the project has, never averaged.
5. **Failure mode**: fails closed and loud, or open and silent; the latter can
outrank a likelier failure.
6. **Evidence**: executed beats derived; a report, a summary or your own
earlier message is not evidence; negative-control every check you cite,
including one you did not write.
Compare what the old code **actually produced** against what the new code
produces, at the point where the difference becomes observable: rendered output,
emitted config, returned set, wire bytes.
The trap this defeats: reasoning about what the old code *looks like* it did. A
sweep that appeared to forward sixteen ports forwarded **zero** in production,
because the flag it gated on was unrendered template text. Had the delta been
argued from the source rather than measured, the risk would have been sized
against a behaviour that never existed.
Extract the old implementation from version control and run it on today's
inputs. If `DROPPED` is empty, nothing can regress; say so and move on.
## Classify every finding as live or latent
For each way the change could break something, decide which it is and say so:
- **Live**: a shipped configuration, inventory, variant or default reaches it.
- **Latent**: reachable only under a configuration nobody ships today.
Both belong in the report. Only live findings drive the number up materially. A
latent finding with a named trigger is worth more to the operator than a vague
worry, and it is honest about why the number is not zero.
## Walk the deployment matrix
A change verified in one mode is unverified in the others. Enumerate the axes
the project actually has, and state the verdict per cell rather than averaging
them away. Typical axes: deployment mode, node role, topology, distro,
filesystem, single versus multi host.
Two numbers for two modes beats one blended number that is wrong in both.
## Weigh the failure mode, not only the probability
A low-probability failure that **fails open** can outrank a likely one that
fails closed. Ask what the world looks like when the change misbehaves:
- Fails closed and loud: the service refuses to start, a gate goes red, a
request errors. Cheap to detect, bounded blast radius.
- Fails open and silent: a port stays reachable, a check passes vacuously, a
credential keeps working, traffic is forwarded to an unintended place.
Say which one applies. When a design choice is between an unverifiable control
over an exposure and not creating the exposure, prefer the second and say why.
## Evidence rules
- Executed beats derived. Run it, render it, read the output.
- A subagent's report, a conversation summary, or your own earlier message is
**not** evidence. Re-verify the claim yourself before it changes a number.
- Negative control before claiming a check works: make the thing it should
catch, watch it fail, restore. A check never observed failing is not known to
work.
- The same applies to a check you did not write. Citing an existing lint, test
or gate as the reason a change is safe means reading its pattern, not its
docstring, and watching it fail on the case you are trusting it to catch. A
green gate whose rule never matched your case is silence, not a pass.
- After a context compaction, rebuild attributions from the source; conclusions
survive compaction, the evidence under them does not.
`reference.md` next to this file explains each step with the trap it defeats.
Read it when a step is new to you or its result is contested.
## Producing the number
skills/break-risk/reference.md
+81
View File
@@ -0,0 +1,81 @@
# Break risk: the method in detail
Each step of the `break-risk` skill, with the trap it defeats.
## The consumer question, first and always
Enumerate every consumer of every thing the change alters, before naming a
number. A written caveat never licenses a low number; an enumeration does.
- Search the **committed** state, not just the working tree. A symbol that looks
unused in your branch may still be called from a file you have not opened
(`git grep <symbol> HEAD`). Removing a function with zero external callers is
a different risk class from removing one with nine.
- Enumerate consumers of the **output**, not only of the code: who reads the
variable, renders the template, parses the emitted block, imports the
constant.
- Say the count out loud. "Two consumers, both inside this change set" is
evidence. "I don't think anything else uses it" is not.
## Measure the delta at the surface that matters
Compare what the old code **actually produced** against what the new code
produces, at the point where the difference becomes observable: rendered output,
emitted config, returned set, wire bytes.
The trap this defeats: reasoning about what the old code *looks like* it did. A
sweep that appeared to forward sixteen ports forwarded **zero** in production,
because the flag it gated on was unrendered template text. Had the delta been
argued from the source rather than measured, the risk would have been sized
against a behaviour that never existed.
Extract the old implementation from version control and run it on today's
inputs. If `DROPPED` is empty, nothing can regress; say so and move on.
## Classify every finding as live or latent
For each way the change could break something, decide which it is and say so:
- **Live**: a shipped configuration, inventory, variant or default reaches it.
- **Latent**: reachable only under a configuration nobody ships today.
Both belong in the report. Only live findings drive the number up materially. A
latent finding with a named trigger is worth more to the operator than a vague
worry, and it is honest about why the number is not zero.
## Walk the deployment matrix
A change verified in one mode is unverified in the others. Enumerate the axes
the project actually has, and state the verdict per cell rather than averaging
them away. Typical axes: deployment mode, node role, topology, distro,
filesystem, single versus multi host.
Two numbers for two modes beats one blended number that is wrong in both.
## Weigh the failure mode, not only the probability
A low-probability failure that **fails open** can outrank a likely one that
fails closed. Ask what the world looks like when the change misbehaves:
- Fails closed and loud: the service refuses to start, a gate goes red, a
request errors. Cheap to detect, bounded blast radius.
- Fails open and silent: a port stays reachable, a check passes vacuously, a
credential keeps working, traffic is forwarded to an unintended place.
Say which one applies. When a design choice is between an unverifiable control
over an exposure and not creating the exposure, prefer the second and say why.
## Evidence rules
- Executed beats derived. Run it, render it, read the output.
- A subagent's report, a conversation summary, or your own earlier message is
**not** evidence. Re-verify the claim yourself before it changes a number.
- Negative control before claiming a check works: make the thing it should
catch, watch it fail, restore. A check never observed failing is not known to
work.
- The same applies to a check you did not write. Citing an existing lint, test
or gate as the reason a change is safe means reading its pattern, not its
docstring, and watching it fail on the case you are trusting it to catch. A
green gate whose rule never matched your case is silence, not a pass.
- After a context compaction, rebuild attributions from the source; conclusions
survive compaction, the evidence under them does not.
skills/confidence/SKILL.md
+7 -17
View File
@@ -10,11 +10,8 @@ description: >
Every stage summary, fix report, or ready-to-commit bundle ends with a
confidence block.
Invoke the `break-risk` skill every time, before writing the block. The break
risk half is derived there — consumers enumerated, the delta measured at the
surface where it shows, live separated from latent, the deployment matrix
walked, the failure mode weighed. Do not estimate it here; this skill reports
the number that skill produces.
Invoke the `break-risk` skill every time, before writing the block; this skill
reports the number it derives and never estimates one itself.
1. **Fix confidence** (percent): probability the change does what it
claims. **Break risk** (percent): probability it breaks anything else,
@@ -36,16 +33,9 @@ Calibration rules:
- Static analysis alone caps at the low nineties; only executed evidence
(test, reproduction, live probe) justifies more.
## When a threshold was stated
A threshold the operator named ("95% confidence, break risk ≤5%") is a gate on
the work, handled as the `break-risk` skill's last section says, for both
numbers.
A number the operator named ("95% confidence, break risk ≤5%") is a gate on the
work, not a field in the report. A block that misses it is not finished output,
it is a work item: name the cheapest evidence that closes the gap, go get it,
re-measure. Report a miss only when that evidence is genuinely out of reach — a
deploy you cannot run, an artifact that does not exist — and say which one.
Objective: the `optimize` skill's. The number exists to save the operator a
verification round trip (time), to stop a rework cycle before it starts
(quality), and to replace a long hedging paragraph with two figures and their
residuals (tokens). A confidence block that costs more than it saves — padding,
repeated caveats, a number without residuals — misses its own objective.
Objective: the `optimize` skill's. Two figures with their residuals replace a
hedging paragraph and save the operator a verification round trip.