write-skills 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/README.md +122 -39
  2. package/THIRD_PARTY_NOTICES.md +8 -1
  3. package/docs/AUDIT.md +4 -4
  4. package/docs/BLOCKS.md +12 -3
  5. package/docs/EVALS.md +24 -1
  6. package/docs/EXPERIMENT.md +341 -0
  7. package/docs/ROUTING-TEST.md +59 -0
  8. package/docs/RULES.md +11 -0
  9. package/docs/STATE.md +88 -0
  10. package/docs/examples.md +133 -35
  11. package/package.json +15 -2
  12. package/skills/help-write/SKILL.md +71 -0
  13. package/skills/{write-core → help-write}/agents/openai.yaml +1 -1
  14. package/skills/help-write/evals/evals.json +26 -0
  15. package/skills/write-adr/SKILL.md +102 -0
  16. package/skills/write-adr/agents/openai.yaml +2 -0
  17. package/skills/write-adr/evals/evals.json +28 -0
  18. package/skills/write-adr/references/local-rules.md +33 -0
  19. package/skills/write-adr/references/ste.md +82 -0
  20. package/skills/write-again/SKILL.md +72 -0
  21. package/skills/write-again/agents/openai.yaml +2 -0
  22. package/skills/write-again/evals/evals.json +28 -0
  23. package/skills/write-again/references/local-rules.md +33 -0
  24. package/skills/write-again/references/ste.md +82 -0
  25. package/skills/{write-core → write-better}/SKILL.md +32 -3
  26. package/skills/write-better/agents/openai.yaml +2 -0
  27. package/skills/{write-core → write-better}/references/ai-patterns.md +12 -0
  28. package/skills/write-better/references/local-rules.md +33 -0
  29. package/skills/write-better/references/reader-load.md +87 -0
  30. package/skills/write-better/references/ste.md +82 -0
  31. package/skills/write-compact/SKILL.md +8 -18
  32. package/skills/write-docs/SKILL.md +16 -0
  33. package/skills/write-docs/references/docs-standard.md +15 -0
  34. package/skills/write-plan/SKILL.md +74 -0
  35. package/skills/write-plan/agents/openai.yaml +2 -0
  36. package/skills/write-plan/evals/evals.json +28 -0
  37. package/skills/write-plan/references/local-rules.md +33 -0
  38. package/skills/write-plan/references/ste.md +82 -0
  39. package/skills/write-pr/SKILL.md +24 -0
  40. package/skills/write-prd/SKILL.md +81 -0
  41. package/skills/write-prd/agents/openai.yaml +2 -0
  42. package/skills/write-prd/evals/evals.json +27 -0
  43. package/skills/write-prd/references/local-rules.md +33 -0
  44. package/skills/write-prd/references/ste.md +82 -0
  45. package/skills/write-ste/SKILL.md +61 -0
  46. package/skills/write-ste/agents/openai.yaml +2 -0
  47. package/skills/write-ste/evals/evals.json +27 -0
  48. package/skills/write-ste/references/local-rules.md +33 -0
  49. package/skills/write-ste/references/ste.md +82 -0
  50. package/skills/write-tldr/SKILL.md +59 -0
  51. package/skills/write-tldr/agents/openai.yaml +2 -0
  52. package/skills/write-tldr/evals/evals.json +27 -0
  53. package/skills/write-tldr/references/local-rules.md +33 -0
  54. package/skills/write-tldr/references/ste.md +82 -0
  55. /package/skills/{write-core → help-write}/references/local-rules.md +0 -0
  56. /package/skills/{write-core → help-write}/references/ste.md +0 -0
  57. /package/skills/{write-core → write-better}/evals/evals.json +0 -0
  58. /package/skills/{write-core → write-better}/references/profile.md +0 -0
