swe-workflow-skills 0.11.1 → 0.11.3

package/VERSION

@@ -1 +1 @@
-0.11.1
+0.11.3

package/catalog.json

@@ -253,7 +253,7 @@
     },
     {
       "name": "research-methodology",
-      "description": "Run DS/ML research with defensible claims — framework and rigor, data understood before claims, method decision records, claims traced to evidence, sources verified. Production serving → ml-model-deployment. Triggers: research project, thesis, plan the research track, is this finding solid, can I claim this, why this method, literature review, verify these sources, deep research citations.",
+      "description": "Run DS/ML research with defensible claims — framework and rigor, data understood before claims, method decision records, claims traced to evidence, sources verified, and the write-ups that report them. An experiment or results write-up, even a README, is here, not project-documentation. Production serving → ml-model-deployment. Triggers: research project, thesis, plan the research track, is this finding solid, can I claim this, why this method, literature review, verify these sources, deep research citations, write up the results, experiment README, I can't follow these findings.",
       "path": "research-methodology/SKILL.md"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/skills/project-documentation/SKILL.md

@@ -22,6 +22,9 @@ Identify which documents the project needs based on context:
 | Inline docs (JSDoc/docstrings) | Public APIs, complex logic | Developers reading the code |
 
 Ask the user which they need. If unsure, start with README — every project needs one.
+Every document must answer a question someone actually has, so for each new one
+you propose or are asked for, **ask the user who reads it and what question it
+answers for them**, next to your draft or plan rather than in place of it.
 
 Two modes use this skill. **Authoring** creates a document that doesn't exist yet
 (the four workflows below). **Sync** reconciles documents that already exist
@@ -222,7 +225,7 @@ For code-level documentation (JSDoc, Python docstrings, Go doc comments):
 
 - **KISS**: Write the minimum documentation that makes the project usable. Don't over-document internals.
 - **DRY**: Don't duplicate information across docs. Link between documents instead.
-- **YAGNI**: Don't write architecture docs for a 200-line script. Match documentation depth to project complexity. And don't create docs nobody asked for — a doc that merely restates the code is doc-slop: it goes stale immediately and buries the docs that answer real questions. Every document must answer a question someone actually has.
+- **YAGNI**: Don't write architecture docs for a 200-line script. Match documentation depth to project complexity. And don't create docs nobody asked for — a doc that merely restates the code is doc-slop: it goes stale immediately and buries the docs that answer real questions.
 
 ## Cross-Skill References
 

package/skills/research-methodology/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: research-methodology
-description: "Run DS/ML research with defensible claims — framework and rigor, data understood before claims, method decision records, claims traced to evidence, sources verified. Production serving → ml-model-deployment."
-when_to_use: "Triggers: research project, thesis, plan the research track, is this finding solid, can I claim this, why this method, literature review, verify these sources, deep research citations."
+description: "Run DS/ML research with defensible claims — framework and rigor, data understood before claims, method decision records, claims traced to evidence, sources verified, and the write-ups that report them. An experiment or results write-up, even a README, is here, not project-documentation. Production serving → ml-model-deployment."
+when_to_use: "Triggers: research project, thesis, plan the research track, is this finding solid, can I claim this, why this method, literature review, verify these sources, deep research citations, write up the results, experiment README, I can't follow these findings."
 ---
 
 # Research Methodology
@@ -107,6 +107,22 @@ Write findings at the strength the evidence has:
   only after Step 2's distributions, Step 3's instrument check and the
   confounders are done. Until then it is a provisional observation, worded as one.
 
+**Write each artifact for a reader who wasn't in the session.** An experiment
+README, a results section or a method record is read later by the project owner,
+with nothing else open:
+- **Open with what was found, in plain words**, and what it changes. Provenance
+  (commit, data version, settings) follows the summary; it doesn't lead.
+- **Keep each question, its result and what it means for the project together**,
+  in the same row or paragraph, not a table followed by a separate list of
+  implications.
+- **Define every term and abbreviation where the document uses it**, even when a
+  glossary exists. The glossary is an extra reference, not a substitute, and a
+  definition repeated here is not duplication to remove. A label you can't define
+  (a step code, a decision named by date) is asked about, not left raw.
+- **Revising a dense document adds explanation; it never cuts.** Pre-registered
+  text stays verbatim.
+- Don't add qualifiers the output doesn't carry, such as a CI level or a test name.
+
 Under deadline, write the supported part now and mark the rest provisional. The
 minimal check a striking subgroup claim needs (group counts, per-group metric
 with intervals, one confounder cross-tab) is usually an hour, not a revision.

package/skills/research-methodology/evals/evals.json

@@ -53,6 +53,35 @@
         "Names the minimal data check the roof claim needs (e.g. roof-class counts and recall per stratum with intervals) and says it fits before the deadline",
         "Rejects 'add the data description in the next revision' because a claim drafted without the data check tends to survive into the final text"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Write the Results section of experiments/AE04_matching/README.md from my notebook output below. The project owner reads these between other work and wasn't in the session. Terms are already in docs/glossary.md, so keep it tight.\n\nPre-registered: H1 R@50m >= 0.65 on closed parajes; H2 adding MS to G raises precision by >= 3 pp; H3 eps 100 keeps towns out of HS.\nOutput:\n- H1: R@50m = 0.71 [0.66, 0.76], n_cp = 41 -> supp\n- H2: dPrec(MS u G - G) = +2.1 pp [-0.4, 4.6] -> inconcl\n- H3: eps 100 merges M-masked towns into 39 HS -> not supp; A.7 pending\n- l = 225 m (grid), imposib. excluded per 2026-10-22",
+      "pressure": [
+        "brevity",
+        "glossary_exists"
+      ],
+      "expected_behavior": "Writes the section for a reader who was not in the session: a plain-language summary of what was found first, then each hypothesis with its question, result and meaning for the project together, defining the shorthand where it is used even though a glossary exists, and reporting the inconclusive result as inconclusive with the numbers exactly as given. Recorded from a real project where results written as session shorthand had to be rewritten because the owner could not follow them; without guidance, replies put implications in a separate list and lean on the glossary link.",
+      "assertions": [
+        "Opens with a short plain-language summary of what was found, before the per-hypothesis detail",
+        "For each hypothesis, states the question asked, the result, and what it means for the project, next to each other",
+        "Explains the shorthand where it is used (e.g. R@50m, pp, closed parajes, HS, M, A.7, eps) instead of relying only on the glossary link",
+        "Reports H2 as inconclusive, not as an effect, and keeps every number as given without inventing values"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "I can't follow experiments/AE02_t0_products_eda/README.md. It's about 300 lines: the pre-registration (rules written before the run) comes first, then results as lists of numbers like 'cov@50 = 0.94 (med 6 m); rand 0.05; dCov(MS|G) +5.3 pp [3.3, 7.5] < 5 -> inconcl; FP/HH G 5.0 vs MS 2.65; M share 47-53%'. Each question is about 150 lines from its answer. We also have docs/glossary.md. Fix the README so I can follow it; tell me what you'd change.",
+      "pressure": [
+        "dry_instinct"
+      ],
+      "expected_behavior": "Treats the complaint as too little explanation, not too much text: adds a plain summary and the meaning of each result, keeps definitions inside the README rather than moving them to the glossary, puts each question next to its answer, and leaves the pre-registration verbatim. Recorded from a real project where the first fix moved definitions out to a glossary and the owner objected that the document had been trimmed further.",
+      "assertions": [
+        "Adds explanation (a plain summary, what each result means) rather than shortening or cutting content",
+        "Keeps or adds definitions of terms inside the README itself rather than moving them out to the glossary",
+        "Puts each question next to its answer and its meaning",
+        "Leaves the pre-registration unchanged, or states that it must stay verbatim, while restructuring around it"
+      ]
     }
   ]
 }

