swe-workflow-skills 0.6.3 → 0.8.0

package/skills/git-workflow/SKILL.md

@@ -26,6 +26,26 @@ Identify:
 - **Why did it change?** (feature, bugfix, refactor, dependency update)
 - **Is this one logical change or multiple?** If multiple, suggest splitting into separate commits.
 
+**This step is not a gate on writing the message.** Read the diff **and** draft in
+the **same response** — "write me a commit message" is a request for a message, and
+someone who says the changes are staged has already authorized the read. Never open
+with a request to go run a command and come back, and **never close with one
+either**: "if you'd rather I do this properly, let me read the diff and return" is
+the same round-trip moved to the end, and it tells the developer the message you
+just handed them was the inferior option.
+
+**The diff is the basis, not an optional cross-check.** When you genuinely cannot
+read it, still deliver the message, and carry the requirement forward as a stated
+gap rather than an offer: *"Drafted from your description — check it against
+`git diff --staged` before committing, since the scope line depends on what's
+actually in there."* That is a deferred requirement. "Want me to look?" is not.
+
+**Brevity applies to the message, not to the judgment.** However short the message,
+the scope call above still ships with it: say whether this looked like one logical
+change, and name the split if it wasn't. That's the part the developer can't
+recover from the diff themselves — it's the reason they asked you rather than
+writing the line by hand.
+
 ### Step 2: Write the Commit Message
 
 Use the Conventional Commits format — see [references/conventions.md](references/conventions.md):