@@ -0,0 +1,341 @@
1
+ # Skill experiment, 30 to 31 October 2026
2
+
3
+ Every skill in the set, tested with and without its own rules. The method, the raw before-and-after pairs, and the verdicts.
4
+
5
+ ## Method
6
+
7
+ - 22 skills, one case each, two arms. Control arm: the task prompt only. Skilled arm: the task prompt plus the skill rules. Nothing else in the prompt.
8
+ - Channel 1: fresh subagents of the coding agent, 2 samples of context. One per run, no tools allowed, answer from the prompt only.
9
+ - Channel 2: OpenCode 1.19.5 on the beam-free model, 8 representative skills, run from a clean directory.
10
+ - Both arms of the subagent channel ran with the machine's global Simplified Technical English rules in the system prompt. That raises the control arm's floor. The comparison measures what the skill adds on top of that floor.
11
+ - Grading: against the assertions in each skill's `evals/` folder.
12
+
13
+ One control arm went off prompt and investigated the real repository with tools. That run was discarded and the whole experiment moved to tool-free prompts. The verdicts below are honest about thin separation: where the base model is already good, the report says so.
14
+
15
+ ## Verdict summary
16
+
17
+ | Skill | Verdict | What the skill changed |
18
+ |---|---|---|
19
+ | write-better | Thin pass | Less ceremony, a code example, varied rhythm |
20
+ | write-compact | Clear pass | The exact one-line answer; the control run went off prompt and was invalid |
21
+ | write-tldr | Clear pass | The exact TLDR and Found block |
22
+ | write-again | Clear pass | Named the broken terms, a new analogy, a next step |
23
+ | help-write | Clear pass | Routed to the report skill; the control routed to the issue skill |
24
+ | write-docs | Thin pass | Warning before the action, reader addressing |
25
+ | write-pr | Clear pass | The exact template with sketch, door, blast radius |
26
+ | write-commit | Thin pass | Tighter intent body, less diff narration |
27
+ | write-comments | Clear pass | No restatement; the constraint at the decision line |
28
+ | write-review | Thin pass | Exact path:line format, severity tags, an honest not-checked line |
29
+ | write-jira | Clear pass | Vertical slices, reasoned points, blocking edges |
30
+ | write-issue | Clear pass | Missing facts listed, suspicion labeled |
31
+ | write-release | Thin pass | Internal noise dropped, user-visible effects named |
32
+ | write-report | Clear pass | Answer first, observed and inferred labels, honest risks |
33
+ | write-summary | Clear pass | Gist, decisions with owners, numbers table, open questions |
34
+ | write-handoff | Clear pass | Claim labels, commands block, traps |
35
+ | write-plan | Thin pass | Source labels, marked assumptions, costed options |
36
+ | write-adr | Clear pass | Full record shape with honest costs |
37
+ | write-prd | Clear pass | No invented targets; unknown baselines named |
38
+ | write-longform | Clear pass | Brief as a draft, approval gate, no premature prose |
39
+ | write-glossary | Thin pass | One tight line, no invented features |
40
+ | write-ste | Thin pass | A definition point and a length check on top of an already good control |
41
+
42
+ Score: 13 clear passes, 9 thin passes, 0 failures.
43
+
44
+ ## Before and after, channel 1
45
+
46
+ ### write-better
47
+
48
+ Before (control):
49
+ ```text
50
+ The build failed because of a type check, not a runtime crash.
51
+ ...
52
+ How to fix it:
53
+ 1. Open `src/cart.ts` and go to line 41.
54
+ 2. Find where the string value comes from. Common sources are form
55
+ inputs, URL parameters, and API responses.
56
+ 3. Choose one of these fixes: ...
57
+ ```
58
+
59
+ After (skilled):
60
+ ```text
61
+ The build failed because TypeScript found a type mismatch in `src/cart.ts`
62
+ at line 41.
63
+ ...
64
+ To fix the build, open `src/cart.ts` and go to line 41. ...
65
+ - Remove the quotes, if the value should be a number: `let quantity: number = 3;`
66
+ ...
67
+ If you cannot tell which fix is correct, ask the person who last changed
68
+ that file. The git history (`git blame src/cart.ts`) shows who that is.
69
+ ```
70
+
71
+ Verdict: thin pass. Both arms are clear. The skilled arm drops the "How to fix it" ceremony, shows the wrong code inline, and ends on a next step. The control's structure reads more like homework.
72
+
73
+ ### write-compact
74
+
75
+ The control arm left the prompt: it inspected the real repository with tools and refuted the task's premise. Discarded as invalid. The skilled run:
76
+
77
+ ```text
78
+ The PR 41 migration drops `users.email`. A revert before the next
79
+ release restores it.
80
+ ```
81
+
82
+ Verdict: clear pass. One line, both facts, nothing else.
83
+
84
+ ### write-tldr
85
+
86
+ Before (control):
87
+ ```text
88
+ **TL;DR**
89
+ - Run `scripts/migrate-login.ts` once, then deploy.
90
+ - Rollback is possible before the next release.
91
+ - Side note: the retry helper in `queue.py` counts each failure twice.
92
+ Fix it separately.
93
+ ```
94
+
95
+ After (skilled):
96
+ ```text
97
+ TLDR: Run scripts/migrate-login.ts once, then deploy. Rollback is
98
+ possible until the next release.
99
+ Found: The retry helper in queue.py double-counts failures.
100
+ ```
101
+
102
+ Verdict: clear pass. The control improvised a near-miss format. The skilled arm hit the contract: one TLDR line, one Found line, no advice.
103
+
104
+ ### write-again
105
+
106
+ Before (control): rebuilt with pseudo-code and decoded "pure" and "composable". Sound, but it reused the original framing.
107
+
108
+ After (skilled):
109
+ ```text
110
+ Let me rebuild this from the start. Three terms did the damage:
111
+ "decorator", "pure", and "composable". I will define each one and show
112
+ the steps.
113
+ ...
114
+ **New analogy**
115
+ Think of airport security. You (the handler) are the passenger with one
116
+ job: fly. Each checkpoint is a decorator ...
117
+ **The one-sentence version** ...
118
+ Next step: look at one decorator in the code and name its single job in
119
+ one line.
120
+ ```
121
+
122
+ Verdict: clear pass. The skilled arm names where the read broke, brings a genuinely new analogy, and closes on a next step.
123
+
124
+ ### help-write
125
+
126
+ Before (control): "Route to: **write-issue**." A defensible read, but a pasted stack trace with "tell the team what happened" is an incident explanation, not a filed issue.
127
+
128
+ After (skilled): "Route: **write-report** — a stack trace explained as 'what happened' for the team is an incident-style status report."
129
+
130
+ Verdict: clear pass. The three routing questions picked the right row.
131
+
132
+ ### write-docs
133
+
134
+ Before (control):
135
+ ```text
136
+ Configure the exporter with exporter.json. Use `--reset` only when you
137
+ want to delete all state. Incorrect use of `--reset` can cause data loss.
138
+ ```
139
+
140
+ After (skilled):
141
+ ```text
142
+ You configure the exporter with `exporter.json`. Warning: `--reset`
143
+ forgets all state and can cause data loss. Use `--reset` only when you
144
+ want to forget all state.
145
+ ```
146
+
147
+ Verdict: thin pass. Both cut the filler. The skilled arm puts the warning before the action and addresses the reader.
148
+
149
+ ### write-pr
150
+
151
+ Before (control): improvised sections — What, Why, Test, Rollback. No sketch. The risk framing is a rollback note.
152
+
153
+ After (skilled): the exact Summary, Evidence, Risk template, with a file sketch, a two-way door, and a blast radius line about shared clients behind one address.
154
+
155
+ Verdict: clear pass. The template is the product.
156
+
157
+ ### write-commit
158
+
159
+ Before (control): correct conventional subject plus a body that narrates the diff: "Change the check to `issuedAt < expiry`. ... Update the test to cover the boundary case."
160
+
161
+ After (skilled):
162
+ ```text
163
+ fix(auth): reject tokens at exact expiry
164
+
165
+ A token issued exactly at its expiry time was valid before. Treat it as
166
+ expired, and cover the boundary in the test.
167
+ ```
168
+
169
+ Verdict: thin pass. Both follow the repo format. The skilled body gives the why and stops narrating the diff.
170
+
171
+ ### write-comments
172
+
173
+ Before (control): restated the code twice — "Read the protocol version from byte 0." and "Reject all versions except 2."
174
+
175
+ After (skilled):
176
+ ```js
177
+ // Byte 0 holds the protocol version.
178
+ const version = buf.readUInt8(0);
179
+ // The gateway accepts only version 2; versions 0 and 1 were removed in 2025.
180
+ if (version !== 2) throw new Error('unsupported');
181
+ ```
182
+
183
+ Verdict: clear pass. The restatement is the exact anti-pattern the skill names. The skilled arm keeps one constraint comment at the decision line.
184
+
185
+ ### write-review
186
+
187
+ Before (control): the same three findings, wrapped in bold headers and long sentences.
188
+
189
+ After (skilled):
190
+ ```text
191
+ - src/auth.ts:41 bug. `user` is null on the reset path, so `if
192
+ (user.token)` throws. Check `user` first: use `if (user?.token)` or an
193
+ early null check.
194
+ - src/auth.ts:58 nit. The literal 3 as a retry cap has no name. Extract
195
+ a named constant ...
196
+ - src/auth.ts:41 bug. No test covers the reset path ... Add a test that
197
+ runs the reset path with `user` null.
198
+ Could not check: I did not see the full diff or the file ...
199
+ ```
200
+
201
+ Verdict: thin pass. Same substance; the skilled arm lands the format, the severity tags, and the honest not-checked line.
202
+
203
+ ### write-jira
204
+
205
+ Before (control): layer slices — a data-model story, an endpoint story, one combined mobile story. Points mostly bare, though Fibonacci appeared.
206
+
207
+ After (skilled): outcome epic with out-of-scope, three vertical stories, testable checkboxes, blocking edges, and points with effort, complexity, and uncertainty reasons.
208
+
209
+ Verdict: clear pass. The slice direction is the whole game.
210
+
211
+ ### write-issue
212
+
213
+ Before (control): good structure, but it invented a cause: "the silent failure suggests the export code does not catch or report the error."
214
+
215
+ After (skilled): exact size, format, and console output listed under "The reporter must add these facts", and the cause labeled "Suspected, unconfirmed ... No evidence supports it yet."
216
+
217
+ Verdict: clear pass. The skill's honesty rules are the difference.
218
+
219
+ ### write-release
220
+
221
+ Before (control): kept the refactor and the dependency bump as "Internal Changes".
222
+
223
+ After (skilled): two heads, two sentences, both naming the user-visible effect. Internal noise gone.
224
+
225
+ Verdict: thin pass. The control is close; the skill enforces the drop.
226
+
227
+ ### write-report
228
+
229
+ Before (control): invented an event. "We rolled back 2.6 and latency returned to the old value." The prompt said only that a rollback restores the old plan.
230
+
231
+ After (skilled): answer first, every evidence line labeled observed or inferred, a confidence statement, and a risk the control missed: the plan count could come from stale statistics instead of the PR.
232
+
233
+ Verdict: clear pass. The fabrication is exactly what the labels prevent. One honest note: the skilled arm labeled one line "observed; source: post-rollback test" with a source the prompt never gave. The labels help; they do not replace judgment.
234
+
235
+ ### write-summary
236
+
237
+ Before (control): one accurate paragraph. All facts kept, the open question named.
238
+
239
+ After (skilled): gist line, decisions with owners, a numbers table, open questions as a list.
240
+
241
+ Verdict: clear pass. Same facts, scannable shape.
242
+
243
+ ### write-handoff
244
+
245
+ Before (control): decent sections, but claims stand unmarked and the commands live in prose.
246
+
247
+ After (skilled): every claim labeled verified or not verified, a commands code block, traps with reasons, and an explicit limits note.
248
+
249
+ Verdict: clear pass. The labeling discipline is the product.
250
+
251
+ ### write-plan
252
+
253
+ Before (control): a strong plan — approach, steps with checkable results, rollback, risks. No marked option among alternatives, no out-of-scope, no source labels.
254
+
255
+ After (skilled): source and assumption labels on every fact, three options each with cost, risk, and what it buys, a recommended pick with the reason, steps that each end on a check, risks with early signs, and an out-of-scope list.
256
+
257
+ Verdict: thin pass. The control was already good; the skill adds the approval-facing honesty layer.
258
+
259
+ ### write-adr
260
+
261
+ Before (control): a five-line record. Decision, reason, rejected options. No status, no consequences, no number.
262
+
263
+ After (skilled): the full record — status, context with the numbers and the rejected options with reasons, a one-sentence decision, and consequences that name the costs: a new dependency, a network hop, an outage mode.
264
+
265
+ Verdict: clear pass. The consequences section is the part teams skip.
266
+
267
+ ### write-prd
268
+
269
+ Before (control): invented freely. New targets ("less than 20 percent", "99.9 percent availability"), new scope (email fallback, phases, seven requirement details) that the input never gave.
270
+
271
+ After (skilled): the two goals as given, requirements that restate only the input, and four metrics that say "Baseline: not measured yet." Open questions with unassigned owners.
272
+
273
+ Verdict: clear pass. The no-invention rule is the difference.
274
+
275
+ ### write-longform
276
+
277
+ Before (control): wrote article prose without approval, framed "three problems" from nothing, and used placeholder tokens for numbers.
278
+
279
+ After (skilled): the brief marked "draft, pending your approval", no prose written, and four questions including the path to the notes and the leading word to mine.
280
+
281
+ Verdict: clear pass. The approval gate held.
282
+
283
+ ### write-glossary
284
+
285
+ Before (control): a solid entry, but it invented features: "It also handles authentication, rate limits, and response formatting."
286
+
287
+ After (skilled): one table line — term, definition from the given facts only, merged synonyms with their sources.
288
+
289
+ Verdict: thin pass. Tighter, and nothing invented.
290
+
291
+ ### write-ste
292
+
293
+ Before (control): a good fix with six named violations and rule numbers. The machine's global STE rules already train this.
294
+
295
+ After (skilled): the same violations, plus two points the control missed: define "upstream dependency" on first use, and check the sentence length explicitly.
296
+
297
+ Verdict: thin pass. The skill adds the checklist's last mile.
298
+
299
+ ## Channel 2: OpenCode 1.19.5, the beam-free model
300
+
301
+ Eight representative skills, same cases, run from a clean directory. This channel produced three findings, and one of them changes how the results read.
302
+
303
+ ### Finding 1: the skills fire in a real host
304
+
305
+ OpenCode auto-discovered the installed skills and invoked them on its own. The run logs show `→ Skill "write-adr"`, `→ Skill "write-ste"`, and the local-rules step executing. This confirms in-host discovery, which no prompt test can prove.
306
+
307
+ ### Finding 2: the control arms are contaminated on this channel
308
+
309
+ Because the skills auto-fire, the "control" arm received the skill too. The write-adr control produced a full record shape, and the write-plan control echoed the skill's own example almost verbatim. No control comparison is valid on this channel. The pairs below are qualitative only.
310
+
311
+ ### Finding 3: the local-rules step executed for real
312
+
313
+ The write-prd skilled run opened with a live check, logged by the host:
314
+
315
+ ```text
316
+ === AGENTS.md === NOT FOUND
317
+ === CLAUDE.md === NOT FOUND
318
+ === CONTRIBUTING.md === NOT FOUND
319
+ === GLOSSARY.md === NOT FOUND
320
+ ```
321
+
322
+ It found no local files, continued without comment, and kept the source attribution on the problem statement. That is the synced local-rules block doing its job in a host we do not control.
323
+
324
+ ### Qualitative results, beam-free
325
+
326
+ - write-tldr: the skilled arm hit the exact TLDR and Found block. The control improvised a TL;DR bullet list.
327
+ - write-again: both arms rebuilt well; the skilled arm kept the "new example, same mechanism" shape and closed on a next step.
328
+ - write-prd: the skilled arm separated observed facts from targets, marked unknown baselines, and left open questions with owners.
329
+ - write-better: the skilled arm defined string and number with concrete examples and gave file-and-line next steps.
330
+ - help-write: both arms routed to the report skill.
331
+ - write-ste: both arms named the same violations; the control had already loaded the skill.
332
+
333
+ ### A warning about beam-free itself
334
+
335
+ The model returned a duplicated answer on one run: the write-plan skilled slot received the write-better answer from an earlier turn. beam-free is usable for smoke tests, not for graded comparisons. For graded runs, use a stronger model on the same OpenCode setup.
336
+
337
+ ## What the experiment changed
338
+
339
+ 1. The eval method now has two validated channels, and the prompt-only constraint is part of the fixture.
340
+ 2. In-host firing is proven on OpenCode. The remaining unknown is firing inside this coding agent's own host, which the provider blocked during this experiment.
341
+ 3. The thin passes point at one truth: the machine's global STE rules already lift every control arm. The skills earn their keep where they own a format, gate an approval, or forbid fabrication.
@@ -0,0 +1,59 @@
1
+ # Routing test fixture
2
+
3
+ Run this test with fresh agents before adding a twenty-third skill, and after any description change. Two runs. Compare against the expected answers below.
4
+
5
+ ## Prompt, part A (should fire)
6
+
7
+ Send this to a fresh agent, verbatim:
8
+
9
+ ```text
10
+ You are an agent host with 22 installed writing skills: write-better,
11
+ write-compact, write-tldr, write-again, help-write, write-docs, write-pr,
12
+ write-commit, write-comments, write-review, write-jira, write-issue,
13
+ write-release, write-report, write-summary, write-handoff, write-plan,
14
+ write-adr, write-prd, write-longform, write-glossary, write-ste. Each
15
+ skill has a "Use when" description matching its name. For each task, name
16
+ the one skill that fires, or "none". Format: "FIRE n: name-or-none".
17
+
18
+ 1. Write the PR description for this branch.
19
+ 2. Explain that again, I'm lost.
20
+ 3. Record the decision about the queue as an ADR.
21
+ 4. Give me a TLDR of what you just did.
22
+ 5. Run the test suite and report failures.
23
+ 6. Deploy the staging build.
24
+ 7. Write a plan for migrating the auth service.
25
+ 8. Summarize this 200-line log file.
26
+ 9. Rotate the API key in the vault.
27
+ 10. Which skill should I use to describe this endpoint to the team?
28
+ ```
29
+
30
+ Expected: 1 write-pr, 2 write-again, 3 write-adr, 4 write-tldr, 5 none, 6 none, 7 write-plan, 8 write-summary, 9 none, 10 help-write.
31
+
32
+ ## Prompt, part B (should fire nothing)
33
+
34
+ Send this to a fresh agent, verbatim:
35
+
36
+ ```text
37
+ You are an agent host with the same 22 installed writing skills. For each
38
+ task, answer "OK n" if no skill fires; answer "MISFIRE n: name" if one
39
+ does.
40
+
41
+ 1. Bump the dependency version and run the build.
42
+ 2. Git rebase this branch onto main.
43
+ 3. Print the current git branch and the last commit hash.
44
+ 4. Warm up the application cache.
45
+ 5. Set the git remote to the new URL.
46
+ 6. Close the stale issues older than 90 days.
47
+ 7. Rotate the application logs.
48
+ 8. Scale the worker pool to 4 replicas.
49
+ 9. Vacuum the database and report the table sizes.
50
+ 10. Pin the base image to the new patch version.
51
+ ```
52
+
53
+ Expected: OK for all ten.
54
+
55
+ ## Status
56
+
57
+ - 2026-10-24: 8 descriptions, should-fire only, 16 of 16 over two samples. Recorded in docs/EVALS.md.
58
+ - 2026-10-29: the 22-skill run is pending. The provider refused the subagent dispatch three times in a row. Run the two prompts above and record the verdicts in docs/EVALS.md.
59
+ - 2026-11-07: the 22-skill run is complete. Four fresh subagents, two runs per part, prompts verbatim. 38 of 40 verdicts correct. Part B is clean in both runs: no misfires, so the negative-trigger gate is green. The two part-A misses are over-fires near real boundaries: task 10 fired write-docs instead of help-write, and task 5 fired write-report. Verdict table in docs/EVALS.md. No description change is planned, so no rerun is required.
package/docs/RULES.md CHANGED
@@ -234,3 +234,14 @@ STE, AI-PATTERNS, TERSE, COMPRESS, DOCS, COPY-EDIT, COPY-WRITE, AGENT-DOCS, WORK
234
234
  - Add or change a rule here first. Then change the skill files.
