write-skills 0.1.0 → 0.2.0

package/docs/EVALS.md

@@ -6,16 +6,26 @@ Date: 24 October 2026. Method: one eval case per skill, run twice in fresh agent
 
 | Skill | Case | Control run | Skilled run | Verdict |
 |---|---|---|---|---|
-| write-commit | 1, simple fix | Correct subject, correct format | Same subject, code block as specified | No separation. The case is too easy for the base model. Cases 2 and 3 in the eval file stay unrun. |
+| write-commit | 1, simple fix | Correct subject, correct format | Same subject, code block as specified | No separation. The case is too easy for the base model. |
+| write-commit | 2, breaking change | Correct subject with "!", body, migration date, ticket, BREAKING CHANGE footer | Same structure, dash bullets, migration step | No separation. The base model knows the breaking-change convention. |
+| write-commit | 3, repo with its own convention | Followed the observed "Area: change" style | Same style, matched the history wording | No separation. Both arms respected the given convention. |
 | write-pr | 1, rate limit change | Improvised sections, invented a justification the input never gave | Exact template: summary with sketch, evidence before and after, door type, blast radius | Clear pass for the skill. |
 | write-jira | 1, attachments plan | Sliced by layer, bare points, no blocking edges | Vertical slices, outcome epic, blocking edges, points with reason lines | Clear pass for the skill. |
+| all blocks | Trigger routing, 8 tasks, 2 samples | 16 of 16 correct, no variance | same | Discovery works from the descriptions alone. |
+| write-commit | Live repo with its own convention | Ignored the observed convention, narrated implementation detail | Read the history, matched it: "Queue: add RetryQueue class" | Clear pass for the process rules. The format spec was pruned in 0.2.0. |
+| write-jira | 3, vague plan, first run | Invented precise targets from nothing | Also invented targets | No separation. Both arms failed the intent. |
+| write-jira | 3, vague plan, after the thin-plan rule | not rerun | Refused to slice, named the missing facts, asked, offered an assumption-marked draft | Fixed and validated. The rule was added in 0.2.0. |
+| write-compact | 1, explain again | Rebuilt well, missed two terms, no next step | Named the break, defined all five terms, ended with a next step | Partial pass for the skill. |
+| write-docs | 1, revise a paragraph | Good revision, warning after the action | Good revision, explicit warning before the action | Thin separation. Both improved the text. |
+| write-comments | 1, comment a function | Acceptable, one restated line | Constraint at the decision line, no restatement | Thin separation. |
 
 ## Reading
 
-- The PR and Jira blocks change behavior in the intended direction. The evidence sits in the table above.
-- The commit block needs its harder cases run before any claim. Case 2, the breaking change, and case 3, the repo with its own convention, are the ones that can separate.
-- No trigger tests exist yet. Every test above inlines the skill text, so it measures the instructions, not the discovery.
-- write-core carries the earlier pattern micro-test from 24 October 2026, in the repository history. The remaining blocks carry no runtime evidence.
+- Every block now carries eval cases in its `evals/` folder. Cases for write-core and write-longform are written but not run.
+- The PR, Jira, and commit blocks change behavior in the intended direction. The commit value sits in the process rules, proven by the live-repo test: read the history first, let the repo convention win.
+- The compact block earns a partial pass. The docs and comments blocks show thin separation on one case each. The base model is already close, and the skill adds placement and ordering discipline.
+- Trigger routing is clean: 16 of 16 in two samples. This test shows the descriptions as written to a host. A real host injects them differently, so in-host firing stays unverified.
+- The vague-plan case exposed a real gap, fixed the same day. The thin-plan rule now stops slicing before the facts arrive, and the rerun proved it.
 
 ## Run more
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "write-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Eight agent skills for writing. Each skill works alone.",
   "license": "MIT",
   "author": "adhamhaithameid",