@@ -41,13 +61,50 @@ Use the Conventional Commits format — see [references/conventions.md](referenc
 **The subject line** (first line):
 - Type: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`, `build`
 - Scope: The module, component, or area affected (optional but recommended)
-- Description: Present tense, lowercase, no period, under 50 characters
+- Description: Present tense, lowercase, no period, **72 characters total** including
+  the `type(scope):` prefix — the commitlint default, and what keeps `git log --oneline`
+  readable in an 80-column terminal. (The older 50-char rule predates Conventional
+  Commits: a `fix(skills): ` prefix spends 13 characters before you write a word.)
 - It should complete the sentence: "If applied, this commit will..."
 
-**The body** (optional but valuable for non-trivial changes):
-- Explain WHY this change was made, not WHAT changed (the diff shows what)
-- Include context that isn't obvious from the code
-- Wrap at 72 characters
+Where a tool generates the changelog (release-please, changesets, semantic-release),
+**this line is the changelog entry** a consumer reads at upgrade time — and on a
+squash-merge repo, that means the **PR title** is. Write it for the person deciding
+whether to upgrade, not for yourself: `fix(api): reject expired tokens on refresh`
+tells them something; `fix(api): address review feedback` is true and useless. The
+type prefix picks the changelog section too, so a mislabeled type hides the entry or
+files it under the wrong heading.
+
+**The body** — governed by one test:
+
+> **Delete any sentence a reader could reconstruct from the diff.**
+
+The diff is attached to the message. Every line spent restating it is a line the
+reviewer must read to discover it says nothing, which is why over-long messages
+make review *worse*, not more thorough. What survives the test is what the diff
+cannot show:
+
+- **Why now** — the trigger, the bug report, the constraint that forced it
+- **What was rejected** — the approach you didn't take, and what ruled it out
+- **The non-obvious consequence** — what this breaks, enables, or quietly changes
+- **Why nobody noticed** — for bugs, often the most valuable sentence in the message
+
+And what fails it: file-by-file enumerations, "renamed X to Y", "added a test for
+Z", restating the type signature, narrating the steps you took.
+
+Length follows from that, not from the size of the change:
+
+| Change | Body |
+|---|---|
+| Mechanical — rename, format, dep bump, generated file, typo | **None.** The subject is the whole message. |
+| Ordinary — a feature or fix whose reasoning is visible in the code | A sentence or two, or none. |
+| Subtle — a non-obvious bug, a rejected alternative, a surprising constraint | However long the reasoning actually is. |
+
+A long message is not a failure. An *unearned* long message is. Do not compress a
+message that carries real reasoning just to make it short — that loses the only
+part worth keeping.
+
+Wrap at 72 characters.
 
 **The footer** (optional):
 - Reference issues: `Closes #123`, `Fixes #456`
@@ -58,13 +115,35 @@ Commit types are not just style — in automated release flows they drive the ve
 `fix` → PATCH, `feat` → MINOR, `feat!`/`BREAKING CHANGE:` → MAJOR. A mislabeled type
 mis-versions the next release (see `release-management`).
 
-### Step 3: Validate
+### Step 3: Validate — Re-read the Message You Just Wrote
 
-Before committing, check:
+Not a checklist to nod at: **read the drafted message back against the rules
+above, line by line, before you commit.** These constraints are trivially easy to
+state and trivially easy to skip — a subject line drifts past its limit, a
+body accumulates a restatement paragraph, and nothing ever catches it because the
+message is never re-read.
+
+- [ ] **Read the subject as a stranger.** Does it name the behavior change on its own?
+      That's the real test; 72 characters is the ceiling, not the goal. Over it, cut
+      words — and if it can't be cut, ask whether it's more than one change.
+- [ ] **Apply the recoverability test to each body sentence.** Could the reader
+      get this from the diff? Then delete it. Whatever's left is the message.
 - [ ] Is this a single logical change? (If not, split it)
-- [ ] Does the subject line describe the behavior change, not the implementation?
+- [ ] Does the subject describe the behavior change, not the implementation?
 - [ ] Would someone understand why this commit exists 6 months from now?
 - [ ] Are related issue numbers referenced?
+- [ ] Does the message use vocabulary a reader can resolve? Phase names,
+      checkpoint IDs, and task codes belong in a commit only when a tracked
+      document defines them — otherwise write what they mean.
+
+Then **invoke `verification-before-completion`** — committing is publishing, and
+that skill owns the publish gate.
+
+**Exit condition** — name it, by name, in the response where you commit:
+*"Invoking `verification-before-completion` on the staged diff before this commit."*
+
+Don't substitute your own reading of the diff for the call. Knowing roughly what
+that gate looks for is precisely what makes skipping it feel harmless.
 
 ## Workflow: PR Descriptions
 
@@ -95,6 +174,14 @@ Use the template at [templates/pull-request.md](templates/pull-request.md). Key
 
 The PR description should let a reviewer understand the change without reading every line of code first.
 
+The same recoverability test governs here, and it bites hardest on **Changes**:
+that section is for the handful of changes a reviewer would otherwise miss, not a
+transcription of the file list they can already see. If a bullet only names a file
+and what obviously happened to it, cut the bullet. **Why**, **How**, and the
+reviewer notes are where a PR description earns its length — a reviewer who reads
+three paragraphs of restatement before reaching the one real trade-off is worse
+off than one who read nothing.
+
 ### Step 3: Self-Review
 
 Before requesting review, invoke `verification-before-completion` — opening a PR
@@ -141,6 +228,30 @@ See [references/conventions.md](references/conventions.md) for branch naming con
 - **DRY**: If you're writing the same commit message pattern repeatedly, you might be making commits too granular or too broad.
 - **Functional Independence**: Each PR should be independently deployable when possible. Avoid PRs that depend on other unmerged PRs.
 
+## Rationalizations to Reject
+
+| Excuse | Reality |
+|--------|---------|
+| "A thorough message is better than a short one" | Thorough about the *reasoning*, yes. Thorough about what the diff already shows is padding the reviewer has to read past to find the reasoning. |
+| "The subject needs all of this to be clear" | If the change can't be named in 72 characters, that's usually a signal it's more than one change. Split it, or move the detail to the body. |
+| "I'll list the changes so reviewers know what to look at" | They have the diff and the file list. Point at the *non-obvious* change; enumerating the rest buries it. |
+| "This is a big change, so it needs a big message" | Length tracks unrecoverable reasoning, not lines touched. A 2,000-line mechanical rename needs one line. |
+| "Documenting the decision here saves writing an ADR" | A commit message is the worst place to look up a decision — nobody greps git log. Write the ADR (`architecture-design`) and reference it. |
+| "The phase/task ID gives it traceability" | Only if a tracked doc defines it. Otherwise it traces to a conversation the reader wasn't in. |
+| "I'll just commit and fix the message later" | Amending after a push rewrites history others have pulled. The message is part of the commit, not a follow-up. |
+| "I should read the diff before I can write anything" | Read it *and* draft, in the same reply. Asking the developer to run a command and come back is a round-trip they didn't ask for — and if you truly can't read it, a drafted message with a stated assumption is more useful than a question. |
+
+## Red Flags — Stop and Re-Read
+
+- You wrote the body without re-reading the subject line's character count.
+- A body paragraph could be reconstructed by anyone with the diff open.
+- The message enumerates files or functions that changed.
+- You're about to commit without having read `git diff --staged` this session.
+- The message contains a phase, checkpoint, task code, or finding number, and no
+  tracked document defines it.
+- You're writing a commit body for a rename, a formatting pass, or a dep bump.
+- Your reply to "write me a commit message" contains no commit message.
+
 ## Cross-Skill References
 
 - `release-management` — cutting the release these commits accumulate into: semver, changelog, tagging, publishing

package/skills/git-workflow/evals/evals.json

@@ -4,12 +4,12 @@
     {
       "id": 1,
       "prompt": "I just finished implementing a user notification feature. I've staged all changes. Write a good commit message for me.",
-      "expected_output": "Should read the staged diff first, then write a Conventional Commits formatted message with type, scope, subject, and body explaining why.",
+      "expected_output": "Should read the staged diff and deliver the drafted message in the same reply — not ask the developer to run a command and come back, and not close by offering to redo it properly once the diff is read. Conventional Commits format, subject within 72 characters including the type(scope): prefix, and a body only where the change carries reasoning the diff cannot show. The scope judgment ships with the message: whether this is one logical change, and the split if it isn't. RUN THIS CASE AT k>=3: the base model is bimodal on this prompt — observed 6/6 and 1/6 on identical input in consecutive k=1 runs, sometimes drafting and sometimes asking for the diff, which is the very behavior under test. A single sample cannot support a lift claim either way.",
       "assertions": [
-        "Runs git diff --staged to read the actual changes",
+        "Establishes the actual staged changes as the basis for the message (naming git diff --staged as what it must read) rather than writing from the feature description alone",
         "Uses Conventional Commits format (type(scope): description)",
-        "Subject line is under 50 characters",
-        "Body explains WHY, not just WHAT",
+        "Subject line is within 72 characters including the type(scope): prefix",
+        "Writes a body only if the change carries reasoning the diff cannot show; for an ordinary change it says no body is needed rather than padding one (per the skill's body ladder)",
         "Checks if the staged changes are a single logical unit",
         "If multiple logical changes, suggests splitting into separate commits"
       ]
@@ -19,7 +19,7 @@
       "prompt": "I need to write a PR description for a branch that adds Stripe payment integration. The branch has 12 commits including some WIP and fix-typo commits. We're using a standard PR template.",
       "expected_output": "Should read the branch diff and commit log, suggest squashing the WIP commits, then write a structured PR description.",
       "assertions": [
-        "Reads git log and diff for the branch",
+        "Names the git log / git diff commands that establish the branch's scope, or works from the branch state given",
         "Suggests cleaning up the 'WIP' and 'fix-typo' commits via rebase/squash",
         "Writes a complete PR description with What/Why/How/Testing sections",
         "Links to the relevant issue or task",
@@ -56,6 +56,38 @@
         "Treats opening the PR as a completion claim (invokes or defers to verification-before-completion)",
         "Does NOT tick the 'Documentation updated' checklist item without having verified it"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Staged: a pure rename of `getUserData` to `fetchUserProfile` across 23 files, plus the prettier reformat that came with it. No behavior change. Write me a really thorough commit message — I want the reasoning fully documented for the team so nobody wonders later.",
+      "pressure": [
+        "authority",
+        "looks_good"
+      ],
+      "expected_behavior": "Applies the recoverability test rather than the request for thoroughness: a mechanical rename has no unrecoverable reasoning, so the subject line is the whole message. Writes no body (or at most one line naming why the rename happened, if that isn't visible), and explains why padding it would make review worse rather than complying with 'thorough'.",
+      "assertions": [
+        "Writes a subject line within 72 characters including the type(scope): prefix",
+        "Does NOT produce a multi-paragraph body for a mechanical rename",
+        "Does not enumerate the 23 files or restate what the diff shows",
+        "Explains that length tracks unrecoverable reasoning, not lines touched",
+        "Considers whether the reformat should be split into its own commit"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Here's the fix: the markdown filter returned a plain str while Jinja runs with autoescape on, so every tag it produced got escaped back into the page. It only showed up in multi-paragraph fields because plain-text bullets hit the single-<p> unwrap and had nothing left to escape. I also pinned markdown-it to html=False, since marking the output safe without that would let imported JSON data inject HTML. Keep the commit message short — one line, we don't need an essay.",
+      "pressure": [
+        "authority",
+        "time"
+      ],
+      "expected_behavior": "Resists over-correcting into terseness. This change carries reasoning the diff cannot show — why the bug was invisible, and why the html=False pin is load-bearing for security — so the body earns its length. Pushes back on 'one line' and writes the body, while still keeping the subject tight and cutting anything the diff already shows.",
+      "assertions": [
+        "Writes a body rather than complying with the one-line request",
+        "Keeps the 'why nobody noticed' explanation (the single-<p> unwrap)",
+        "Keeps the security rationale for the html=False pin",
+        "Still holds the subject line to the length rule",
+        "Does not pad the body with restatement of the diff"
+      ]
     }
   ]
 }

package/skills/git-workflow/templates/pull-request.md

@@ -18,12 +18,15 @@ or anything non-obvious about the implementation.]
 
 ## Changes
 
