swe-workflow-skills 0.2.0 → 0.4.0

package/skills/statistical-analysis/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "skill_name": "statistical-analysis",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We ran an experiment: 2,400 users saw the new checkout flow and converted at 6.8%; 2,350 saw the old one and converted at 5.9%. My PM wants to ship it today — is this difference real? How confident can we be?",
+      "expected_output": "Should treat this as a two-proportion hypothesis test: state the null, run or outline the test with the actual numbers, report a confidence interval on the difference, ask whether the sample size was fixed in advance (peeking), and separate statistical from practical significance before giving a ship recommendation.",
+      "assertions": [
+        "Frames the question as a hypothesis test (two-proportion z-test or equivalent) and states the null hypothesis",
+        "Works the actual numbers given (or sets up the exact computation) rather than answering qualitatively",
+        "Reports uncertainty as a confidence interval on the difference, not only a p-value or a yes/no verdict",
+        "Asks or checks whether the sample size was fixed in advance and flags the peeking/optional-stopping problem",
+        "Distinguishes statistical significance from practical/business significance",
+        "States the assumptions behind the chosen test (independent samples, adequate counts)",
+        "Gives a clear ship/don't-ship framing with the statistical caveats attached"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "We measured 20 different metrics in our experiment and 2 came out significant at p < 0.05. Which ones should we report as wins?",
+      "expected_output": "Should identify the multiple-comparisons problem (about one false positive is expected by chance at that rate), recommend a correction (Holm/Bonferroni or FDR), distinguish pre-registered primary metrics from exploratory ones, and treat the 2 hits as hypotheses for a confirmatory follow-up — not report them as wins.",
+      "assertions": [
+        "Identifies the multiple-comparisons problem explicitly — with 20 tests, roughly one false positive at p < 0.05 is expected by chance",
+        "Recommends a concrete correction (Bonferroni, Holm, or FDR / Benjamini-Hochberg) and notes the trade-off between them",
+        "Warns against reporting the 2 nominal hits as wins (p-hacking / cherry-picking)",
+        "Distinguishes pre-registered primary metrics from exploratory findings",
+        "Recommends treating the surviving hits as hypotheses for a follow-up confirmatory experiment",
+        "Does not simply declare the two significant metrics real effects"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We're about to launch a new system prompt for our support chatbot and want to A/B test it live against the current one to see which gives better answers. Can you set this up?",
+      "expected_output": "Should recognize this as online A/B evaluation of an LLM app and hand off to the ai-evaluation skill for the evaluation design (answer-quality metrics, LLM-as-judge or human feedback, eval gates); statistical-analysis contributes at most the underlying experiment statistics (sample size, significance), not the AI evaluation design.",
+      "assertions": [
+        "Recognizes this as AI-app evaluation territory and hands off to or invokes the ai-evaluation skill",
+        "Raises AI-specific measurement concerns (defining answer quality, LLM-as-judge or human feedback signals) rather than treating it as a pure two-sample statistics problem",
+        "Does not respond with only a generic A/B test design ignoring how answer quality gets measured",
+        "If it retains anything, retains only the experiment statistics (sample size, significance testing) as this skill's contribution"
+      ]
+    }
+  ]
+}

package/skills/strategic-review/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: strategic-review
-description: "Review a project's strategic position before going public, launching, or raising — vision, mission, value proposition, scope positioning, the defensible wedge, and a live competitive / market comparative analysis. Triggers: strategic review, positioning, go public, go-to-market, market analysis, competitive landscape, value proposition, is there a moat, who are our competitors, platform absorption risk, market positioning, comparable products. Use project-review for execution/roadmap/implementation health; delegates deep market scans to deep-research."
+description: "Review a project's strategic position before going public, launching, or raising — vision, mission, value proposition, scope positioning, the defensible wedge, and a live competitive / market comparative analysis. Use project-review for execution/roadmap/implementation health; delegates deep market scans to deep-research."
+when_to_use: "Triggers: strategic review, positioning, go public, go-to-market, market analysis, competitive landscape, value proposition, is there a moat, who are our competitors, platform absorption risk, market positioning, comparable products."
 model: opus