package/skills/write-comments/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill_name": "write-comments",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Add code comments to this function. Context: byte 0 is the protocol version; version 2 is the only one the gateway still accepts; versions 0 and 1 were removed in 2025. Code: function parseHeader(buf) { const version = buf.readUInt8(0); if (version !== 2) throw new Error('unsupported'); return { version }; }",
+      "expected_output": "Comments state the constraint and the trap: only version 2 accepted, older versions removed. No comment restates the code.",
+      "assertions": [
+        "States the version 2 constraint",
+        "Names the removal fact or date",
+        "No restatement of the code",
+        "Comment sits next to the line it explains"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Review these comments and delete or fix the bad ones: '// increment i by one' above i++; '// TODO: fix this' above a date parser; '// returns the result' above a return statement; '// The API allows 10 calls per second. See ticket 812.' above a retry delay.",
+      "expected_output": "Restatements deleted. The bare TODO gets a reason or goes. The API constraint comment stays.",
+      "assertions": [
+        "Restatements removed",
+        "Bare TODO flagged or replaced with a reason",
+        "Constraint comment kept",
+        "No new narration added"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/write-commit/SKILL.md

@@ -7,37 +7,27 @@ description: >
 
 # Write commit
 
-One change, one commit, one message. The message gives the intent. The diff already shows the what.
+The message gives the intent. The diff already shows the what.
 
 ## Read first
 
-1. Read the staged diff. A commit message describes the staged change, not the plan.
-2. Read the history with `git log --oneline -15`. Match the type words, the scope style, and the capitalization of the repo.
-3. Read the contribution guide when the repo has one. It wins on format.
+1. Read the staged diff. The message describes the staged change, not the plan.
+2. Read the history with `git log --oneline -15`. The history sets the format: the type words, the scope style, the capitalization, the length.
+3. Read the contribution guide when the repo has one. It wins over the history.
 
-## Subject
+The repo convention wins over any default. When the history writes "Area: change", write "Area: change". When the history writes Conventional Commits, write Conventional Commits.
 
-- Format: `type(scope): summary`. The scope part is optional.
-- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`.
-- Imperative mood: "add", not "added" or "adds".
-- Fifty characters or fewer when possible. Seventy-two is the hard cap. No trailing period.
+## Write
 
-## Body
+- One subject line, imperative, the real change. Keep to the length the history uses.
+- Add a body only for what the diff cannot show: a why, a migration path, a linked ticket.
+- A breaking change, a security fix, a data migration, and a revert always get a body.
+- Keep file narration out. The diff lists files.
+- No tool attribution, unless a repo rule requires a trailer.
 
-Skip the body when the subject says it all. Add a body only for:
-
-1. A why the diff cannot show.
-2. A breaking change and its migration path.
-3. A linked issue or a follow-up.
-
-Always add a body for a breaking change, a security fix, a data migration, and a revert. Future debuggers need the context. Wrap the body at 72 characters. Use dash bullets.
-
-## Never
+## Output
 
-- No narration of files the diff already lists.
-- No "I", "we", "now", "this commit".
-- No tool attribution, unless a repo rule requires a trailer. Then add it as a trailer.
-- No emoji, unless the repo history uses them.
+Give one code block, ready to paste. This block writes text only. It never stages, commits, or amends.
 
 ## Example
 
@@ -50,10 +40,6 @@ passed as valid. Compare timestamps as numbers instead.
 Closes #412
 ```
 
-## Output
-
-Give one code block, ready to paste. This block writes text only. It never stages, commits, or amends.
-
 ## Output language
 
 Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`.

package/skills/write-compact/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "write-compact",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Your previous reply was: 'The decorator wraps the handler so the middleware chain stays pure and the retry policy stays composable.' The user answers: 'wait, what? I don't follow.' Rebuild the explanation.",
+      "expected_output": "Explain-again mode: finds where the read broke, defines the failed terms, rebuilds with the missing context, ends with the next step. Not a shorter repetition of the same words.",
+      "assertions": [
+        "Defines the terms that failed: decorator, middleware chain",
+        "Adds the context the reader lacked",
+        "Uses plain constructions and short sentences",
+        "Ends with one next step"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "User says: 'be brief from now on'. Then asks: 'does the migration in PR 41 drop the old column, and is it reversible?'",
+      "expected_output": "Brief mode: answer first, facts exact, no ceremony, full sentences because the answer covers an irreversible action and order matters.",
+      "assertions": [
+        "Answer first",
+        "No greeting, recap, or closing line",
+        "Facts and names exact",
+        "Full sentences where order or safety matters"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Brief mode is on. The user asks for the exact error line from a log that contains: TypeError: Cannot read properties of undefined (reading 'id') at updateCart (cart.ts:88) plus 40 lines of stack.",
+      "expected_output": "One decisive error line quoted exact with file and line, no stack dump, one next step.",
+      "assertions": [
+        "Shortest decisive error line quoted exact",
+        "No stack dump",
+        "One next step"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/write-core/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill_name": "write-core",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Explain to a new team member why the build failed: the CI log says 'error TS2322: Type string is not assignable to type number at src/cart.ts line 41'. They have never used TypeScript.",
+      "expected_output": "Level 1 reply: defines type checking and the error in plain words, gives the fix, one example. No jargon without expansion. Short sentences, active voice.",
+      "assertions": [
+        "Defines the terms a newcomer lacks",
+        "States the fix and the file location",
+        "Sentences short and active",
+        "No AI patterns"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Status update for the channel, level 2, depth 3: the flaky login test was fixed by waiting for the session cookie instead of a fixed sleep. Test run went from 14 failures this week to 0.",
+      "assertions": [
+        "Answer first, then reason, then next step",
+        "Exact numbers kept: 14, 0",
+        "Real symbol and command names",
+        "Report held to a few lines"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Rewrite this reply so it carries no AI patterns: 'In order to boost your productivity, this robust tool leverages cutting-edge caching to deliver a seamless experience that will help you delve into your data like never before.'",
+      "expected_output": "Every banned word and filler removed. The rewrite names what the tool does in plain words.",
+      "assertions": [
+        "No banned vocabulary remains",
+        "No 'in order to', no 'leverage', no 'seamless'",
+        "Names a mechanism or number",
+        "Meaning kept"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/write-docs/SKILL.md

@@ -41,6 +41,13 @@ Jobs stay separate. Split the page and link, rather than mixing.
 11. One thing carries one name across the whole document.
 12. Name the real symbols, paths, flags, and commands. The codebase supplies the words.
 
+## Revise an existing document
+
+1. Read the whole page once before you change a line.
+2. Settle the job of the page. Check every section against that job.
+3. Repair the sentences that break the rules. Leave the sentences that hold.
+4. Do not reword text that did not change. A rewrite of untouched text costs the reviewer time.
+
 ## Rhythm
 
 A page can pass every rule and still read like a machine wrote it.

package/skills/write-docs/evals/evals.json

@@ -0,0 +1,42 @@
+{
+  "skill_name": "write-docs",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Revise this README paragraph: 'Configuration of the exporter is performed via exporter.json. Note that it's important to remember that running with --reset should only be done when you want to forget all state, as data loss may occur if misused.'",
+      "expected_output": "The revision names the real actor and file, puts the condition before the action, cuts the filler, and keeps every fact. Untouched meaning stays in place.",
+      "assertions": [
+        "Real symbol and flag names kept",
+        "Warning placed before the action",
+        "Filler deleted: 'note that', 'it's important to remember'",
+        "Active voice, actor named",
+        "No facts lost"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Plan a short doc page that teaches a newcomer to run their first import with our CLI tool. Choose the document job and outline the page.",
+      "expected_output": "Tutorial job chosen: build-a-thing framing, every step shows a visible result, written as commands. No reference tables or argument sections mixed in.",
+      "assertions": [
+        "Chooses tutorial and says why",
+        "Opens with what the learner ends with",
+        "Steps produce visible results",
+        "No mixed modes"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Write the structure for an agent instruction file that a coding agent reads on every run: how to run tests, what never to commit, and where the domain glossary lives.",
+      "expected_output": "Agent mode: stable headings, steps with checkable end conditions, facts the environment does not show, one meaning in one place.",
+      "assertions": [
+        "Stable headings per topic",
+        "Steps end on checkable conditions",
+        "Points at the glossary location",
+        "No restated rules"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/write-jira/SKILL.md

@@ -15,6 +15,14 @@ Turn a plan into tickets an engineer can pick up without a meeting. Each story c
 2. Read the code area when access exists. Use the domain words of the codebase.
 3. List the slices before you write the tickets. Confirm the list with the user.
 
+## When the plan is thin
+
+A plan without a goal, a number, or a constraint is not a plan yet. Do not slice it.
+
+1. Name what is missing: the user-visible goal, the current numbers, the constraints.
+2. Ask for those facts before you draft. A story with invented targets tests nothing.
+3. When the user wants a draft anyway, mark every invented target as an assumption. Carry every unknown into the points reason.
+
 ## Slice rules
 
 1. One story is one complete path through the stack: data, API, interface, tests.

package/skills/write-longform/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "write-longform",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Start a staged mission on the topic: why our team moved from REST to gRPC. I have a notes file with fragments at notes.md.",
+      "expected_output": "Stage 0 first: a shared brief with topic, reader, sources, output path, and done condition, confirmed with the user. Then the explore interview begins. No article text yet.",
+      "assertions": [
+        "Writes the brief before any material moves",
+        "Asks for confirmation of the brief",
+        "Begins the interview or fragment mining",
+        "Produces no article prose yet"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "In exploit stage, shape mode, the article so far grounded 'streaming' and 'deadline'. The next planned block uses 'backpressure' without grounding it.",
+      "expected_output": "The skill refuses the ungrounded move: it names the gap, grounds backpressure first or moves it earlier, then continues.",
+      "assertions": [
+        "Names the ungrounded concept",
+        "Grounds it before the block leans on it",
+        "Keeps the running grounded list"
+      ],
+      "files": []
+    }
+  ]
+}