235
235
  - Keep IDs stable. Do not reuse the ID of a deleted rule.
236
236
 
237
+
238
+ ## B. Reader load (write-better)
239
+
240
+ - **B23** `core` Rare pairs: two words that rarely appear together. Rewrite the relationship in plain words. (source: NYU/UT Austin study, 2026)
241
+ - **B24** `core` Long gaps: the subject and its verb sit far apart. Move them together, or split the sentence. (source: same study)
242
+ - **B25** `core` Dropped connectors: a relative clause lost its "that". Put the connector back. (source: same study)
243
+ - **B26** `core` Tacked nouns: three or more nouns in a row. Add the small words that show the relations. (source: same study)
244
+ - **B27** `core` Nouns as verbs: a noun used as a verb. Write the verb phrase. (source: same study)
245
+ - **B28** `core` Things as people: an inanimate thing with a verb of a living being. State the need plainly. (source: same study)
246
+ - **B29** `core` Flipped roles: the tool acts and the human receives. Make the human the actor. (source: same study, user naming)
247
+ - **B30** `core` No announced structure, no section ceremony under 3 sections, no closing summary except the short end-of-turn block. (source: anti-homework rules)
package/docs/STATE.md ADDED
@@ -0,0 +1,88 @@
1
+ # Set state, 2026-11-07
2
+
3
+ The one file that records what this set is. Update it in the same commit as any set change. The mission: the reading experience must never feel like hell.
4
+
5
+ ## The skills (22)
6
+
7
+ | Skill | Role | Trigger | Lines | Example | Eval cases |
8
+ |---|---|---|---|---|---|
9
+ | write-better | Chat answers, explanations, notes | Auto, on any prose task | 172 | yes | 3 |
10
+ | write-compact | The whole reply stays short | Auto, or "brief mode" | 70 | no | 3 |
11
+ | write-tldr | Short block at the end of a long answer | Auto, past 30 lines | 60 | yes | 2 |
12
+ | write-again | Rewrite, explain again, refresh a stale doc | Auto, on "again" or "wait what" | 73 | yes | 2 |
13
+ | help-write | In-chat router to the right skill | On request | 72 | yes | 2 |
14
+ | write-docs | Docs for humans and for agents | Auto, on doc tasks | 116 | no | 3 |
15
+ | write-pr | PR title and body with evidence | Auto, on PR text | 120 | yes | 3 |
16
+ | write-commit | Commit message from diff and history | Auto, on commit text | 55 | yes | 3 |
17
+ | write-comments | Code comments: intent, constraints, traps | Auto, on comment edits | 61 | no | 2 |
18
+ | write-review | Review comments: location, problem, fix | Auto, on review requests | 58 | yes | 2 |
19
+ | write-jira | Jira epics, stories, points (Fibonacci) | Auto, on Jira text | 130 | yes | 3 |
20
+ | write-issue | GitHub issues with repro steps | Auto, on issue text | 68 | yes | 2 |
21
+ | write-release | Release notes from git history | Auto, on release text | 59 | yes | 2 |
22
+ | write-report | Reports: answer first, evidence after | Auto, on report requests | 82 | yes | 2 |
23
+ | write-summary | Summaries that keep decisions and owners | Auto, on summarize | 60 | yes | 2 |
24
+ | write-handoff | Handoff notes for a fresh session | Auto, on handoff | 62 | no | 2 |
25
+ | write-plan | Plans before work starts | Auto, on plan requests | 75 | yes | 2 |
26
+ | write-adr | Architecture decision records (Nygard) | Auto, on ADR requests | 103 | yes | 2 |
27
+ | write-prd | Product requirements with metrics | Auto, on PRD requests | 82 | yes | 2 |
28
+ | write-longform | Staged long-form mission | Explicit request | 99 | yes | 2 |
29
+ | write-glossary | One term per concept | Auto, on glossary work | 58 | yes | 2 |
30
+ | write-ste | Enforce STE, violations named by rule | Auto, on "ste" | 62 | yes | 2 |
31
+
32
+ Evidence notes: four behaviors carry graded run evidence in docs/EVALS.md. They are the pattern sweep, the PR and Jira templates, and the commit process rules. The other skills carry eval cases. Run them before claiming behavior.
33
+
34
+ ## Shared machinery
35
+
36
+ - `shared/ste.md`: the Simplified Technical English rules. Synced into every skill as `references/ste.md`. Enforced by `tools/check.py`.
37
+ - `shared/local-rules.md`: the local-rules step. Synced into every skill as `references/local-rules.md`. Every skill reads AGENTS.md, CLAUDE.md, CONTRIBUTING.md, and GLOSSARY.md first. Local rules beat skill defaults.
38
+ - `<!-- sync:NAME -->` markers: the brief voice, the sentence floor, and the local-rules block exist once in source and one identical copy in every skill. The check fails on drift.
39
+ - `tools/check.py` + `tests/`: frontmatter, links, cross-references, sync regions, privacy blocklist, lint, noreply authors, sizes.
40
+ - `tools/blocklist.txt`: privacy guard. Allows the public handle, bans personal name parts and old names.
41
+
42
+ ## Docs map
43
+
44
+ - `README.md`: the visitor page. Mission, skill table, three example pairs, install.
45
+ - `docs/BLOCKS.md`: the manifest and the set-size cap.
46
+ - `docs/RULES.md`: the rule register with stable IDs, A1 to B30.
47
+ - `docs/EVALS.md`: the behavior evidence and the routing-test results.
48
+ - `docs/AUDIT.md`: the 24-check rubric scores per skill.
49
+ - `docs/EXPERIMENT.md`: the full before-and-after run over all 22 skills.
50
+ - `docs/ROUTING-TEST.md`: the routing fixture with prompts and expected answers.
51
+ - `docs/examples.md`: the before-and-after gallery.
52
+ - `docs/STATE.md`: this file.
53
+
54
+ ## Release history
55
+
56
+ - 0.1.0 (2026-10-24): first eight skills on GitHub and skills.sh.
57
+ - 0.2.0: commit block pruned to process rules, thin-plan rule, evals for every block, trigger routing evidence 16 of 16.
58
+ - 0.2.1: Fibonacci story points with the effort, complexity, uncertainty model.
59
+ - 0.3.0: seven more skills (review, release, issue, summary, handoff, report, glossary), local-rules step in every skill, examples everywhere, 24-check audit.
60
+ - 0.3.1: rich styling rules in write-better, write-docs, write-pr.
61
+ - 0.4.0 (2026-10-29): seven new skills, write-core renamed to write-better, reader-load rules, docs/STATE.md, routing fixture.
62
+ - 0.4.1 (2026-10-29): store-front polish, grouped skill table, badges, why section, npm description and keywords fix.
63
+ - Experiment (2026-10-30 to 31): all 22 skills before-and-after on the subagent channel. 13 clear passes, 9 thin passes, 0 failures. Full pairs in docs/EXPERIMENT.md.
64
+ - Routing test (2026-11-07): the 22-skill fixture ran with four fresh subagents. 38 of 40 verdicts correct; part B clean in both runs. Verdicts in docs/EVALS.md.
65
+
66
+ ## Published channels
67
+
68
+ - GitHub: github.com/adhamhaithameid/write-skills
69
+ - skills.sh: skills.sh/adhamhaithameid/write-skills
70
+ - npm: write-skills (0.3.0 live at the time of writing; the npm token expired. Publish 0.4.1 after `npm login`.)
71
+
72
+ ## Name check, 2026-10-29
73
+
74
+ skills.sh: write-tldr, write-again, help-write, write-adr, write-prd, write-ste, and write-better are free. write-plan exists under another owner (manastalukdar/ai-devstudio); kept, because installs are owner-namespaced.
75
+
76
+ ## Open work
77
+
78
+ - npm publish 0.4.1 (user, after `npm login`; the token expired).
79
+ - Delete the old private repo github.com/adhamhaithameid/writing-skills (user).
80
+
81
+ ## Done, for the record
82
+
83
+ - Eval evidence for all 22 skills: docs/EXPERIMENT.md, 13 clear passes, 9 thin passes, 0 failures.
84
+ - Routing test (2026-11-07): 38 of 40 verdicts correct, part B clean in both runs. Recorded in docs/EVALS.md and docs/ROUTING-TEST.md. The negative-trigger gate for a twenty-third skill is green.
85
+
86
+ ## Held for later
87
+
88
+ - Marketing text modules, language modules beyond English, memory-file compression tools.