+context: fork
+agent: general-purpose
 allowed-tools: Read, Grep, Glob, WebFetch, WebSearch, Write, Edit
 ---
 
@@ -60,6 +63,9 @@ Survey the field with current evidence, not memory:
   absorb the category.
 - For a deep, multi-source, fact-checked sweep, **delegate to `deep-research`** and
   fold its cited report in. For a lighter pass, use `WebSearch`/`WebFetch` directly.
+  (This skill runs in a forked context — if the `deep-research` skill is not
+  invocable from here, do the lighter pass yourself and note under Open questions
+  that a deep-research sweep is the recommended follow-up.)
 - **Tag each comparable** with its relationship: **competitor**, **complement**,
   or **integration target** — and what it means for this project.
 - Label every finding confirmed-vs-inferred and date it.
@@ -86,8 +92,16 @@ Integrate the above into a decision instrument:
   default is options + a recommendation.
 - **A readiness picture** mapped to the project's own gates, if it has them.
 
+**Write the full review to a file** — default a gitignored path (e.g.
+`.local/strategic-review-<date>.md`) — and state its path in your final summary.
+This skill runs in a forked context: only the summary returns, everything unwritten
+is lost. The summary leads with the thesis verdict and the top weak point.
+Anything that needs the user's judgment (which strategic fork to take, an
+unverifiable market assumption, missing vision docs) goes in an **Open questions**
+section of the report — never silently decided.
+
 For the rendered deliverable (interactive HTML, scorecards, a forks comparison
-panel), hand off to `artifact-design`; default to a gitignored path (e.g. `.local/`).
+panel), hand off to `artifact-design`.
 
 ## Principles Applied
 

package/skills/technical-debt-review/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: technical-debt-review
-description: "Strategic codebase health assessment — identify hotspots, categorize debt, produce remediation roadmap. Triggers: technical debt, tech debt, debt review, codebase health, hotspots, debt assessment, remediation plan, what should we fix first, debt roadmap, code rot, legacy code audit."
+description: "Strategic codebase health assessment — identify hotspots, categorize debt, produce remediation roadmap."
+when_to_use: "Triggers: technical debt, tech debt, debt review, codebase health, hotspots, debt assessment, remediation plan, what should we fix first, debt roadmap, code rot, legacy code audit."
 model: opus
+context: fork
+agent: general-purpose
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
 
@@ -34,7 +37,7 @@ Don't try to review everything. Focus on where pain is concentrated.
 - Tests that only test happy paths (no edge cases, no error cases)
 - Test files significantly longer than the code they test (over-specified tests that break on refactoring)
 
-Ask the user: Where do engineers slow down? What parts of the codebase do people avoid touching? Where do bugs keep appearing?
+If the request came with team pain points (where engineers slow down, code people avoid touching, where bugs keep appearing), weight those hotspots first. This skill runs in a forked context and cannot ask mid-run — when that input is missing, proceed on the code signals above and list "where does the team actually hurt?" under Open questions in the report.
 
 ## Step 2: Categorize by Debt Type and Severity
 
@@ -99,6 +102,13 @@ Output a prioritized action plan:
 
 Use [templates/debt-audit.md](templates/debt-audit.md) for the full audit format.
 
+**Write the full audit to a file** (default a gitignored location, e.g.
+`.local/debt-review-<date>.md`) and state its path in your final summary — this
+skill runs in a forked context: only the summary returns, everything unwritten is
+lost. Judgment calls that need user input (e.g. which subsystem matters most,
+unknown team pain points) go in an **Open questions** section of the report, never
+guessed silently.
+
 ## Principles Applied
 
 - **KISS**: Simplify complexity first — complex code is the root cause of most other debt

