write-skills 0.0.0-stage → 0.1.0

package/skills/write-longform/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: write-longform
+description: >
+  Use on an explicit user request for a staged long-form writing mission:
+  collect raw material first, then build a long article or document from it
+  under one shared brief. Not for single-pass replies or edits.
+---
+
+# Write longform
+
+One mission, one brief, staged. Explore first. Exploit second. The user approves every stage.
+
+## Stage 0: the shared brief
+
+Write the brief before any material moves:
+
+1. Topic and working title.
+2. Reader and reader level.
+3. Sources: the pile file, the repo, the links.
+4. Output: the article path and the done condition.
+
+Confirm the brief with the user. Revisit it when a stage changes the mission.
+
+## Stage 1: explore
+
+Interview the user. Mine fragments. No structure yet.
+
+1. Ask questions until the material starts to repeat.
+2. Capture every fragment the user gives, from the first message on.
+3. Append fragments to the pile file. Separate them with a horizontal rule. One H1 working title at the top, nothing else.
+4. A fragment is any text that might survive. Examples: a sharp sentence, a claim with a reason, a vignette, a half-thought, a quote.
+5. A leading word names the idea the piece hangs on. It is the most valuable fragment. When the talk circles one idea, push to coin the word for it.
+6. Re-read the pile from disk before every write. Append, never overwrite. Keep user edits.
+
+## Stage 2: exploit
+
+The pile is now read-only. Commit to a path. The user picks the mode:
+
+- Shape mode: grow the article paragraph by paragraph.
+- Beat mode: grow it as a journey of beats, one move at a time.
+
+Both modes share the grounding rule:
+
+1. List the concepts the reader brings. These are grounded from the start.
+2. A block or a beat may lean only on grounded concepts.
+3. A block or a beat grounds new concepts as it lands.
+4. When the next move needs an ungrounded concept, that gap is the next move. Ground it first.
+
+Shape loop:
+
+1. Read the pile end to end.
+2. Draft 2 or 3 candidate openings, each with a different thesis. The user picks one.
+3. Ask "what does the reader need next?". Pull the answer from the pile.
+4. Argue the format out loud: prose or list, table or text, quote or paraphrase, code block or inline code.
+5. Append each agreed block to the article file at once.
+
+Beat loop:
+
+1. Offer 2 or 3 candidate beats reachable from the grounded set. Name what each beat grounds.
+2. The user picks one. Write only that beat.
+3. Re-read the article from disk. Offer the next set of beats.
+
+End when the journey is complete, not when the pile is empty. Leftover fragments are normal.
+
+## Stage rules
+
+- The pile file is read-only in stage 2.
+- Append each agreed block to the article file at once. Re-read from disk first.
+- The user can ask to rewrite any block or revisit any beat. Edit that piece in place. Leave the rest alone.
+- Stage 1 can restart when the pile runs dry in stage 2. Say what is missing, then go mine it.
+
+## Output language
+
+Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`.

package/skills/write-longform/agents/openai.yaml

@@ -0,0 +1,2 @@
+display_name: Write longform
+allow_implicit_invocation: true

package/skills/write-longform/references/ste.md

@@ -0,0 +1,82 @@
+# Simplified Technical English rules
+
+## Purpose
+
+Write prose that a non-native English reader understands at first read, without guessing. These rules follow the Issue 9 principles of ASD-STE100.
+
+## Scope
+
+Applies to chat replies, commit messages, PR descriptions, documentation, release notes, status updates, and bug reports.
+Does not apply to code identifiers, product UI copy, quoted user text, file paths, and shell commands.
+
+## Writing rules
+
+1. Keep sentences short. Use 20 words or fewer in instructions. Use 25 words or fewer in descriptive text.
+2. Write one instruction, or one topic, per sentence.
+3. Use the active voice. Use the passive voice only when the agent is unknown. Name the agent when you know it.
+4. Write one topic per paragraph. Use 6 sentences or fewer per paragraph.
+5. Use simple verb forms only: simple present, simple past, simple future, imperative, infinitive.
+6. Do not use the "-ing" form of a verb unless it is a technical noun.
+7. Use each word with one meaning only.
+8. Do not use multi-word nouns with more than three words.
+9. Do not use idioms, slang, metaphors, jokes, or cultural references.
+10. Do not use double negatives. Write one clear negative, or write the positive statement.
+11. Do not use contractions. Keep the articles "the" and "a" in sentences.
+12. Use the same word for the same thing. Do not alternate synonyms.
+13. Use vertical lists for data or steps with more than two items.
+14. In procedures, start each step with the command verb. Put warnings before the step.
+15. Split complex text into more sentences. Do not omit the subject or the article to make a sentence shorter.
+
+## Word guidance
+
+- Prefer the shortest common word: "use", not "utilize". Write "start", not "initiate". Write "before", not "prior to".
+- Treat the approved word list of STE, about 900 words, as the target vocabulary. Approximate it with common English words, one sense each.
+- Technical terms are allowed. Define a technical term on first use.
+- Do not invent a new term for a thing you already named.
+
+## Examples
+
+Commit message, before and after:
+
+```text
+Before: "Refactored auth layer to leverage modern async patterns, kicking
+off the long-overdue cleanup of the legacy session nightmare."
+After: "Make the auth module use async functions. Remove the old session
+code. Do not migrate session data. See ticket ABC-123."
+```
+
+Status update, before and after:
+
+```text
+Before: "We're currently experiencing some issues with the deployment
+pipeline, which has been acting up since this morning."
+After: "The deployment pipeline failed at 09:15. The build step gave error
+E403. We are investigating the cause. The next update comes at 14:00."
+```
+
+Bug report, before and after:
+
+```text
+Before: "Users can't seem to export their reports whenever the dataset is
+particularly large. It just silently fails without any error."
+After: "Export fails for datasets larger than 50000 rows. The app shows no
+error. To reproduce: load the sample dataset, click Export, wait 60 seconds."
+```
+
+## Conflicts with other styles
+
+When another active style conflicts with these rules, these rules win for prose. A brief style may shorten sentences further. It keeps every fact, negation, and number.
+
+## Compliance check
+
+- Are all sentences 25 words or fewer?
+- Does each sentence give one instruction or one topic?
+- Is the voice active, except where the agent is unknown?
+- Are there no idioms, jokes, metaphors, contractions, or double negatives?
+- Is every technical term defined on first use, and is each term stable?
+
+## Sources
+
+- https://asd-ste100.org/
+- https://en.wikipedia.org/wiki/Simplified_Technical_English
+- https://github.com/danyuchn/asd-ste100-skill

package/skills/write-pr/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: write-pr
+description: >
+  Use when the agent writes a pull request title or description, or when the
+  user asks for PR text, a PR body, or a reviewable summary of a change.
+---
+
+# Write PR
+
+Write a briefing a reviewer reads in under one minute. Build it from the actual change and the evidence. Never invent evidence.
+
+## Read first
+
+1. Read the full diff of the branch.
+2. Read the linked issue or ticket when one exists.
+3. Read the test output, the build result, or the screenshots that show the change works.
+4. Read recent PR titles in the repo. Match their format.
+
+## Title
+
+- One line, imperative, names the real change. Example: "Add rate limits to the login endpoint".
+- Use the type prefix the repo already uses, when it uses one.
+- Keep 72 characters or fewer.
+
+## Body template
+
+```markdown
+## Summary
+
+What the change does, and why, in 2 or 3 sentences.
+Sketch: file tree, call tree, or diff sketch.
+
+## Evidence
+
+- Before: failing test, error output, or old behavior.
+- After: passing test, output, or new behavior.
+
+## Risk
+
+- Door: one-way or two-way.
+- Blast radius: the parts this change can break.
+```
+
+## Sketch rules
+
+Pick the smallest view that makes the point. One sketch is enough for most changes.
+
+- Show logic as short code or plain steps.
+- Show a file layout change as a shallow tree with one-line comments.
+- Show a control flow change as a diff of the call tree.
+- Show a UI change with a screenshot when the environment allows it.
+
+## Rules
+
+- State what the change does first. State why second.
+- Link long logs and dashboards. Do not paste them.
+- Name the risk honestly. A one-way door gets a warning line in the summary.
+- Write saved text at level 2 or higher. Never use a brief voice here.
+- This block writes text only. It never opens, merges, comments on, or closes a pull request.
+
+## Output language
+
+Write prose in ASD-STE100 Simplified Technical English. The rules live in `references/ste.md`.

package/skills/write-pr/agents/openai.yaml

@@ -0,0 +1,2 @@
+display_name: Write PR
+allow_implicit_invocation: true

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

@@ -0,0 +1,45 @@
+{
+  "skill_name": "write-pr",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write the PR title and description. Branch diff: adds rate limiting to the login endpoint, 3 files, plus a test that floods the endpoint and passes under the limit. Evidence: the flood test fails on main and passes on the branch. The change is easy to roll back.",
+      "expected_output": "An imperative title of 72 characters or fewer naming the real change. A body with the Summary, Evidence, and Risk sections. Evidence shows the before and after states. Risk names a two-way door and the blast radius around the login path.",
+      "assertions": [
+        "Title is imperative and 72 characters or fewer",
+        "Body has Summary, Evidence, and Risk sections",
+        "Evidence shows before and after",
+        "Risk names the door type and the blast radius",
+        "No evidence that was not given is claimed",
+        "Long material is linked, not pasted"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Write the PR title and description. Branch diff: splits the single transport.ts (900 lines) into transport/client.ts and transport/stream.ts with no behavior change. Call sites updated. Tests green on the branch.",
+      "expected_output": "A title for a pure refactor with no behavior change. The summary carries a small sketch of the new file layout as a shallow tree or diff sketch. Evidence cites the green test run. Risk is low: a two-way door with blast radius limited to import sites.",
+      "assertions": [
+        "Title names the refactor without overclaiming behavior change",
+        "Summary includes a file tree or diff sketch",
+        "Evidence cites the test run as given",
+        "Risk section present and honest",
+        "Sketch stays small, one view"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Write the PR title and description. Branch diff: adds a data migration that merges the two user tables into one. The tests are written but have not been run yet, and there is no screenshot or log available.",
+      "expected_output": "The skill writes the PR text without inventing evidence. The Evidence section states plainly that the tests exist but were not run. A one-way door is named for the data migration, with a warning line in the summary.",
+      "assertions": [
+        "Does not fabricate test results or logs",
+        "Evidence section states the gap explicitly",
+        "One-way door named for the migration",
+        "Warning line present in the summary",
+        "Title still states the real change"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/write-pr/references/ste.md

@@ -0,0 +1,82 @@
+# Simplified Technical English rules
+
+## Purpose
+
+Write prose that a non-native English reader understands at first read, without guessing. These rules follow the Issue 9 principles of ASD-STE100.
+
+## Scope
+
+Applies to chat replies, commit messages, PR descriptions, documentation, release notes, status updates, and bug reports.
+Does not apply to code identifiers, product UI copy, quoted user text, file paths, and shell commands.
+
+## Writing rules
+
+1. Keep sentences short. Use 20 words or fewer in instructions. Use 25 words or fewer in descriptive text.
+2. Write one instruction, or one topic, per sentence.
+3. Use the active voice. Use the passive voice only when the agent is unknown. Name the agent when you know it.
+4. Write one topic per paragraph. Use 6 sentences or fewer per paragraph.
+5. Use simple verb forms only: simple present, simple past, simple future, imperative, infinitive.
+6. Do not use the "-ing" form of a verb unless it is a technical noun.
+7. Use each word with one meaning only.
+8. Do not use multi-word nouns with more than three words.
+9. Do not use idioms, slang, metaphors, jokes, or cultural references.
+10. Do not use double negatives. Write one clear negative, or write the positive statement.
+11. Do not use contractions. Keep the articles "the" and "a" in sentences.
+12. Use the same word for the same thing. Do not alternate synonyms.
+13. Use vertical lists for data or steps with more than two items.
+14. In procedures, start each step with the command verb. Put warnings before the step.
+15. Split complex text into more sentences. Do not omit the subject or the article to make a sentence shorter.
+
+## Word guidance
+
+- Prefer the shortest common word: "use", not "utilize". Write "start", not "initiate". Write "before", not "prior to".
+- Treat the approved word list of STE, about 900 words, as the target vocabulary. Approximate it with common English words, one sense each.
+- Technical terms are allowed. Define a technical term on first use.
+- Do not invent a new term for a thing you already named.
+
+## Examples
+
+Commit message, before and after:
+
+```text
+Before: "Refactored auth layer to leverage modern async patterns, kicking
+off the long-overdue cleanup of the legacy session nightmare."
+After: "Make the auth module use async functions. Remove the old session
+code. Do not migrate session data. See ticket ABC-123."
+```
+
+Status update, before and after:
+
+```text
+Before: "We're currently experiencing some issues with the deployment
+pipeline, which has been acting up since this morning."
+After: "The deployment pipeline failed at 09:15. The build step gave error
+E403. We are investigating the cause. The next update comes at 14:00."
+```
+
+Bug report, before and after:
+
+```text
+Before: "Users can't seem to export their reports whenever the dataset is
+particularly large. It just silently fails without any error."
+After: "Export fails for datasets larger than 50000 rows. The app shows no
+error. To reproduce: load the sample dataset, click Export, wait 60 seconds."
+```
+
+## Conflicts with other styles
+
+When another active style conflicts with these rules, these rules win for prose. A brief style may shorten sentences further. It keeps every fact, negation, and number.
+
+## Compliance check
+
+- Are all sentences 25 words or fewer?
+- Does each sentence give one instruction or one topic?
+- Is the voice active, except where the agent is unknown?
+- Are there no idioms, jokes, metaphors, contractions, or double negatives?
+- Is every technical term defined on first use, and is each term stable?
+
+## Sources
+
+- https://asd-ste100.org/
+- https://en.wikipedia.org/wiki/Simplified_Technical_English
+- https://github.com/danyuchn/asd-ste100-skill