@sjawhar/pi-envoy 16.19.0 → 16.20.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/README.md +5 -3
- package/dist/envoy.js +1 -1
- package/dist/skills/asd-ste100/SKILL.md +2 -19
- package/dist/skills/dispatch-first/SKILL.md +7 -1
- package/dist/skills/dispatch-writing-specs/SKILL.md +6 -4
- package/dist/skills/envoy/SKILL.md +1 -1
- package/dist/skills/outside-message/SKILL.md +7 -26
- package/dist/skills/plain-words/SKILL.md +41 -42
- package/dist/skills/plain-words/references/mechanics.md +49 -0
- package/dist/skills/thermonuclear-code-quality/LICENSE +21 -0
- package/dist/skills/thermonuclear-code-quality/SKILL.md +70 -0
- package/dist/skills/thermonuclear-deep-review/LICENSE +21 -0
- package/dist/skills/thermonuclear-deep-review/SKILL.md +86 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -169,9 +169,11 @@ pane that still loads the pre-split package beside the new ones.
|
|
|
169
169
|
|
|
170
170
|
The tarball is self-contained: it ships `dist/envoy.js` — bundling every dependency except the OMP
|
|
171
171
|
host packages (`@legion/pi-shared`, `@legion/contracts` and `@legion/envoy-client` are inlined) —
|
|
172
|
-
`dist/THIRD_PARTY_NOTICES`, and the
|
|
173
|
-
`agent-secrets`, `asd-ste100`, `dispatch`, `dispatch-first`, `dispatch-writing-specs`,
|
|
174
|
-
`outside-message` and `plain-words`,
|
|
172
|
+
`dist/THIRD_PARTY_NOTICES`, and the ten skills it ships: the eight every session with Dispatch
|
|
173
|
+
reads, `agent-secrets`, `asd-ste100`, `dispatch`, `dispatch-first`, `dispatch-writing-specs`,
|
|
174
|
+
`envoy`, `outside-message` and `plain-words`, and the reviewer's pair,
|
|
175
|
+
`thermonuclear-code-quality` and `thermonuclear-deep-review`, which ships here so one copy of each
|
|
176
|
+
rubric reaches both harnesses. All ten are staged from the repository's `skills/` at
|
|
175
177
|
`dist/skills`. The manifest declares `omp.skills: ["dist/skills"]` alongside `omp.extensions`:
|
|
176
178
|
OMP's own plugin discovery only reads `skill://`-resolvable skills from `<plugin root>/skills` or
|
|
177
179
|
from directories a manifest's `omp.skills` array names, and this package ships skills at
|
package/dist/envoy.js
CHANGED
|
@@ -41931,7 +41931,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
|
|
|
41931
41931
|
|
|
41932
41932
|
// package.json
|
|
41933
41933
|
var name = "@sjawhar/pi-envoy";
|
|
41934
|
-
var version2 = "16.
|
|
41934
|
+
var version2 = "16.20.0";
|
|
41935
41935
|
var package_default = {
|
|
41936
41936
|
name,
|
|
41937
41937
|
version: version2,
|
|
@@ -8,19 +8,6 @@ Copied from danyuchn/asd-ste100-skill at 32511c69 under its MIT licence (LICENSE
|
|
|
8
8
|
|
|
9
9
|
# Simplified Technical English (ASD-STE100)
|
|
10
10
|
|
|
11
|
-
ASD-STE100 is a controlled-language standard built by the aerospace and defense industry (ASD, the AeroSpace and Defense Industries Association of Europe) to stop maintenance technicians from misreading English instructions. The standard removes the two biggest sources of misreading: words with more than one meaning, and sentences with more than one possible structure.
|
|
12
|
-
|
|
13
|
-
This skill borrows that same discipline for a different reader: an **AI agent or a downstream system** that has to parse an English string — an error message, a tool description, an inter-agent instruction, a status report — without a human in the loop to resolve ambiguity. If a maintenance technician can misread "close the valve" as an adjective ("the valve that is near") instead of a command, so can a language model.
|
|
14
|
-
|
|
15
|
-
## When to Use This Skill
|
|
16
|
-
|
|
17
|
-
- An agent's output (explanation, instruction, log message, tool description) reads as dense, jargon-heavy, or ambiguous.
|
|
18
|
-
- Text will be consumed by another agent, a translation pipeline, or a non-native English reader, and misparsing has a real cost.
|
|
19
|
-
- You are writing a prompt, system message, or tool description and want to remove ambiguity before a model ever sees it.
|
|
20
|
-
- You want a **before/after** comparison showing exactly which rule was violated and how the rewrite fixes it. Ask for it — the default output is the rewritten text alone (see Output Format).
|
|
21
|
-
|
|
22
|
-
This skill is not for creative or marketing copy — STE is deliberately flat and literal. Do not apply it to text where voice, nuance, or persuasion is the point.
|
|
23
|
-
|
|
24
11
|
## Two Modes
|
|
25
12
|
|
|
26
13
|
Pick a mode before rewriting. If the user does not say which, infer it from the text type. Keep the choice internal unless the user asks for the rule table (see Output Format).
|
|
@@ -33,11 +20,11 @@ The two modes and the structural/lexical split are the same distinction seen fro
|
|
|
33
20
|
|
|
34
21
|
## Source and Scope
|
|
35
22
|
|
|
36
|
-
|
|
23
|
+
The rule summary, its citations and worked examples are in `references/writing-rules.md` and `examples/before-after.md`.
|
|
37
24
|
|
|
38
25
|
It does **not** reproduce ASD's ~900-word approved dictionary verbatim. ASD-STE100 is free to obtain, but it is not free to redistribute: Issue 9, page 2 states that "no reproduction or publication of it, in whole or in part, shall be made without the written authority of an officer of ASD," and grants free reproduction rights only to eight listed categories (ASD/AIA/AIAC member associations and their member companies and customers, member-state defence ministries, A4A, airworthiness authorities, and universities and research institutes for educational purposes). This project is in none of them, so the dictionary stays out of this repo.
|
|
39
26
|
|
|
40
|
-
Instead, this skill applies the *underlying principle* (pick the plainest, most common word available and use it the same way every time) rather than checking against a fixed word list. When exact ASD-approved wording matters
|
|
27
|
+
Instead, this skill applies the *underlying principle* (pick the plainest, most common word available and use it the same way every time) rather than checking against a fixed word list. When exact ASD-approved wording matters, get the standard and check word-by-word against the real dictionary.
|
|
41
28
|
|
|
42
29
|
## Core Rewrite Rules
|
|
43
30
|
|
|
@@ -134,7 +121,3 @@ Follow the table with a one-line note on anything you deliberately did **not** s
|
|
|
134
121
|
- Make weak content true or useful. STE fixes the *form* of a text, not its substance. A hollow paragraph rewritten under these rules becomes a clean, short, well-punctuated hollow paragraph. If the text has nothing to say, no rewrite fixes that — say so instead of polishing it.
|
|
135
122
|
- Shorten past the point of clarity. Cutting words is not the goal. Removing ambiguity is the goal. Past a certain point compression starts costing the reader time rather than saving it, so stop when the sentence is unambiguous, not when it is shortest.
|
|
136
123
|
|
|
137
|
-
## Additional Resources
|
|
138
|
-
|
|
139
|
-
- **`references/writing-rules.md`** — fuller summary of the 9 rule sections and dictionary structure, with citations to the official standard and secondary sources.
|
|
140
|
-
- **`examples/before-after.md`** — worked examples, including official STE examples and agent-output examples built for this skill.
|
|
@@ -18,7 +18,7 @@ dispatch search --query 'reviewer threads OR review comments'
|
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
- No hits: remove a word before you add one. Try two or three wordings before you decide nothing exists.
|
|
21
|
-
- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`).
|
|
21
|
+
- Open each hit that can be yours with `dispatch read --issue KEY`, then its parent (`child_of` under `Links:`, or a document's `Issue:`), with its status and recent events.
|
|
22
22
|
|
|
23
23
|
## What to do with what you find
|
|
24
24
|
|
|
@@ -28,6 +28,12 @@ dispatch search --query 'reviewer threads OR review comments'
|
|
|
28
28
|
- **Question already decided:** the answered ask is the record. Cite it (`dispatch://KEY/ask/<id>`). Do not ask again.
|
|
29
29
|
- **Duplicate found:** keep the issue with the spec, copy to it what only the duplicate has, and close the duplicate (`--status done --reason 'Duplicate of dispatch://KEY.'`). When it has the `legion` label or another holder's claim, comment the kept issue's name on it instead.
|
|
30
30
|
|
|
31
|
+
## Research before you ask
|
|
32
|
+
|
|
33
|
+
- Research when a file, command or document can show the answer (a pattern, a convention, a solved problem, a technical approach), because a person must not answer twice what the repository already records.
|
|
34
|
+
- Ask a person only for what their authority, taste or risk appetite settles, because no file holds that. Where a file already records the decision, cite it (`file:line`) and follow it; ask again only when the facts it rested on changed.
|
|
35
|
+
- Say what you searched: each part you found with its source, and each part you did not, with the queries you ran. Ask only the part no search answered.
|
|
36
|
+
|
|
31
37
|
## Reach a person only through Dispatch
|
|
32
38
|
|
|
33
39
|
Reach a person through an ask, an ask block or an approval request.
|
|
@@ -39,16 +39,18 @@ For each spec, ask, comment and message:
|
|
|
39
39
|
- Link each source where the person wrote it, each id whole. With no link, state the design.
|
|
40
40
|
- In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
|
|
41
41
|
- A sentence that cites a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
|
|
42
|
-
- Keep only text
|
|
43
|
-
- Explain each name a new reader may not know, and what each issue you name does for them.
|
|
42
|
+
- Keep only text a reader needs to understand, decide, build or check, and say what each issue you name does for them (`skill://plain-words`).
|
|
44
43
|
- In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
|
|
45
44
|
|
|
46
45
|
## Questions
|
|
47
46
|
|
|
48
47
|
- Name the concrete case and its numbers, then the choice in those terms, never "Which option?".
|
|
49
|
-
- A choice inside what the person asked for,
|
|
48
|
+
- A choice inside what the person asked for, one their messages favour, routine cleanup, sequencing, naming, a choice between equivalent options, and a fix you can make are yours.
|
|
50
49
|
- Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
|
|
51
|
-
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone.
|
|
50
|
+
- Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options, answerable on a phone, and name nothing the reader cannot see from it ("the message above").
|
|
51
|
+
- For each technical term you coined in this session, count the files that hold it, in the repositories the work touches and in Dispatch, by exact match; a single-digit count means expand the term or drop it, because a term you coined reads as familiar to you. A count misses a coinage made of common words, so read the draft for those too.
|
|
52
|
+
- Measure each claim the ask rests on, its premise and each option's precondition. Where you cannot, mark the claim unverified and name the measurement that is missing; call an option unavailable only where a precondition is shown to fail. A premise can go stale within the hour, and no unmeasured number goes in one.
|
|
53
|
+
- Before you pass a question on as one only an attended or privileged act answers, name the source that answers it and try that source, then the other records that hold it, because a 403 or an unfamiliar surface does not make a fact unknowable. Keep a privileged read for what only the live system knows.
|
|
52
54
|
|
|
53
55
|
## Each version
|
|
54
56
|
|
|
@@ -70,7 +70,7 @@ Every topic starts with `notifications.`.
|
|
|
70
70
|
- One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not. Compare its `sha` with the head you wait on, because an earlier commit's settlement can arrive first. A commit whose message carries one of GitHub's skip keywords (`[skip ci]` and its kin) starts no workflow, so no settlement of it may ever arrive.
|
|
71
71
|
- Settlement waits until the commit has had no check event for 5 seconds (`ENVOY_CI_DEBOUNCE`) and every reported check run and check suite of it has finished. No event arrives before that. Envoy does not read GitHub's required-checks list, so a green settlement does not mean GitHub will merge the PR.
|
|
72
72
|
- A `pr.<n>` event with `closed` and `merged: true` means the PR merged; it carries `merge_commit_sha`, `merged_by` and `head_sha`.
|
|
73
|
-
-
|
|
73
|
+
- Code that orders settlements of one commit follows `skill://envoy/references/check-settlement.md`.
|
|
74
74
|
- A Legion implementer waits this way only on a re-run of a red check its task names. Otherwise it pushes and completes its phase, and the daemon reads CI for it (`skill://legion-worker`).
|
|
75
75
|
|
|
76
76
|
## Roles and team topics
|
|
@@ -50,14 +50,13 @@ report, a disclosure, and a reply to a maintainer who wrote first.
|
|
|
50
50
|
do: a reader of the same model as the writer is the weaker check, though no measurement here
|
|
51
51
|
separates the two.
|
|
52
52
|
|
|
53
|
-
**Step 4 ends with a list of what it removed, and that list goes in the ask.**
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
sentence "the reviewer removed nothing", which is itself an answer.
|
|
53
|
+
**Step 4 ends with a list of what it removed, and that list goes in the ask.** An instruction alone
|
|
54
|
+
does not make the cut happen, so the list is what proves it did: three lines naming what came out,
|
|
55
|
+
or the sentence "the reviewer removed nothing", which is itself an answer.
|
|
56
|
+
|
|
57
|
+
**The text the operator approves is the text the reviewer cut, byte for byte.** Any edit after the
|
|
58
|
+
cut, even one line of fact, sends the text back through step 1 and a new fresh review, because a
|
|
59
|
+
sentence added after the cut reaches the operator unreviewed.
|
|
61
60
|
|
|
62
61
|
The form of the text is not in this skill. Where the stream that owns the relationship keeps its own
|
|
63
62
|
rules for writing to maintainers — in its project's `AGENTS.md`, in its skills, or in its brief —
|
|
@@ -85,24 +84,6 @@ An ask for an outside message has, in this order:
|
|
|
85
84
|
Link the research, not the message. An ask with no removal line has not had step 4, whatever it
|
|
86
85
|
says.
|
|
87
86
|
|
|
88
|
-
## Never write these
|
|
89
|
-
|
|
90
|
-
Delete the empty verb phrases and say the literal thing instead. These shapes:
|
|
91
|
-
|
|
92
|
-
| Never | Write instead |
|
|
93
|
-
|---|---|
|
|
94
|
-
| "to name the problem" | say the problem |
|
|
95
|
-
| "land the change" | merge it, release it, deploy it — whichever it is |
|
|
96
|
-
| "carry the finding to X" | tell X, send X, put it on the issue |
|
|
97
|
-
| "this shows the gap" | the gap is … |
|
|
98
|
-
| "that pays for itself" | it costs $X and returns $Y |
|
|
99
|
-
|
|
100
|
-
The test: delete the verb phrase and ask what literally happens. If you cannot say what happens, you
|
|
101
|
-
did not know, and the phrase hid that from both of you. Write what happens.
|
|
102
|
-
|
|
103
|
-
The same rule runs over asks, specs, messages, commit bodies and pull-request descriptions, not only
|
|
104
|
-
outside messages. `skill://plain-words` has the full list and the rewrites.
|
|
105
|
-
|
|
106
87
|
## What this skill does not cover
|
|
107
88
|
|
|
108
89
|
- Text written in a person's own name, which that person signs off.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: plain-words
|
|
3
|
-
description: "Use before you send or publish any text a person reads: an ask, a spec, a Dispatch comment, a message to a colleague, a pull-request body, a commit message, a report, a status update. It removes empty verb phrases and replaces each with the literal thing.
|
|
3
|
+
description: "Use before you send or publish any text a person reads: an ask, a spec, a Dispatch comment, a message to a colleague, a pull-request body, a commit message, a report, a status update. Also use before you answer a question a person asked, and before a draft goes to a reviewer. It removes empty verb phrases and replaces each with the literal thing."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Say the literal thing
|
|
@@ -10,59 +10,51 @@ thing instead.
|
|
|
10
10
|
|
|
11
11
|
Run this over your text before you send it. It takes a minute and it is not optional.
|
|
12
12
|
|
|
13
|
-
##
|
|
14
|
-
|
|
15
|
-
Take the verb phrase out and ask: **what literally happens?** Write that. If you cannot say what
|
|
16
|
-
happens, you did not know, and the phrase hid it from you as well as from the reader.
|
|
17
|
-
|
|
18
|
-
## The phrases, in the order agents actually use them
|
|
13
|
+
## Answering a question
|
|
19
14
|
|
|
20
|
-
|
|
15
|
+
1. Answer the exact question, only it, in the order it was asked, because anything else reads as
|
|
16
|
+
evasion and the question comes again.
|
|
17
|
+
2. Start from what happens, not from a setting, a flag or a name: the reader can reach the setting
|
|
18
|
+
from the behaviour, not the reverse.
|
|
19
|
+
3. Define each term where you first use it, in literal words. No analogy: the reader cannot tell
|
|
20
|
+
which part of one is true.
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|---|---:|---|
|
|
24
|
-
| land the change, land the PR | **1,053** | merge it, release it, deploy it, apply it — whichever one it is |
|
|
25
|
-
| unblock the work | 151 | X can start once Y merges |
|
|
26
|
-
| name the problem, name the owner, name a date | 23 | say the problem; who owns it is X; it is due on 11-02 |
|
|
27
|
-
| it pays for itself, that pays | 13 | it costs $16,306 and returns $60,379 a month |
|
|
28
|
-
| carry it to X, carry the finding | 11 | tell X; send it to X; put it on the issue |
|
|
29
|
-
| this shows the gap, the number shows | 5 | the gap is 12 of 30; the number is 1.17 |
|
|
22
|
+
## Before you send
|
|
30
23
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
24
|
+
A fresh session that has only what the reader has removes what the reader does not need, and lists
|
|
25
|
+
every term it cannot define. Fix each listed term. A reviewer that reads only to approve has not
|
|
26
|
+
done this step, and an instruction alone did not make it happen, so the two lists are what show it
|
|
27
|
+
ran. The check runs on the text going to the reader, never on the instructions you give that
|
|
28
|
+
session or on what it sends back, which would never end.
|
|
34
29
|
|
|
35
|
-
|
|
36
|
-
skill and without it (11 drafts against 10, over 72). Use the test rather than the row: if deleting
|
|
37
|
-
"name" leaves a sentence that says what happens, delete it; if it does not, you were about to write
|
|
38
|
-
a verb for an action you had not decided on.
|
|
30
|
+
## The test
|
|
39
31
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
costs a reader attention and buys nothing.
|
|
32
|
+
Take the verb phrase out and ask: **what literally happens?** Write that. If you cannot say what
|
|
33
|
+
happens, you did not know, and the phrase hid it from you as well as from the reader.
|
|
43
34
|
|
|
44
|
-
##
|
|
35
|
+
## The phrases, commonest first
|
|
45
36
|
|
|
46
|
-
|
|
47
|
-
|
|
37
|
+
| Never | What to write |
|
|
38
|
+
|---|---|
|
|
39
|
+
| land the change, land the PR | merge it, release it, deploy it, apply it — whichever one it is |
|
|
40
|
+
| unblock the work | X can start once Y merges |
|
|
41
|
+
| name the problem, name the owner, name a date | say the problem; who owns it is X; it is due on <date> |
|
|
42
|
+
| it pays for itself, that pays | it costs $16,306 and returns $60,379 a month |
|
|
43
|
+
| carry it to X, carry the finding | tell X; send it to X; put it on the issue |
|
|
44
|
+
| this shows the gap, the number shows | the gap is 12 of 30; the number is 1.17 |
|
|
48
45
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
Either recommend it or do not raise it.
|
|
46
|
+
The rows are in the order agents write them, so look for the first row first: you reach for "land"
|
|
47
|
+
when you cannot say whether the thing merged, released or deployed. If you can say which, say it.
|
|
48
|
+
If you cannot, that is the sentence — "it is approved and not merged" — and it is more useful than
|
|
49
|
+
any verb.
|
|
54
50
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
phrases live.
|
|
51
|
+
On the "name the X" row an instruction alone does not work, so use the test: delete "name". If the
|
|
52
|
+
sentence then says what happens, keep it that way; if it says nothing, you had not decided the
|
|
53
|
+
action, so decide it and write it.
|
|
59
54
|
|
|
60
55
|
## Do not shout
|
|
61
56
|
|
|
62
|
-
|
|
63
|
-
obnoxious format with all caps headers and stuff?
|
|
64
|
-
|
|
65
|
-
No capitalised headers. No capitalised phrases for emphasis. Bold only where a number, a name or a
|
|
57
|
+
No ALL-CAPS headings. No ALL-CAPS phrases for emphasis. Bold only where a number, a name or a
|
|
66
58
|
choice needs to be found again.
|
|
67
59
|
|
|
68
60
|
The reason it appears: an agent writes a long passage, cannot find its point, and puts a handle on
|
|
@@ -86,3 +78,10 @@ collector collects, a sweep sweeps.
|
|
|
86
78
|
English. This skill removes verb phrases that carry no fact. Neither removes AI writing tells, so
|
|
87
79
|
where your session has a pass for those it is a third one. Run them all on an outside message
|
|
88
80
|
(`skill://outside-message`); run this one on everything.
|
|
81
|
+
|
|
82
|
+
The two passes themselves — the structural one and the one that removes the writing that marks
|
|
83
|
+
text as an agent's — are `skill://plain-words/references/mechanics.md`.
|
|
84
|
+
|
|
85
|
+
One kind of text may also have a form skill of its own — a comment to another project's
|
|
86
|
+
maintainers, a document a buyer reads — where the operator ships one; your stream's brief names
|
|
87
|
+
it. This skill holds for all text either way.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# The two passes over a draft
|
|
2
|
+
|
|
3
|
+
Read this when you have a draft and want the passes themselves, not the rule. The structural pass
|
|
4
|
+
makes a sentence hard to misread; the tells pass removes the writing that marks text as an agent's.
|
|
5
|
+
`skill://plain-words` holds the rule each pass serves: every verb names something that happened.
|
|
6
|
+
|
|
7
|
+
Run the structural pass first: a tell often disappears with the sentence that carried it.
|
|
8
|
+
|
|
9
|
+
## The structural pass
|
|
10
|
+
|
|
11
|
+
1. One instruction per sentence. A sentence that holds two actions hides the second from a reader
|
|
12
|
+
who stops at the first.
|
|
13
|
+
2. Active voice, with the actor named. "The job is retried" leaves the reader to guess who retries
|
|
14
|
+
it; "the daemon retries the job" does not.
|
|
15
|
+
3. Simple tenses. A compound tense carries a time relation the reader has to reconstruct, so keep
|
|
16
|
+
one only where that relation is the fact.
|
|
17
|
+
4. Write the thing, not its noun form: "the build failed", not "a build failure occurred". A noun
|
|
18
|
+
made from a verb drops the actor and the time.
|
|
19
|
+
5. Cut a noun stack to three words. Four or more leave the reader guessing which word modifies
|
|
20
|
+
which.
|
|
21
|
+
6. One idea per paragraph, and a list wherever you write three or more of anything. A reader
|
|
22
|
+
counts a list and cannot count a sentence.
|
|
23
|
+
7. Keep every qualifier, exception, number and hedge. Where keeping one makes the sentence long,
|
|
24
|
+
keep it long and say why: dropping "may" turns a possibility into a claim.
|
|
25
|
+
8. Use one word for one thing, through the whole text. A synonym reads as a second thing.
|
|
26
|
+
|
|
27
|
+
## The tells pass
|
|
28
|
+
|
|
29
|
+
1. Delete a sentence that says what you are about to say, or what you have just said. A reader who
|
|
30
|
+
has the point does not need it announced.
|
|
31
|
+
2. Delete praise of the work and of the reader: "great question", "a robust solution".
|
|
32
|
+
3. Delete the symmetry an agent reaches for: "not only X but also Y", "it is not just A, it is B".
|
|
33
|
+
Write the half that is true.
|
|
34
|
+
4. Delete a hedge that costs a second read: "it may be worth considering whether". Recommend it or
|
|
35
|
+
leave it out.
|
|
36
|
+
5. Delete a closing offer to do more. Where something remains, name it as the next step with its
|
|
37
|
+
owner.
|
|
38
|
+
6. Cut an em dash and a semicolon into two sentences, unless the aside is the fact.
|
|
39
|
+
7. Replace a word that rates the thing ("comprehensive", "significant", "seamless") with the
|
|
40
|
+
measurement that made you reach for it.
|
|
41
|
+
8. Read the first and last sentence of each paragraph alone. Where they say the same thing, delete
|
|
42
|
+
one.
|
|
43
|
+
|
|
44
|
+
## Where a fuller pass exists
|
|
45
|
+
|
|
46
|
+
`skill://asd-ste100` is the full controlled-language standard behind the structural pass: run it
|
|
47
|
+
where a reader must not misread one sentence. Neither pass here replaces `skill://plain-words`,
|
|
48
|
+
which is the rule both serve. Where your session installs a fuller pass of its own over AI writing
|
|
49
|
+
tells, run that one after the tells pass above; this file is what you run when it does not.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Cursor
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: thermonuclear-code-quality
|
|
3
|
+
description: Use when asked for a thermonuclear code-quality review or a deep maintainability audit of a branch or PR diff. Also use when asked to review abstraction quality, oversized files or ad-hoc branching growth.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Thermonuclear Code Quality
|
|
8
|
+
|
|
9
|
+
If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
|
|
10
|
+
|
|
11
|
+
Make your own scratch with `mktemp -d` and delete only the paths you made, each by its exact
|
|
12
|
+
path. Never delete by a glob in a shared directory: every role of this issue writes into the same
|
|
13
|
+
`$TMPDIR` on the issue's volume, so a sweep like `rm -rf "$TMPDIR"/tmp.*` deletes directories
|
|
14
|
+
another role has open.
|
|
15
|
+
|
|
16
|
+
This is a maintainability review of one diff: the current branch's changes, or the range you are given. Every remedy keeps behavior the same and removes code or concepts, or moves code where a reader finds it without reading the rest of the file, because a behavior change is work for `skill://thermonuclear-deep-review`, not a cleanup. The table's last two rows change ordering or failure behavior: say so in the finding.
|
|
17
|
+
|
|
18
|
+
## Report
|
|
19
|
+
|
|
20
|
+
The first line is the verdict, with the short sha of the head you reviewed (`git rev-parse --short=8 HEAD`, or the sha your brief names when you have no shell):
|
|
21
|
+
|
|
22
|
+
- `Verdict: APPROVE at <sha>` when no finding stands.
|
|
23
|
+
- `Verdict: CHANGES at <sha>` when one does.
|
|
24
|
+
|
|
25
|
+
Put nothing before it: a PR gate reads only the first line of a posted report.
|
|
26
|
+
|
|
27
|
+
Then one entry per finding: `path:line`, the smell, the cost it adds, and the remedy, so the author can act on it without asking. Report few findings, each one you are sure of: a long list hides the ones that block. Order them so the costliest is read first: step 2's structural regressions and missed code-judo moves, then rows 2-3, 7-8, 1, 9-10, then the rest. Write each as a plain request: `this adds another special-case branch to an already busy flow. Move it into its own function.`
|
|
28
|
+
|
|
29
|
+
## Steps
|
|
30
|
+
|
|
31
|
+
1. Read the diff and each changed file around its hunks. Flag lines the diff adds or changes, and existing code it makes harder to follow, such as a function it lengthens or adds a branch or parameter to. A finding on code the diff leaves alone blocks the PR for work it did not cause.
|
|
32
|
+
2. Look for the code-judo move first: a restructure onto the existing architecture that deletes whole branches, helpers, modes, conditionals or layers. A structural fix often removes the line-level findings with it.
|
|
33
|
+
3. For a refactor, count the concepts (the types, functions, flags and modes) a reader must know before and after. A move that keeps the count is not a simplification: say so, rather than accept a cleaner version of the same idea. When the problem is structural, do not suggest a rename, which hides the finding that matters.
|
|
34
|
+
4. Check every hunk against the table below, because each row is a smell this review blocks on. For file size, compare `git show <base>:<path> | wc -l` with `wc -l <path>`; `<base>` is the range start your brief names, else `git merge-base HEAD origin/<default branch>`.
|
|
35
|
+
5. Before you report a finding, quote its line at the reviewed head. For a boundary, type or duplicate-helper claim, also read the callers (`grep` the symbol) and the existing helper you name. A finding built on a misread costs the author a round.
|
|
36
|
+
6. Report only a cost you can name (the table's Cost column). A preference or a micro-optimization with no such cost is not a finding. When a structural finding exists, leave out naming and style nits, because they bury it.
|
|
37
|
+
7. Ask for a new abstraction (a type, module or policy object) only when the code shows two real callers or two ways it will change. With one, the abstraction is the thin wrapper row 6 flags.
|
|
38
|
+
|
|
39
|
+
## Smells and remedies
|
|
40
|
+
|
|
41
|
+
| Smell | Cost | Remedy |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| The PR pushes a file from under 1000 lines to over 1000 | more to scan for every change | Decompose it first into helpers, modules or local abstractions. Accept the growth only when the PR names the caller or constraint that keeps the code in that file. |
|
|
44
|
+
| Ad-hoc conditionals, special cases, one-off booleans, nullable modes or flags in unrelated or busy flows. A branch for one input value in the middle of a busy function. A branch whose name or comment says it is temporary. | each later change reads every branch | Reframe the state model so the conditionals disappear, not only move to one place. Make the special case part of a simpler default flow. Else move it into its own function, or behind an abstraction step 7 allows. |
|
|
45
|
+
| Repeated conditionals or condition chains | each new case edits every chain | A typed model or an explicit dispatcher. |
|
|
46
|
+
| Copy-pasted logic or duplicate branches | a fix lands in one copy | Extract a helper or pure function. Collapse into one flow. |
|
|
47
|
+
| Hacky, brittle or "magic" behavior, such as reading a value by its string form or position. Generic mechanisms that hide simple data-shape assumptions. | the assumption breaks with no error | Direct code that states the assumption: a typed field, a named constant, an explicit check. |
|
|
48
|
+
| Thin wrappers, identity abstractions, pass-through helpers | one more layer to cross | Delete the layer. |
|
|
49
|
+
| Unnecessary optionality, `unknown`, `any`, casts, loose ad-hoc objects. A silent fallback over an unclear invariant. | the type hides what the value is | Explicit typed models or shared contracts, so the control flow gets simpler. |
|
|
50
|
+
| Feature logic in shared paths. Implementation details leaking through APIs. Logic in the wrong file, layer or package. | every caller of the shared path pays | Move it to the package whose existing code already reads or writes that data (`grep` its type). |
|
|
51
|
+
| A bespoke helper where the repository already has one that does the same | two helpers drift apart | Reuse the existing helper; name it as `path:line`. |
|
|
52
|
+
| A module that became more coupled (a new import of another package), stateful (new module-level state) or hard to scan. Orchestration mixed with business logic. | a change to one concern touches the others | Split into focused modules. Separate orchestration from business logic. |
|
|
53
|
+
| Independent work run in sequence | an order nothing needs | Run it in parallel, only when the parallel code is also simpler. |
|
|
54
|
+
| Related updates that can leave state half-applied | a failure leaves state no code expects | A more atomic flow. |
|
|
55
|
+
|
|
56
|
+
## Approval bar
|
|
57
|
+
|
|
58
|
+
- A structural regression, a hacky or magic abstraction, a boundary leak, or a missed obvious decomposition blocks whatever the PR says, because no evidence makes the code easier to change.
|
|
59
|
+
- Every other finding blocks, and the verdict is CHANGES, unless the PR gives evidence that the simpler form fails: a caller it breaks, a measured cost, or a constraint outside the diff that the PR names with `path:line` or a link. "It works" and "tests pass" are no such evidence, because this review judges structure, not behavior.
|
|
60
|
+
- State a blocking finding as blocking, directly and without rudeness. A "maybe" or "consider" finding reads as optional and gets skipped.
|
|
61
|
+
|
|
62
|
+
## A reviewer rates, a lead decides
|
|
63
|
+
|
|
64
|
+
- Rate each finding; the lead disposes of it. Put on the must-fix list only a finding that has to
|
|
65
|
+
be fixed before this change ships, because a list that mixes those with the rest gets filtered
|
|
66
|
+
by nobody.
|
|
67
|
+
- The four dispositions the lead gives a finding are act on, consider, noted and dismissed. Write
|
|
68
|
+
each finding so the lead can place it: the evidence, the cost, and what it depends on.
|
|
69
|
+
- Do not review a diff you wrote. A reviewer that grades its own work reports no finding against
|
|
70
|
+
it, so hand the diff to a session that did not write it.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Cursor
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: thermonuclear-deep-review
|
|
3
|
+
description: Use when asked for a thermonuclear or deep review, or for a security and correctness audit of a branch or PR diff. Covers bugs, breaking changes, security issues, developer-experience regressions and feature-gate leaks.
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Thermonuclear Deep Review
|
|
8
|
+
|
|
9
|
+
If this skill disagrees with the code, a command's output or its `--help`, follow those and say which line of this skill is wrong.
|
|
10
|
+
|
|
11
|
+
Make your own scratch as `skill://thermonuclear-code-quality` says, and delete only the paths
|
|
12
|
+
you made: every role of this issue writes into one shared `$TMPDIR`.
|
|
13
|
+
|
|
14
|
+
## Verdict
|
|
15
|
+
|
|
16
|
+
The first line of the report is the verdict, in exactly this form, because a PR gate reads only that line. `<sha>` is the short sha of the head you reviewed, or the sha your brief names when you have no shell:
|
|
17
|
+
|
|
18
|
+
- `Verdict: CHANGES at <sha>` when the report has a Medium or High finding.
|
|
19
|
+
- `Verdict: APPROVE at <sha>` when it has none. Minor findings do not block.
|
|
20
|
+
|
|
21
|
+
Priority: trace each finding end to end first. Minor changes no behavior, hides no error and breaks no gate; any other finding is Medium, or High when the report holds its trace, because developers who get false High findings stop listening.
|
|
22
|
+
|
|
23
|
+
## Scope
|
|
24
|
+
|
|
25
|
+
Audit the checked-out branch. Report issues in code its diff adds or modifies, in the unchanged consumers check 2 finds, and in the PR body's claims (check 6), because the author fixes only this diff and the diff never shows them.
|
|
26
|
+
|
|
27
|
+
## Checks
|
|
28
|
+
|
|
29
|
+
1. **Breakage.** Trace each change through its callers and contracts, across packages and modules, because breaks show outside the changed lines.
|
|
30
|
+
2. **Consumers.** For each behavior the diff changes, name its consumers and show that each one still works. Behaviors: log level, status code, exception type, metric or field name, payload shape, identity or uniqueness key, timing, retry, default. Tracing callers misses consumers, many outside the diff, the package or the repository:
|
|
31
|
+
- alert and monitor predicates (a monitor on `status:error` stops when a line goes down to WARNING)
|
|
32
|
+
- log-level contracts, structured-log field names, log-derived metric filters
|
|
33
|
+
- status codes and error-type strings in request logs, webhooks and audit records
|
|
34
|
+
- identity or uniqueness keys that a persistence layer arbitrates on
|
|
35
|
+
- dashboards, SLOs, saved queries, downstream parsers
|
|
36
|
+
|
|
37
|
+
If you cannot find a consumer, say so, because an assumed-away consumer breaks silently. A change that removes its own alarm is High, because it also removes the signal that would catch it.
|
|
38
|
+
3. **Developer experience.** Find changes to how developers run or build the code locally, because no test catches them. Examples: where or how the code reads secrets, new or renamed environment variables, remapped ports or networking, a new script that must run for a feature to keep working. Not a break: a new alternative way to run or build, or a new package-manager dependency, unless it needs a step the README or AGENTS.md does not list, such as a manual install from a website or app store.
|
|
39
|
+
4. **Feature leaks.** Trace each feature flag or internal-only check and its callers, because a leak ships a feature to users a gate excludes.
|
|
40
|
+
5. **Intended breakage.** A high-risk effect the PR body names and bounds (who it affects, how to undo it) is not a defect, because the author chose it. Report one it does not, or one that removes a safeguard or feature gate.
|
|
41
|
+
6. **PR body claims.** Attack each safety or correctness claim in the PR body, because the diff does not show whether a claim in prose is true. Attack these first:
|
|
42
|
+
- Order, not coverage: after a pipeline sanitizes, can any later pass create or recreate what the sanitizer neutralized?
|
|
43
|
+
- An input called safe because another program escapes it depends on that program: rate the finding as if it did not.
|
|
44
|
+
|
|
45
|
+
## Security Guidelines
|
|
46
|
+
|
|
47
|
+
For each row whose surface the diff touches, answer with a file:line citation, because an answer without one cannot be checked.
|
|
48
|
+
|
|
49
|
+
| Tag | If the diff touches… | Answer, with file:line |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| `authz` | an authorization or refusal check, or a new route, command, or tool | who may call it, who may not, where the diff enforces that, and what the unauthorized caller gets |
|
|
52
|
+
| `secret` | a token, grant, secret file, credential helper, or its lifetime | what widened: who can read it, for how long, in which process |
|
|
53
|
+
| `untrusted-input` | a subprocess, argv, path, template, or query built from text an outside party controls (an issue body, a PR comment, a webhook payload, model output) | the boundary that neutralizes it, and whether any later pass can re-create what it neutralized (order, not coverage) |
|
|
54
|
+
| `prompt` | a prompt that embeds untrusted text into an agent's instructions | what delimits the untrusted region, and what the agent may do if it obeys that text (OWASP LLM01 prompt injection, LLM06 excessive agency) |
|
|
55
|
+
| `supply-chain` | a dependency, lockfile, base image, or GitHub Action | the version, the pin (a digest or a SHA checked against its tag), and the permissions the workflow runs with |
|
|
56
|
+
| `sandbox` | a sandbox or pod manifest, a capability, or a network policy | which isolation property changed, and against whom |
|
|
57
|
+
| `agent-def` | an agent definition, skill, role prompt, `.omp/` config, or `AGENTS.md` | whether this diff can steer its own reviewers, and, if so, what a reviewer must check by hand |
|
|
58
|
+
| `transport` | TLS or certificate verification, a signature, an HMAC, a randomness source, or a read or write that untrusted input sizes with no bound | what changed, the check or bound it relies on, and the ASVS identifier it maps to |
|
|
59
|
+
|
|
60
|
+
- Cite an OWASP ASVS v5.0.0 identifier where one applies (`v5.0.0-1.2.5` style), so the author can find it.
|
|
61
|
+
- A security finding with no stated exploit path is hardening, ranked Minor. One that states an exploit path is its own finding at its real priority, so no exploit is filed as optional.
|
|
62
|
+
- Report at most two hardening items, ranked, and put the rest in one paragraph, so they do not bury findings.
|
|
63
|
+
- Start each security finding with its row's tag, `Security[<tag>]:`, so readers can count findings by row.
|
|
64
|
+
- End the report with one `Security:` line, because the Legion reviewer copies it: each touched row's tag and its answer with file:line, or `Security: no sensitive surface in this diff.` when the diff touches none.
|
|
65
|
+
|
|
66
|
+
## Findings
|
|
67
|
+
|
|
68
|
+
- Never report a finding whose open question you can settle by reading code, because the author cannot act on a guess. When you cannot settle it, say what you searched and where.
|
|
69
|
+
|
|
70
|
+
## PR discussion
|
|
71
|
+
|
|
72
|
+
Only after your own audit, so others' findings do not steer it, and only with a Medium or High finding on a branch that has a PR:
|
|
73
|
+
|
|
74
|
+
1. Read the PR/MR's comments and review comments, bots' included, with `gh` or `glab`.
|
|
75
|
+
2. Check their findings in the code: a comment is not evidence. Include the valid ones you missed; for one you share, add their evidence if yours lacks it.
|
|
76
|
+
3. Mark each finding that came from that discussion, so readers can tell it from yours.
|
|
77
|
+
|
|
78
|
+
## A reviewer rates, a lead decides
|
|
79
|
+
|
|
80
|
+
- Rate each finding; the lead disposes of it. Put on the must-fix list only a finding that has to
|
|
81
|
+
be fixed before this change ships, because a list that mixes those with the rest gets filtered
|
|
82
|
+
by nobody.
|
|
83
|
+
- The four dispositions the lead gives a finding are act on, consider, noted and dismissed. Write
|
|
84
|
+
each finding so the lead can place it: the trace, the consumer it breaks, and what it depends on.
|
|
85
|
+
- Do not review a diff you wrote. A reviewer that grades its own work reports no finding against
|
|
86
|
+
it, so hand the diff to a session that did not write it.
|