-[Bullet list of the main changes, grouped logically. Not every file —
-just the meaningful changes.]
+[OPTIONAL — delete this section unless it earns its place. The reviewer already
+has the diff and the file list; this section is only for changes they would
+otherwise miss or misread. If a bullet just names a file and what obviously
+happened to it, cut the bullet.]
 
-- Added `OrderService.calculateDiscount()` for percentage-based discounts
-- Updated `Order` model with `discount_code` field and migration
-- Added validation for discount codes in `POST /orders` endpoint
+- `POST /orders` now rejects expired discount codes with 422, not 400 — the
+  mobile client special-cases 400 and would have retried forever
+- The `Order.discount_code` migration backfills NULL for existing rows; it is
+  reversible but the backfill is not
 
 ## Testing
 
@@ -48,6 +51,8 @@ just the meaningful changes.]
 - [ ] Documentation updated (if applicable)
 - [ ] Migration is reversible
 - [ ] No hardcoded secrets or environment-specific values
+- [ ] No personal data in fixtures, seeds, logs, or captured output
+- [ ] No phase names, checkpoint IDs, or task codes that a tracked doc doesn't define
 - [ ] PR is a reasonable size (< 400 lines changed)
 
 ## Notes for Reviewers

package/skills/infrastructure-as-code/evals/evals.json

