@shadowclone/skills 0.0.0-stage → 0.0.29

package/skills/verify-review-findings/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: verify-review-findings
+description: 'Use when a pull request has review comments or bot findings to check. Also use it when the user says "are these comments right?", "triage the review", or "check what the bot found". Checks each finding against the code at the head of the pull request, and confirms the file, the line, and the claim. Asks what each suggested fix would break, reports a verdict for each finding, and waits. Not for writing the fix (use `scope-confirmed-changes`).'
+metadata:
+  shadowclone-category: review
+  shadowclone-section: workflow
+  shadowclone-applies-when: when a pull request has review comments or bot findings
+  shadowclone-voice: "true"
+---
+# Verify Review Findings
+
+## Use when
+
+A pull request has review comments, bot findings, or a list of issues from another agent. A finding is a claim, not a fact. Check each one before you change code or reply.
+
+## Gates
+
+1. Did you read each finding at the head commit of the pull request? A finding about an older commit can be stale.
+2. For each finding, do the file and the line exist, and does the code there do what the finding says?
+3. Can you show the claim with a test, a command, or the code itself? If not, label it as not verified.
+4. Did you ask what each suggested fix would break, such as a caller, a test, or a documented behavior?
+5. Does each finding have a verdict: confirmed, partly right, wrong, stale, or not verified?
+6. Did you wait for the user before you changed code or replied to a reviewer?
+
+## Process
+
+Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it does not exist, build it once from the user's merged pull requests, review comments, and commit messages. Use only text that the user wrote, and name those sources in your handoff. Never overwrite an existing or linked `voice.md`.
+
+1. Fetch the pull request, and check out its head commit. Write down the commit hash.
+2. List each finding in one table, with its source, its `file:line`, and its claim.
+3. For each finding, read the code at that location and its callers. Compare the claim with the real behavior.
+4. When the claim is about behavior, run a focused test or a command that shows it.
+5. For each suggested fix, list what it changes for callers, tests, and users. A fix that is right in one place can break another place.
+6. Give each finding a verdict, with the evidence that supports it.
+7. Put the confirmed findings first, with the highest risk at the top.
+8. Report the table, and wait. Change code or reply only after the user decides.
+
+## Example
+
+**Situation:** A review bot says that a function can return null and crash its caller. It suggests a null check.
+**Easy route:** Add the null check, and reply "Fixed".
+**Hidden cost:** The function never returns null, because a type guard on the line above handles that case. The extra check hides the real contract, and the reply tells the reviewer something false.
+**Best route:** Read the function at the head commit, and run its test with an empty input. Report the finding as wrong, with the line that handles the case.
+**Evidence:** The test with the empty input passed at the head commit. The report quoted the guard at its `file:line` and gave the verdict "wrong".
+
+## Guardrails
+
+- Never change code or post a reply before the user decides.
+- Do not accept a finding because a bot or a senior reviewer wrote it. Do not reject it for that reason either.
+- Quote the code that proves each verdict. Do not paraphrase it.
+- Keep each finding separate. Do not merge two findings into one verdict.
+- A finding that you cannot check stays "not verified" in the report.
+
+## Completion
+
+- The head commit hash that you checked.
+- A table row for each finding: the source, the `file:line`, the claim, the verdict, and the evidence.
+- Each command or test that you ran, with its result line.
+- For each confirmed finding, what its fix changes for callers and tests.