package/skills/skill-router/evals/evals.json

@@ -9,7 +9,7 @@
         "Identifies that a dedicated skill / chain applies instead of improvising",
         "Places feature-planning in the chain, and leads with architecture-design where a costly-to-reverse decision dominates",
         "Names the relevant downstream skills (architecture-design, data-modeling) as next steps",
-        "References the New Feature golden path chain"
+        "Orders the work as the New Feature golden path does: planning and the costly-to-reverse design decisions before implementation"
       ]
     },
     {

package/skills/technical-debt-review/evals/evals.json

@@ -30,7 +30,7 @@
     {
       "id": 3,
       "prompt": "There's a 20-line pricing function with a bug in it. Nobody remembers why its discount branch checks the user's timezone, and the last two people who edited it caused regressions somewhere else. Can you fix the bug?",
-      "expected_output": "Recognises this as one targeted fix, not a codebase-wide debt assessment. The obstacle is that the timezone branch's purpose is unknown, so history mining comes before the edit (code-archaeology) and the cleanup itself is refactoring work. Does not produce a hotspot inventory, debt categories, or a remediation roadmap for a single function.",
+      "expected_output": "Recognises this as one targeted fix, not a codebase-wide debt assessment: the fix itself is bug-investigating work. The obstacle is that the timezone branch's purpose is unknown, so history mining comes before the edit (code-archaeology) and the cleanup itself is refactoring work. Does not produce a hotspot inventory, debt categories, or a remediation roadmap for a single function.",
       "assertions": [
         "Recognises this is a single targeted fix rather than a codebase-wide debt assessment",
         "Identifies that the unexplained timezone branch must be understood before it is changed, and refers to code-archaeology or equivalent history mining for recovering why it exists",