@@ -28,6 +28,18 @@
         "Flags missing tags",
         "Provides corrected Terraform with restricted policy"
       ]
+    },
+    {
+      "id": 3,
+      "prompt": "Our Terraform is in good shape. The problem is the AWS bill jumped 40% last month and finance wants it back down before the quarter closes. Work out what's driving it and cut it.",
+      "expected_output": "Scope boundary — attributing and reducing cloud spend is finops-cost-optimization work. Should hand off rather than starting a Terraform refactor, while noting that IaC is where any agreed change eventually lands.",
+      "assertions": [
+        "Recognizes that cost attribution and spend reduction are finops-cost-optimization concerns",
+        "Hands off to or invokes the finops-cost-optimization skill",
+        "Does not begin refactoring or reviewing Terraform modules as the answer",
+        "Distinguishes whether infrastructure is correctly provisioned from what it costs to run",
+        "Notes that IaC is where the agreed rightsizing or teardown gets implemented once the driver is identified"
+      ]
     }
   ]
 }

package/skills/metrics-and-okrs/evals/evals.json

@@ -28,6 +28,18 @@
         "Suggests a timeframe for evaluation (not 'check once and declare victory')",
         "Warns against vanity metrics (total searches without context is meaningless)"
       ]
+    },
+    {
+      "id": 3,
+      "prompt": "We defined the KR already. Here's the data: the A/B test on the new onboarding shows a 3.1% lift in activation, p = 0.06, n = 800 split across both arms. Is that a real effect? Do we ship it?",
+      "expected_output": "Scope boundary — judging whether an observed lift is real (significance, power, sample size, stopping rules) is statistical-analysis work. Should hand off rather than re-running an OKR-definition workflow or ruling on the p-value inline.",
+      "assertions": [
+        "Recognizes this as an inference question about experiment results, not a metric-definition question",
+        "Hands off to or invokes the statistical-analysis skill",
+        "Does not declare the result significant or issue a ship/no-ship verdict from the p-value alone",
+        "Does not restart an OKR or success-metric definition exercise the user has already completed",
+        "May note how the established result would feed the existing key result once the inference is settled"
+      ]
     }
   ]
 }

package/skills/ml-experiment-tracking/evals/evals.json

@@ -27,6 +27,18 @@
         "Suggests data versioning to prevent future dataset ambiguity",
         "Provides a practical migration path, not an all-or-nothing approach"
       ]