package/skills/write-plain-english/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: write-plain-english
+description: 'Use when writing or editing prose that people read, such as documents, pull requests, commit messages, review comments, chat replies, or skills. Also use it when the user says "make this clearer", "simplify the wording", or "this is a wall of text". Rewrites the text in plain technical English, with one idea in each sentence and no dashes. Then runs a checker that reports long sentences and dashes. Not for checking code behavior (use `verify-and-review`).'
+metadata:
+  shadowclone-category: writing
+  shadowclone-section: workflow
+  shadowclone-applies-when: before you write any text that a person reads
+  shadowclone-voice: "true"
+  shadowclone-always-on: "true"
+---
+# Write Plain English
+
+## Use when
+
+You write or edit any text that a person reads. Examples are a document, a pull request, a commit message, a review comment, a chat reply, and a skill. This skill is always on, so load it before you write.
+
+The rules come from ASD-STE100 Simplified Technical English, at about 80% strictness. Fix every checker error. Fix each warning, or keep it and give a reason. Clarity comes first. If a rule makes the text wrong or unclear, break the rule.
+
+## Gates
+
+1. Does each sentence carry one idea, with 20 words or fewer for an instruction and 25 or fewer for a description?
+2. Is each instruction in the active voice, with the condition before the action?
+3. Do you use one term for one thing, every time?
+4. Is the text free of em dashes and en dashes?
+5. Did you run `scripts/check-ste.mjs` on the text, fix every error, and fix or explain each warning?
+6. Are code, commands, paths, and product names exactly as they were?
+
+## Process
+
+Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it does not exist, build it once from the user's merged pull requests, review comments, and commit messages. Use only text that the user wrote, and name those sources in your handoff. Never overwrite an existing or linked `voice.md`.
+
+1. Put the main point first. Give the reader the result, then the reason.
+2. Use common words that have one meaning. Use a single verb, not a phrasal verb: "start", not "kick off".
+3. Keep the articles "the" and "a". Do not drop words to save space.
+4. Use numbered steps for a procedure, with one action in each step.
+5. Put a condition before its instruction: "If the test fails, read the first error."
+6. Replace each dash with a comma, a period, parentheses, or two sentences. For a range, write "to", as in "2 to 5".
+7. Save the text to a file, and run `node scripts/check-ste.mjs <file>`. If Node is not available, run the script with `bun`. If neither one runs, say that the check did not run.
+8. Fix every error. For each warning, fix it, or keep it and say why the rule makes the text worse.
+
+For a document, also follow these rules:
+
+- Lead with the result. Put the reason and the detail after it.
+- Write one topic in each paragraph.
+- Name each heading for the task or the answer that the reader needs.
+- Use a table to compare options. Use a numbered list for steps.
+- Link to the text that already exists. Do not repeat it.
+
+## Example
+
+**Situation:** A pull request explains a bug in one sentence of 45 words. The sentence joins the symptom, the cause, and the fix with "so" and "which", and it has an em dash.
+**Easy route:** Keep the sentence. It is accurate, and a rewrite takes time.
+**Hidden cost:** Reviewers skim it and miss the cause, so they ask about it in review. The dash also fails the prose check of the repository.
+**Best route:** Split it into three sentences: the symptom, the cause, and the fix. Replace the dash with a period.
+**Evidence:** Before the edit, the checker reported the 45 word sentence and the dash. After the edit, it printed "check-ste: 0 errors, 0 warnings in 1 file".
+
+## Guardrails
+
+- Keep technical terms, identifiers, and quoted text exactly as they are. Do not paraphrase an error message.
+- Do not change the meaning to obey a rule.
+- Do not rewrite text that another person wrote, unless they ask. Suggest the change instead.
+- Do not add filler, praise, or hedging words, such as "robust", "seamless", or "simply".
+- Keep each term the same in the whole document.
+
+## Completion
+
+- The checker command and its summary line, for example `check-ste: 0 errors, 1 warning in 1 file`.
+- Each warning that you kept, with its `file:line` and your reason.
+- The path of the voice file that you read, or the sources that you used to build it.