package/skills/writing-skills/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: writing-skills
-description: "Use when authoring, editing, or reviewing a skill in this library — a new SKILL.md, one that under-triggers, or hardening an existing one. Covers description and listing-budget rules, frontmatter, progressive disclosure, the 3-eval rule, and pressure-testing against rationalizations. Triggers: write a skill, new skill, edit a skill, skill isn't triggering."
+description: "Use when authoring, editing, or reviewing a skill in this library — a new SKILL.md, one that under-triggers, or hardening an existing one. Covers description and listing-budget rules, frontmatter, progressive disclosure, the 3-eval rule, and pressure-testing against rationalizations."
+when_to_use: "Triggers: write a skill, new skill, edit a skill, skill isn't triggering."
 model: sonnet
 allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 ---
@@ -51,24 +52,31 @@ description over the body, so get it right.
 - **Write WHEN to use, not WHAT it does.** A description that summarizes the
   internal workflow ("reviews code in two passes") triggers worse than one that
   lists situations ("review this PR, check my code before commit").
-- **Our format is a compliant hybrid:** `<when/purpose>. Triggers: <keywords>. <boundary>`.
-  The `Triggers:` list *is* the when-to-use expressed as the phrases a user
-  actually types — keep casting that net wide.
-- **Keep the hybrid format for now** (don't move triggers to `when_to_use` yet):
-  the catalog builder reads only `description`, so the router would lose the
-  trigger phrases. The `when_to_use` migration is a coordinated roadmap change
-  (builder + skills + routing re-baseline together).
-- **~350 chars** for `description` (listing-budget constraint; hard cap 1024).
-  Over budget, the *least-invoked* skills' descriptions drop silently — `/doctor`
-  reports it. See AUTHORING.md "Listing Budget".
+- **The listing is `description` + `when_to_use`.** The `Triggers:` list *is* the
+  when-to-use expressed as the phrases a user actually types — keep casting that
+  net wide. **New skills put it in `when_to_use`; existing skills migrate lazily**
+  (whenever next touched). A migration must be a **pure move**: triggers go to
+  `when_to_use`, the **boundary/delegation instructions STAY in `description`**
+  (they're what steers haiku routing — EVALS.md). The catalog builder concatenates
+  both fields — check with `node scripts/build-plugins.mjs` + `git diff
+  catalog.json` that content is unchanged (a trailing boundary reorders ahead of
+  the triggers; that's fine). No re-baseline needed.
+- **~350 chars** combined listing target (hard caps: `description` 1024, combined
+  1536 — the builder errors above either). Over the listing budget, the
+  *least-invoked* skills' descriptions drop silently — `/doctor` reports it. See
+  AUTHORING.md "Listing Budget".
 - **Anti-pattern:** describing mechanics/steps instead of triggering situations.
 
 ## Structure and budget (brief — see AUTHORING.md for detail)
 
-- Frontmatter: `name`, `description`, `model` (haiku/sonnet/opus by reasoning
-  need), `allowed-tools`. Newer fields where they fit: `when_to_use`,
-  `context: fork` + `agent` (heavy read-only skills), `paths` (file-scoped),
-  `disable-model-invocation` (deliberate-only workflows), `effort`.
+- Frontmatter: `name`, `description`, `when_to_use`, `model` (haiku/sonnet/opus
+  by reasoning need), `allowed-tools`. Newer fields where they fit:
+  `context: fork` + `agent` (heavy report-producing skills — must write the full
+  report to a file and put anything needing user input in an "Open questions"
+  section, since a fork returns only a summary and can't ask the user),
+  `paths` (file-scoped), `disable-model-invocation` (deliberate-only workflows),
+  `effort`. Dynamic `` !`cmd` `` injection: cheap `--stat`-style commands only,
+  `|| true` failure-tolerant — see AUTHORING.md's injection rules.
 - Progressive disclosure: keep SKILL.md tight (aim < 300 lines); push deep
   domain knowledge to `references/`, output formats to `templates/`. On
   compaction only a skill's first ~5k tokens are re-attached — front-load the
@@ -89,11 +97,19 @@ Apply rigor where mistakes are expensive; keep freedom where judgment matters.
   architecture exploration, UX, estimation, proposals. Rigidity there produces
   worse outcomes, not better ones.
 
-## Retiring skills
-
-As base models improve, a skill can become pure overhead. Periodically re-run a
-skill's evals RED (without the skill); if RED ≈ GREEN, slim or retire it rather
-than letting it spend listing budget and re-attachment tokens.
+## Retiring skills (obsolescence review)
+
+As base models improve, a skill can become pure overhead. Once per release cycle
+— or on a major base-model update — re-run the skill's 3 evals RED on shipping
+models via `evals/workflow-runner.mjs`; re-sample ×3 on borderline scores and
+read the judge journal before calling a result variance (a "flaky" case is often
+a real content gap the skill causes). If RED ≈ GREEN across all 3 evals (0/0
+tool-dependent assertion pairs don't count), **slim first** — cut what the model
+does unaided; keep the Iron Law, boundaries, and cross-skill references — then
+re-run GREEN (gate: GREEN ≥ RED per case). Retire only after a slimmed skill
+stays RED ≈ GREEN a full cycle later, with a deprecation notice in
+CHANGELOG/ROLES.md first (removal is user-visible to role and plugin consumers).
+Full policy: docs/AUTHORING.md § Obsolescence review.
 
 ## See also
 

package/uninstall.mjs

@@ -12,7 +12,7 @@
 //   node uninstall.mjs --global         # remove from the user config dir
 //   node uninstall.mjs --dir DIR --dry-run
 
-import { existsSync, statSync, readdirSync, rmSync, rmdirSync } from "node:fs";
+import { existsSync, statSync, readdirSync, readFileSync, rmSync, rmdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -96,16 +96,38 @@ if (!isDir(claudeDir)) {
 
 const settingsLocal = join(claudeDir, "settings.local.json");
 
-// Build the removal list: only library skills present on disk, plus the machinery.
-const libSkills = readdirSync(SKILLS_DIR)
-  .filter((s) => isDir(join(SKILLS_DIR, s)) && isDir(join(dest, s)))
-  .sort();
+// Build the removal list: only library skills THIS installer created, plus the
+// machinery. The provenance manifest is authoritative when present, so a user's own
+// custom skill that shares a library name is never removed. Pre-manifest installs
+// have no manifest — fall back to matching source-tree skill names (the historical
+// behavior) so they can still be uninstalled.
+const manifestPath = join(dest, ".swe-workflow-manifest.json");
+let manifestSkills = null;
+if (existsSync(manifestPath)) {
+  try {
+    const m = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    if (Array.isArray(m.skills)) manifestSkills = m.skills;
+  } catch {
+    /* unreadable manifest -> fall back to name-match below */
+  }
+}
+
+let libSkills;
+if (manifestSkills !== null) {
+  const srcSkills = new Set(readdirSync(SKILLS_DIR).filter((s) => isDir(join(SKILLS_DIR, s))));
+  libSkills = manifestSkills.filter((s) => srcSkills.has(s) && isDir(join(dest, s))).sort();
+} else {
+  libSkills = readdirSync(SKILLS_DIR)
+    .filter((s) => isDir(join(SKILLS_DIR, s)) && isDir(join(dest, s)))
+    .sort();
+}
 
 const targets = [...libSkills.map((s) => join(dest, s))];
 for (const f of [
   join(dest, ".roles.json"),
   join(dest, ".catalog.json"),
   join(dest, ".active-role"),
+  join(dest, ".swe-workflow-manifest.json"),
   join(claudeDir, "hooks", "resolve.mjs"),
   join(claudeDir, "hooks", "session-start.mjs"),
   join(claudeDir, "commands", "role.md"),