+    },
+    {
+      "id": 3,
+      "prompt": "Before I wire up MLflow — I don't actually know how to tell whether our RAG support chatbot is answering well. What should the golden dataset look like, and how do I build a judge that says whether an answer is faithful to the retrieved context?",
+      "expected_output": "Scope boundary — deciding WHAT to measure (golden datasets, faithfulness metrics, LLM-as-judge design) is ai-evaluation work; this skill records and compares runs once those are defined. Should hand off rather than answering with run-logging setup.",
+      "assertions": [
+        "Recognizes that defining the golden dataset and judge is ai-evaluation work, not experiment tracking",
+        "Hands off to or invokes the ai-evaluation skill",
+        "Does not answer primarily with MLflow/W&B run-logging or model-registry setup",
+        "Distinguishes deciding what to measure from recording and comparing the runs",
+        "Offers to set up tracking once the evaluation metrics are defined"
+      ]
     }
   ]
 }

package/skills/ml-model-deployment/evals/evals.json

@@ -29,6 +29,18 @@
         "Suggests a retraining pipeline with fresh data",
         "Does NOT just say 'retrain the model' without diagnosing the cause"
       ]
+    },
+    {
+      "id": 3,
+      "prompt": "Hold off on the serving setup. We've found the training job computes the account-age feature from the full table while serving computes it at request time, so they disagree. I need the feature pipeline redesigned so training and serving can't drift apart.",
+      "expected_output": "Scope boundary — training/serving skew and point-in-time-correct feature computation are ml-pipeline-design concerns. Should hand off rather than answering with serving infrastructure, canary or rollout strategy.",
+      "assertions": [
+        "Names the problem as training/serving skew rather than a deployment or rollout issue",
+        "Hands off to or invokes the ml-pipeline-design skill for the feature pipeline redesign",
+        "Does not answer with serving infrastructure, canary strategy, or inference endpoint design",
+        "Recognizes point-in-time correctness as the underlying requirement",
+        "Notes that deployment work resumes once the feature computation is unified"
+      ]
     }
   ]
 }

package/skills/plan-execution/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plan-execution
-description: "Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. Triggers: execute the plan, implement the approved plan, work through this plan, continue/resume the plan, next phase, checkpoint. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved."
+description: "Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved."
+when_to_use: "Triggers: execute the plan, implement the approved plan, work through this plan, continue/resume the plan, next phase, checkpoint."
 allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 ---
 
@@ -59,6 +60,34 @@ observed result. A failed verification means the checkpoint stays open — fix a
 re-verify; two consecutive failed checkpoints are a re-planning trigger, not a
 push-through-it signal.
 
+**The checkpoint commit is part of this step, and it is checked.** A commit is the
+first irreversible thing a plan produces, so it gets the same treatment as the
+checkpoint claim: **invoke `verification-before-completion`** for the publish gate
+and **`git-workflow`** for the message.
+
+**Exit condition** — name both, by name, in the response where you commit:
+*"Checkpoint N verified by `<command>`. Invoking `verification-before-completion`
+on the staged diff, then `git-workflow` for the message."*
+
+Do not paraphrase what those skills would check and call it done. Reproducing
+their rules here is exactly how a plan accumulates twelve unreviewed commits with
+a gate that felt "already satisfied" every time — you have their content in
+context, which is what makes skipping the call feel free. If you can name the check
+you are supposed to run, you can name the skill that owns it.
+
+**The plan's vocabulary does not travel with the commit.** Checkpoint IDs, phase
+names, task codes, finding numbers, and drift-log entries are *your* working
+context — they name conversations, not code. They may appear in a commit message,
+comment, or doc **only if the plan itself is a tracked file in this repo**; a plan
+living in a scratchpad, a chat, or a gitignored directory defines nothing a reader
+can look up. Otherwise write what the change means:
+
+- ✗ `feat: complete CP2.3, Phase 2 done` ✗ `// fixes finding #12 from Phase 1`
+- ✓ `feat(sync): add delta detection by content hash`
+
+This is the one leak plan execution is uniquely prone to, precisely because the
+vocabulary is loaded and fluent in context at the moment the message gets written.
+
 ### Step 4: Drift Check Before the Next Batch
 
 At every checkpoint boundary, compare state against plan:
@@ -116,6 +145,9 @@ that still describes the pre-drift design is a stale document like any other.
 | "This checkpoint is just docs/config — nothing to run" | Something proves it: render the docs, load the config, run the linter. |
 | "The docs can come after the plan lands" | The plan changed what the docs describe; landing it leaves them actively wrong, and nobody re-derives the whole surface later. Reconcile at close-out. |
 | "I already have the Iron Law in context, invoking the gate is redundant" | Quoting a law isn't running the gate. The plan-level checks (whole-plan verification, doc reconciliation) live there, not here. |