package/skills/write-plain-english/scripts/check-ste.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+
+const maximumWords = 25;
+const dash = /[\u2013\u2014]/;
+const passive =
+  /\b(?:is|are|was|were|be|been|being)\s+(?:not\s+)?(?:\w+ly\s+)?(\w{3,}(?:ed|en))\b/i;
+const notParticiples = new Set(["often", "even", "seven", "eleven", "token", "listen", "golden"]);
+const phrasalVerbs = [
+  "carry out",
+  "come up with",
+  "end up",
+  "figure out",
+  "find out",
+  "get rid of",
+  "go over",
+  "kick off",
+  "look into",
+  "make use of",
+  "point out",
+  "set up",
+  "take care of",
+  "turn out",
+];
+const vagueWords = [
+  "basically",
+  "etc",
+  "leverage",
+  "numerous",
+  "robust",
+  "seamless",
+  "seamlessly",
+  "simply",
+  "utilize",
+  "various",
+];
+
+function proseLines(text) {
+  const lines = text.split("\n");
+  const prose = [];
+  let fence = null;
+  let frontmatter = lines[0] === "---";
+
+  for (const [index, line] of lines.entries()) {
+    const number = index + 1;
+
+    if (frontmatter) {
+      if (index > 0 && line === "---") {
+        frontmatter = false;
+      }
+
+      const description = /^description:\s*(["']?)(.*)\1\s*$/.exec(line);
+
+      if (description) {
+        prose.push({ number, text: description[2].replace(/''/g, "'") });
+      }
+
+      continue;
+    }
+
+    const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+
+    if (marker) {
+      fence = fence === null ? marker : marker.startsWith(fence) ? null : fence;
+
+      continue;
+    }
+
+    if (fence !== null || /^\s*(?:#|\||$)/.test(line)) {
+      continue;
+    }
+
+    prose.push({
+      number,
+      text: line
+        .replace(/`[^`]*`/g, "Code")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/^\s*(?:[-*]|\d+\.)\s+/, "")
+        .replace(/\*\*([^*]+):\*\*/g, "$1:")
+        .replace(/[*_]/g, ""),
+    });
+  }
+
+  return prose;
+}
+
+function sentencesOf(text) {
+  return text
+    .split(/(?<=[.!?])\s+(?=["'(A-Z0-9])/)
+    .map((sentence) => sentence.trim())
+    .filter((sentence) => sentence.length > 0);
+}
+
+function wordCount(sentence) {
+  return sentence.split(/\s+/).filter((word) => /[A-Za-z0-9]/.test(word)).length;
+}
+
+function checkText(text) {
+  const findings = [];
+
+  for (const line of proseLines(text)) {
+    if (dash.test(line.text)) {
+      findings.push({
+        line: line.number,
+        level: "error",
+        rule: "dash",
+        message: "replace the em or en dash with a comma, a period, parentheses, or the word to",
+      });
+    }
+
+    for (const sentence of sentencesOf(line.text)) {
+      const words = wordCount(sentence);
+      const unquoted = sentence.replace(/"[^"]*"/g, " ");
+      const lower = ` ${unquoted.toLowerCase().replace(/[^a-z0-9' ]+/g, " ")} `;
+      const passiveMatch = passive.exec(unquoted);
+      const passiveWord = passiveMatch?.[1]?.toLowerCase();
+
+      if (words > maximumWords) {
+        findings.push({
+          line: line.number,
+          level: "error",
+          rule: "long-sentence",
+          message: `${words} words, split it to ${maximumWords} or fewer: "${sentence.slice(0, 60)}"`,
+        });
+      }
+
+      if (passiveMatch && passiveWord && !notParticiples.has(passiveWord)) {
+        findings.push({
+          line: line.number,
+          level: "warning",
+          rule: "passive",
+          message: `"${passiveMatch[0]}" may be passive, name who does the action`,
+        });
+      }
+
+      for (const verb of phrasalVerbs.filter((entry) => lower.includes(` ${entry} `))) {
+        findings.push({
+          line: line.number,
+          level: "warning",
+          rule: "phrasal-verb",
+          message: `"${verb}" is a phrasal verb, use a single verb`,
+        });
+      }
+
+      for (const word of vagueWords.filter((entry) => lower.includes(` ${entry} `))) {
+        findings.push({
+          line: line.number,
+          level: "warning",
+          rule: "vague-word",
+          message: `"${word}" is vague, say exactly what you mean`,
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+async function main(files) {
+  if (files.length === 0) {
+    console.error("Usage: check-ste.mjs <file>...");
+
+    return 2;
+  }
+
+  let errors = 0;
+  let warnings = 0;
+
+  for (const file of files) {
+    let text;
+
+    try {
+      text = await readFile(file, "utf8");
+    } catch (error) {
+      console.error(`${file}: cannot read the file (${error.code ?? error.message})`);
+
+      return 2;
+    }
+
+    for (const finding of checkText(text)) {
+      console.log(`${file}:${finding.line}: ${finding.level} ${finding.rule} ${finding.message}`);
+
+      if (finding.level === "error") {
+        errors += 1;
+      } else {
+        warnings += 1;
+      }
+    }
+  }
+
+  const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+
+  console.log(
+    `check-ste: ${plural(errors, "error")}, ${plural(warnings, "warning")} in ${plural(files.length, "file")}`,
+  );
+
+  return errors > 0 ? 1 : 0;
+}
+
+process.exitCode = await main(process.argv.slice(2));