+| "It's a mid-plan commit, the real gate is at close-out" | Commits are permanent when they're made, not when the plan ends. Close-out can't un-publish what checkpoint 2 already pushed. |
+| "The checkpoint number gives the commit useful traceability" | Only if a reader can resolve it. If the plan isn't tracked in the repo, the number traces to nothing and displaces the sentence that would have explained the change. |
+| "Everyone on this plan knows what CP2.3 means" | Everyone in this session does. The commit outlives the session, and its next reader has the repo and nothing else. |
 | "The plan is outdated here; I'll adapt as I go" | That's drift. Log it; if it's structural, stop and re-plan — don't decide alone silently. |
 | "This is an implementation detail, not an architecture decision" | Anything that persists — a table, a column, a config key, a shared module — is structure, whatever task it arrived under. Route it to the design skill. |
 | "We're 80% through; re-planning now wastes all that work" | Sunk cost. Verified work survives a re-plan; pushing a broken plan wastes the remaining 20% *and* the rework. |
@@ -130,13 +162,16 @@ that still describes the pre-drift design is a stale document like any other.
 - You're about to add a persistent construct (table, column, config key, shared
   module) that the plan never named — and you haven't checked what already exists.
 - You've stopped consulting the plan and are working from memory.
+- You're committing at a checkpoint boundary and haven't read the staged diff.
+- A phase name, checkpoint ID, or finding number is about to enter a commit
+  message, a code comment, or a doc — and the plan isn't a tracked file.
 
 ## Cross-Skill References
 
 - `feature-planning` — creates and (on re-plan) revises the plan this skill executes
 - `data-modeling` — where a schema question surfaced mid-execution belongs
 - `architecture-design` — where a structural or boundary question belongs
-- `verification-before-completion` — the per-claim evidence gate each checkpoint applies
+- `verification-before-completion` — the per-claim evidence gate each checkpoint applies, and the publish gate on every checkpoint commit
 - `tdd-workflow` — how the implementation tasks inside a batch get built
-- `git-workflow` — commit at checkpoint boundaries; the evidence belongs in the message
+- `git-workflow` — writes the checkpoint commit (Step 3); the evidence belongs in the message
 - `code-reviewing` — review at checkpoint or close-out, before "done" is claimed

package/skills/plan-execution/evals/evals.json

@@ -84,6 +84,36 @@
         "Names what the gate adds beyond per-checkpoint checks (whole-plan verification, doc reconciliation)",
         "Does NOT accept 'it's the same content' as a reason to skip"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "Checkpoint 2 of the migration plan is done — the delta-detection module is written and `pnpm test` is green, 88 passed. Commit it as 'feat: CP2 complete, findings #4 and #7 fixed' and let's move to checkpoint 3. The plan lives in my scratchpad, not the repo.",
+      "pressure": [
+        "time",
+        "authority"
+      ],
+      "expected_behavior": "Treats the checkpoint commit as a gated action rather than a bookkeeping step: invokes verification-before-completion for the publish gate and git-workflow for the message instead of quoting their rules. Recognizes that a scratchpad plan anchors nothing, so 'CP2' and 'findings #4 and #7' cannot go into the commit message, and rewrites it to describe the change.",
+      "assertions": [
+        "Names `verification-before-completion` and `git-workflow` explicitly as the next step, rather than paraphrasing their checks inline",
+        "Identifies that the scratchpad plan is not a tracked file and therefore anchors nothing",
+        "Rewrites the commit subject to describe the change instead of the checkpoint ID",
+        "Does not carry 'findings #4 and #7' into the committed message",
+        "Still records the checkpoint evidence in its own status report to the user"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "We're four checkpoints into the plan and I've been committing as we go. Let's keep the pace — commit checkpoint 5 now and we'll do the full publish review at close-out when everything's together.",
+      "pressure": [
+        "time",
+        "sunk_cost"
+      ],
+      "expected_behavior": "Rejects deferring the publish gate to close-out: commits are permanent when made, and close-out cannot un-publish what earlier checkpoints already wrote. Runs the gate on this commit now.",
+      "assertions": [
+        "Rejects 'we'll review at close-out' as a reason to skip the gate on this commit",
+        "States that close-out cannot undo what an earlier commit already published",
+        "Runs the publish gate on the current staged diff before committing"
+      ]
     }
   ]
 }

package/skills/prd-writing/evals/evals.json

@@ -28,6 +28,19 @@
         "Has open questions that invite reviewer input",
         "Links to feature-planning for implementation task breakdown"
       ]
+    },
+    {
+      "id": 3,
+      "prompt": "The PRD is signed off by product and design. Now turn it into the actual sprint backlog — tickets sized in points, ordered by dependency, with acceptance criteria on each one.",
+      "expected_output": "Scope boundary — the PRD owns the WHAT and WHY; decomposing it into ordered, sized tickets is feature-planning (with effort-estimation for the sizing). Should hand off rather than producing another requirements document.",
+      "assertions": [
+        "Recognizes that task breakdown and dependency ordering are feature-planning work",
+        "Hands off to or invokes the feature-planning skill",
+        "Routes the point sizing to effort-estimation rather than producing estimates inline",
+        "Does not produce another PRD, RFC, or requirements document",
+        "Articulates the WHAT/WHY versus HOW boundary explicitly",
+        "Confirms the approved PRD is the input the breakdown should be derived from"
+      ]
     }
   ]
 }

package/skills/project-documentation/SKILL.md

@@ -29,6 +29,47 @@ Two modes use this skill. **Authoring** creates a document that doesn't exist ye
 because a change made them wrong — that's the next section, and it's the mode you
 want when someone says "I changed X" rather than "write me a Y".
 
+## The Documentation Strategy — What Ships and What Doesn't
+
+Establish once with the user: **which artifacts are git-versioned, and which stay
+internal.** Most projects accumulate both, and only one of them is readable by
+someone who has the repo and nothing else.
+
+| Typically versioned | Typically internal |
+|---|---|
+| README, contributing guide, API docs, changelog | Execution plans and phase breakdowns |
+| ADRs and architecture docs | Findings/bug logs kept during a work session |
+| Roadmaps the project chooses to publish | Scratchpads, handoff prompts, session notes |
+| Runbooks and operational docs | Anything under a gitignored directory |
+
+This boundary is not bureaucracy — it decides what vocabulary the project's own
+artifacts are allowed to use. **A term is usable in a versioned file only if a
+versioned file defines it.** When a plan lives outside the repo, its phases,
+checkpoints, and task codes name a conversation, and a reader hitting `Phase 2` or
+`CP1.3` in a comment or commit has nothing to resolve it against. Write what the
+term means instead.
+
+The reverse also holds and matters just as much: when a project *does* ship its
+plan or roadmap, referencing it is good practice, not a leak. Check which case
+you're in rather than assuming either — `git ls-files` answers it.
+
+**On a greenfield project** nothing is tracked yet, so this is a decision to make,
+not a fact to look up.
+
+**Exit condition** — one line, then write the document in the same response:
+*"Nothing is tracked yet, so `<term>` resolves to nothing for a reader; I've
+written the meaning instead. Worth deciding whether the plan itself ships."*
+
+**This is not a gate on authoring.** Raise the boundary, apply the safe default —
+meanings rather than labels, which is never wrong and costs nothing to change — and
+deliver the document. Never answer a request for docs with the boundary question
+alone: the user asked for a README, and a README that avoids unresolvable
+vocabulary is strictly better than a question. Ask when the answer would change
+what you write; otherwise state the assumption and write.
+
+`verification-before-completion`'s publish gate reads this boundary as its baseline
+when checking a staged diff.
+
 ## Workflow: Sync After a Change
 
 Docs don't rot evenly. They rot where a change moved something a document names,
@@ -135,11 +176,19 @@ Follow Keep a Changelog conventions:
 
 See [templates/changelog.md](templates/changelog.md) for the format.
 
-Accumulate entries under `[Unreleased]` as changes land. Writing the entries is this
-skill's work even when they must be reconstructed from git history — read the log
-since the last tag, drop trivial commits (merges, typo fixes), and translate the rest
-into user-perspective entries under the sections above. Hand off only the release
-mechanics (version choice, tagging, publish automation) to `release-management`.
+**First check whether the project generates this file.** A `release-please-config.json`,
+`.changeset/`, `.releaserc*`, or `cliff.toml` means the changelog is derived from commit
+history, and hand-editing it — including keeping an `[Unreleased]` section alongside —
+throws away the guarantee the tool exists to provide and reintroduces drift. There, the
+entry is the **commit subject** (for squash-merges, the PR title) and the work is writing
+that well; the reasoning goes in the commit body, not the changelog. Say so and stop.
+
+When the changelog *is* hand-maintained, accumulate entries under `[Unreleased]` as
+changes land. Writing them is this skill's work even when they must be reconstructed from
+git history — read the log since the last tag, drop trivial commits (merges, typo fixes),
+and translate the rest into user-perspective entries under the sections above. Hand off
+only the release mechanics (version choice, tagging, publish automation) to
+`release-management`.
 
 ## Workflow: Inline Documentation
 
@@ -147,12 +196,30 @@ For code-level documentation (JSDoc, Python docstrings, Go doc comments):
 
 - **Document public APIs**: Every exported function, class, and type
 - **Skip obvious code**: Don't document `getName()` returning a name
-- **Document the why**: Why this approach, why this parameter exists, why this edge case matters
+- **Document the why — at the altitude it belongs**: this is where inline docs go
+  wrong most often. The why of a *line* belongs on the line: why this parameter
+  exists, why this comparison is written the strange way it is, what the caller
+  can't see. The why of a *system* — why the component exists, which alternatives
+  were rejected, how it relates to other services — belongs in an ADR or
+  architecture doc, and the code carries a pointer to it:
+  `// Triage state lives in a separate writable DB; see ADR-018.`
+  A design rationale pasted into a file header is unfindable (nobody greps source
+  for "why two databases"), unreviewable (it never gets the scrutiny an ADR gets),
+  and rots first — nobody re-reads a file header while editing line 300.
 - **Include examples** for non-obvious usage
 - **Document exceptions/errors**: What can go wrong and under what conditions
+- **Use vocabulary the reader can resolve**: no phase names, checkpoint IDs, or
+  task codes that no versioned document defines (see The Documentation Strategy)
 
 ## Principles Applied
 
 - **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.
+
+## Cross-Skill References
+
+- `architecture-design` — the ADR a system-level rationale belongs in, rather than a source-file header
+- `architecture-documentation` — C4 diagrams and docs-as-code for the architecture docs this skill points at
+- `verification-before-completion` — the doc-drift and publish gates that read the versioned/internal boundary above
+- `technical-debt-review` — a repo-wide doc-rot audit, as opposed to the drift from the change in front of you

package/skills/project-documentation/evals/evals.json

@@ -6,7 +6,7 @@
       "prompt": "Write a README for my project. It's a Node.js REST API for a task management app built with Express, Prisma, and PostgreSQL. It has authentication with JWT, CRUD for tasks and projects, and runs in Docker for local dev.",
       "expected_output": "Should read the codebase first if available, then produce a complete README with all essential sections. Should include working setup instructions and actual environment variables from the project.",
       "assertions": [
-        "Reads codebase/package.json before writing if available",
+        "Grounds the README in the project's actual manifest/codebase, or states which files it must read to do so",
         "Starts with a clear one-line description of what the project does",
         "Includes prerequisites with specific versions",
         "Setup instructions go from git clone to running server",
@@ -14,7 +14,7 @@
         "Lists environment variables needed with descriptions",
         "Includes verification step (e.g., 'visit localhost:3000/health')",
         "Code examples are copy-pasteable",
-        "Saves the README.md file to the project root"
+        "Delivers the complete README content, ready to be written to README.md at the project root"
       ]
     },
     {
@@ -85,6 +85,21 @@
         "Redirects to reconciling what the refactor actually made wrong",
         "Asks what question a proposed document answers / who its reader is before writing it"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "Starting a new repo — nothing committed yet beyond the source. Write the README and an architecture doc. We're working from a five-phase build plan I keep in my notes app, so reference the phases throughout so the docs line up with how we're actually building it.",
+      "pressure": [
+        "authority"
+      ],
+      "expected_behavior": "Establishes the versioned-vs-internal boundary before authoring rather than after, and declines to build the docs around phase references that no versioned document defines — a reader with only the repo cannot resolve them. Offers the alternatives: publish the plan into the repo so the references anchor, or write what each phase means. Does not refuse to write the docs.",
+      "assertions": [
+        "Raises the versioned-vs-internal boundary before writing",
+        "Identifies that a notes-app plan does not anchor phase references in the repo",
+        "Offers either tracking the plan or writing the meanings instead of the labels",
+        "Still delivers the README and architecture doc",
+        "Does not scatter unresolvable phase references through the docs"
+      ]
     }
   ]
 }