@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

package/src/templates/mate-skills/agents/mate-show-me/SKILL.md

@@ -21,7 +21,7 @@ Explain the current topic visually in a browser-rendered Mate report. Skip the p
 
 ## Subject
 
-- With no argument, explain the current topic or the applied change, as described below.
+- With no argument, review the applied change when the user asks what a change did, or when the conversation is about work in the Working Repository and `git diff` there is not empty; otherwise explain the current topic. When both readings fit, review the change.
 - With an argument naming a spec capability (`$ARGUMENTS`, for example `acme-capability`), explain that capability instead: read its canonical spec under `openspec/specs/` in the Companion Repository and report its purpose, its requirements, and the flow or structure they establish. Name the capability in the report `metadata`, include a `diagram` section, and omit the `diff` section.
 - When the named capability has no canonical spec, say so, suggest close capability names from `openspec/specs/`, and write nothing: no report, no file.
 
@@ -89,6 +89,18 @@ src/
 
 - Show a whole block in the report when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape.
 
+## Reviewing An Applied Change
+
+- Read the change scope before drawing it, and draw the state after the change, not the one it replaced.
+- Decide the diagram by what the change did. When it alters control flow or behaviour - new or changed branches, calls, ordering, return paths, or error handling - the first diagram is a `flowchart TD` of the resulting flow, limited to the part the change touches. A rename, a move, or an extraction that keeps behaviour identical gets one structure diagram and no flowchart.
+- Mark new steps `added` and modified steps `changed`. Removed steps normally do not appear, since the diff shows what was there before; when removing a step is the point of the change, keep it as a `removed` node.
+- When most of the drawn flow is new, marking every step carries no signal: mark at most the entry step `added`, and say in the caption that the flow is new.
+- Keep a flowchart to about twelve nodes. Collapse a run of steps the change did not touch into one node instead of splitting the flow across several diagrams.
+- When the change also alters structure - types, modules, or ownership - follow the flowchart with a structure diagram such as a `classDiagram`. A report carries at most two `diagram` sections, flowchart first, each with its own `caption`.
+- Take the diff from `git diff` in the Working Repository. Keep only repository-relative paths in the patch, default to the working tree, and ask the user when their intent is a committed range instead.
+- Run `git diff --numstat` over the same scope before choosing between the full diff and a curated report. Every excerpt is whole hunks copied unchanged from that diff.
+- When the inspected scope has no changes, say so and omit the `diff` section. Never invent a patch.
+
 ## Browser Delivery
 
 The report is mandatory. Prefer `mate report --input <temporary-json-file>` without `--json` so the CLI reads the complete document reliably and renders self-contained HTML. The CLI chooses the surface: inside a Studio terminal it hosts the report in Studio, elsewhere it opens it in the default browser. The CLI also supports `mate report --input -` when JSON is piped to stdin; if stdin delivery reports empty or truncated JSON, switch to a temporary JSON file rather than retrying the same transport. If validation fails, fix the report document and retry; do not fall back to an inline explanation or JSON-only delivery.
@@ -105,19 +117,33 @@ Build a JSON document that conforms to the `mate-create-report` contract, then h
 A report assembled by this skill carries:
 
 - `metadata` naming the subject and a neutral repository label, never a local path
-- one `diagram` section for the structure or flow at issue, even when the visual is small
+- `diagram` sections, even when the visual is small: one for a topic or capability report, one or two for a change review as Reviewing An Applied Change describes
 - use a `mermaid` payload for runtime control flow, call trees, data flow, or component relationships; use `text` only when a sketch or pseudocode is clearer
-- one `diff` section carrying the unified diff, when there is something to diff
-- a short `text` section next to each visual, saying what the reader should notice
+- what changed, when there is something to diff: the complete unified diff in one `diff` section for a small change or when the user asks for it, otherwise a curated overview and excerpts as described in Curating A Large Diff
+- a short Markdown `caption` on each `diagram` and `diff` section, saying what the reader should notice; do not repeat it in a separate `text` section
+- a `text` section only for explanation that belongs to no single visual, with `"format": "markdown"` when it uses Markdown
+
+A `diagram` section carries exactly one payload: `mermaid` for diagram source the report draws as a picture, or `text` for a monospace ASCII sketch or pseudocode block. A `diff` section carries a unified `patch` string. Both take an optional `caption`, rendered beneath the visual with the Markdown subset described in `mate-create-report`.
+
+```json
+{
+  "id": "flow",
+  "title": "Saving a document",
+  "type": "diagram",
+  "mermaid": "flowchart TD\n  save[save] --> check{unchanged?}\n  check -->|yes| cached[return cached]\n  check -->|no| write[write content]\n  class check,cached added\n  class write changed",
+  "caption": "Unchanged content now **returns early** instead of being rewritten."
+}
+```
 
-A `diagram` section carries exactly one payload: `mermaid` for diagram source the report draws as a picture, or `text` for a monospace ASCII sketch or pseudocode block. A `diff` section carries a unified `patch` string.
+When a change also alters structure, the second `diagram` section is a structure diagram:
 
 ```json
 {
   "id": "structure",
   "title": "Report rendering",
   "type": "diagram",
-  "mermaid": "classDiagram\n  Renderer --> Highlight : uses"
+  "mermaid": "classDiagram\n  Renderer --> Highlight : uses",
+  "caption": "`Renderer` is the only caller of `Highlight`."
 }
 ```
 
@@ -126,23 +152,55 @@ A `diagram` section carries exactly one payload: `mermaid` for diagram source th
   "id": "changes",
   "title": "What changed",
   "type": "diff",
-  "patch": "diff --git a/src/acme.ts b/src/acme.ts\n..."
+  "patch": "diff --git a/src/acme.ts b/src/acme.ts\n...",
+  "caption": "Validation moves **before** rendering."
 }
 ```
 
 If the document fails contract validation, report the diagnostic and correct the document. Do not fall back to hand-written HTML.
 
+## Curating A Large Diff
+
+The reader already has the full diff in git; the report earns its place by choosing what is worth looking at.
+
+- Measure first. Run `git diff --numstat` over the inspected scope and add the added and removed lines of every file; binary files count as zero.
+- At or under 150 changed lines, or whenever the user asks for the full diff, include the complete unified diff in one `diff` section, whatever its size.
+- Above 150 changed lines, curate:
+  - one `table` section with id `changed-files` and the columns File | Added | Removed | Role, listing every changed file in the scope, including tests, snapshots, and generated files. Added and Removed are numbers; Role is a short phrase such as "contract: optional fields" or "snapshot hashes".
+  - one to four focused `diff` sections with ids such as `diff-<topic>`, each making one point and carrying a `caption` that says why its hunks matter. Keep each section under about 60 lines.
+  - a `summary` metric labelled "Changed lines shown" with the value `<shown> of <total>`, where shown counts the `+` and `-` lines in the excerpts and total is the `--numstat` sum.
+- Excerpts stay verbatim. A focused patch is the file's `diff --git`, `---`, and `+++` header followed by one or more whole hunks copied unchanged from `git diff`. Never alter, merge, or invent hunk lines, and never elide lines with `...`. Two hunks of the same file may share a section when they make the same point.
+- Leave supporting files out of the excerpts: tests (`*.test.*`, `*.spec.*`, `__tests__/`), snapshots (`__snapshots__/`, `*.snap`), lockfiles (`bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`), generated files (`*.generated.*`), and formatting-only hunks. They still appear in the `changed-files` table. Excerpt them when the change is about them or the user asks for them.
+
+```json
+{
+  "id": "changed-files",
+  "title": "Changed files",
+  "type": "table",
+  "columns": ["File", "Added", "Removed", "Role"],
+  "rows": [
+    ["src/report/contract.ts", 48, 6, "contract: optional fields"],
+    ["src/report/renderer.test.ts", 210, 95, "tests"]
+  ]
+}
+```
+
+```json
+{
+  "id": "diff-contract",
+  "title": "Contract gains optional fields",
+  "type": "diff",
+  "patch": "diff --git a/src/report/contract.ts b/src/report/contract.ts\n--- a/src/report/contract.ts\n+++ b/src/report/contract.ts\n@@ -40,6 +40,8 @@\n...",
+  "caption": "New fields are **optional**, so existing documents still validate."
+}
+```
+
 ## Mermaid Authoring Rules
 
 - Use Mermaid whenever the user asks for a diagram or the subject has meaningful control flow, sequencing, lifecycle, or relationships. A `text` payload is a deliberate fallback, not the default for runtime flows.
-- Pick the diagram type that matches the question: `classDiagram` for structure, `sequenceDiagram` for interaction between components, `stateDiagram-v2` for lifecycles, `flowchart TD` for control flow and call trees.
-- Keep labels short enough to read at report width. A label that needs a sentence belongs in the neighbouring `text` section.
+- Pick the diagram type that matches the question: `classDiagram` for structure, `sequenceDiagram` for interaction between components, `stateDiagram-v2` for lifecycles, `flowchart TD` for control flow and call trees. For a change review, Reviewing An Applied Change decides the diagram instead.
+- Keep labels short enough to read at report width. A label that needs a sentence belongs in the section's `caption`.
 - Do not use ELK-only layouts or math labels. The report loads the single-file mermaid build from a CDN, which does not carry those chunks.
-- Pair each Mermaid visual with a short neighbouring `text` section that calls out the ownership boundary or invariant the reader should notice.
+- To mark nodes, apply the report's theme classes `added`, `changed`, or `removed` with `class a,b added` or `a:::added`. They follow the reader's colour scheme. Never fix a colour with `classDef`, `style`, or `linkStyle`: a fill picked for a white page hides the labels in dark mode, so the dark copy drops those lines.
+- Give each Mermaid visual a short `caption` that calls out the ownership boundary or invariant the reader should notice.
 - Prefer the `text` payload for pseudocode, shallow file trees, or cases where a picture would genuinely obscure the point.
-
-## Reviewing An Applied Change
-
-- Read the change scope before drawing it, then diagram the structure or flow the change establishes - not the structure it replaced.
-- Take the diff from `git diff` in the Working Repository. Keep only repository-relative paths in the patch, default to the working tree, and ask the user when their intent is a committed range instead.
-- When the inspected scope has no changes, say so and omit the `diff` section. Never invent a patch.

package/src/templates/mate-skills/agents/mate-simplify-code/SKILL.md

@@ -19,21 +19,12 @@ Simplify code by reducing complexity while preserving exact behavior. The goal i
 
 - Inspect the requested scope and its callers, callees, and tests before editing. Use the available code-graph tools before broad source scans.
 - Keep the refactor limited to the requested scope; do not make unrelated cleanup changes.
-- Run the relevant tests after each simplification. Do not modify tests merely to make a refactor pass.
+- Do not modify tests merely to make a refactor pass.
 - Format touched files with the project's own formatter — detect it first (see Principle 2); never run a formatter the project has not adopted.
 - Run `mate cap index --tokensave` after code changes.
 - Never commit, push, or create a pull request unless the user explicitly asks.
 
-## When to Use
-
-- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
-- During code review when readability or complexity issues are flagged
-- When you encounter deeply nested logic, long functions, or unclear names
-- When refactoring code written under time pressure
-- When consolidating related logic scattered across files
-- After merging changes that introduced duplication or inconsistency
-
-**When NOT to use:**
+## When NOT to Use
 
 - Code is already clean and readable — don't simplify for the sake of it
 - You don't understand what the code does yet — comprehend before you simplify
@@ -75,25 +66,29 @@ Simplification that breaks project consistency is not simplification — it's ch
 
 Detect the formatter before formatting anything — first match wins:
 
-| Signal in the repo                                                                | Formatter to run                                                                 |
-| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `format` / `fmt` script in `package.json`, `Makefile`, `justfile`, `Taskfile.yml` | Run that script — it encodes the project's intent and needs no further detection |
-| `biome.json` / `biome.jsonc`                                                      | `biome format --write`                                                           |
-| `.oxfmtrc.json`, or `oxfmt` in devDependencies                                    | `oxfmt`                                                                          |
-| `dprint.json` / `.dprint.jsonc`                                                   | `dprint fmt`                                                                     |
-| `.prettierrc*`, `prettier.config.*`, or a `prettier` key in `package.json`        | `prettier --write`                                                               |
-| `rustfmt.toml`, or any Cargo crate                                                | `cargo fmt`                                                                      |
-| `[tool.ruff]` in `pyproject.toml`                                                 | `ruff format`                                                                    |
-| `[tool.black]` in `pyproject.toml`                                                | `black`                                                                          |
-| Go module                                                                         | `gofmt -w` (or `goimports -w` if already used)                                   |
-| Only `.editorconfig`, or no signal at all                                         | Do not format — match the surrounding style by hand                              |
+| Signal in the repo                                                                | Formatter to run                                                    |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `format` / `fmt` script in `package.json`, `Makefile`, `justfile`, `Taskfile.yml` | That script decides — narrow it to your files (see the rules below) |
+| `biome.json` / `biome.jsonc`                                                      | `biome format --write`                                              |
+| `.oxfmtrc.json`, or `oxfmt` in devDependencies                                    | `oxfmt`                                                             |
+| `dprint.json` / `.dprint.jsonc`                                                   | `dprint fmt`                                                        |
+| `.prettierrc*`, `prettier.config.*`, or a `prettier` key in `package.json`        | `prettier --write`                                                  |
+| `rustfmt.toml`, or any Cargo crate                                                | `cargo fmt`                                                         |
+| `[tool.ruff]` in `pyproject.toml`                                                 | `ruff format`                                                       |
+| `[tool.black]` in `pyproject.toml`                                                | `black`                                                             |
+| Go module                                                                         | `gofmt -w` (or `goimports -w` if already used)                      |
+| Only `.editorconfig`, or no signal at all                                         | Do not format — match the surrounding style by hand                 |
 
 Rules:
 
 - Invoke the project's pinned local binary through its package manager or runner, inferred from the lockfile (`bun`, `pnpm`, `yarn`, `npm`) — never a global install and never an `npx`-downloaded version, which may differ from the one that formatted the committed code.
+- **A script decides the tool, not the paths.** Read the script to learn the tool, its config, and its flags, then run that tool on your files only. Scripts usually hard-code their own paths, so passing a file to them adds it to the run instead of narrowing it. If the script chains several steps, run only its formatting steps, each narrowed to your files — a lint `--fix` step is not formatting.
+- In a monorepo, use the script from the nearest package manifest above the files that defines one — often only the repository root does.
+- If a `format` script cannot be narrowed, do not run it: it rewrites files outside the scope, and reverting those with `git checkout` would also discard any uncommitted work in them. Match the surrounding style by hand and report it.
 - If several formatters are configured, the `format` script decides. If there is no script and the signals conflict, ask which is canonical instead of picking one.
 - Format only the files you changed. A repo-wide format pass is a separate change with its own diff.
-- If the formatter rewrites far more than the lines you touched, its config disagrees with the committed code. Stop, revert the formatting, and report it — do not fold that drift into a simplification change.
+- Before running any formatter, save a copy of each file you are about to format to a temporary directory (`$TMPDIR`) — never inside the repository, where a backup can be committed. Git cannot tell a formatter's hunks apart from uncommitted work already in the file; the copy can.
+- If the formatter rewrites far more than the lines you touched, its config disagrees with the committed code. Stop, restore the copies you saved — never `git checkout` the file, which would also discard uncommitted work — match the surrounding style by hand, and report it. Do not fold that drift into a simplification change.
 
 ### 3. Prefer Clarity Over Cleverness
 
@@ -137,6 +132,7 @@ Simplification has a failure mode: over-simplification. Watch for these traps:
 - **Combining unrelated logic** — two simple functions merged into one complex function is not simpler
 - **Removing "unnecessary" abstraction** — some abstractions exist for extensibility or testability, not complexity
 - **Optimizing for line count** — fewer lines is not the goal; easier comprehension is
+- **Stripping return type annotations** — leave them; exported ones are contracts, and inference can silently widen the type
 
 ### 5. Scope to What Changed
 
@@ -160,6 +156,16 @@ BEFORE SIMPLIFYING, ANSWER:
 
 If you can't answer these, you're not ready to simplify. Read more context first.
 
+**When no test exercises the scope**, the safety net that Step 3 relies on is missing. Pick one, and report the missing coverage either way:
+
+- Write characterization tests first. They pin the current behavior, including its quirks, and are never edited later to fit the refactor.
+- In a type-checked project, restrict the pass to changes the type checker verifies on its own, and leave every other candidate in the report:
+  - Rename locals, or remove unused locals whose initializer has no side effects. A call, `await`, `new`, or getter in the initializer can have one, and removing it changes behavior the checker cannot see.
+  - Skip a rename when the local also supplies an object key (`{ user }`), a JSX prop, or a string lookup — renaming it changes data, and the checker cannot see that.
+  - Unexport a symbol only after it clears every box of the pre-removal checklist. The checker catches a broken importer, but not a framework or config that resolves the symbol by name.
+
+Without a type checker, only characterization tests remain.
+
 ### Step 2: Identify Simplification Opportunities
 
 #### Step 2a: Mechanical pre-scan (required)
@@ -181,7 +187,8 @@ PRE-SCAN THE REQUESTED SCOPE:
 
 Do not skip the pre-scan because the file "looks clean". Judgment applies to the
 candidates it produces, not to whether to produce them. Report candidates you
-deliberately leave alone, with the reason.
+deliberately leave alone, with the reason. Every "report it" in this skill means an entry
+in the final [Report](#report), under its bucket.
 
 **A pre-scan hit is a question, not a verdict.** These tools find symbols nothing
 _imports_; they cannot see symbols resolved by name — framework exports, reflective
@@ -292,11 +299,6 @@ design decision rather than a behavior-preserving edit. Both collide with Princi
 Describe the change and the affected files, then stop and let the user decide — the
 same treatment the prop-drilling case gets under React guidance.
 
-**When the pre-scan flags a symbol you cannot prove is unreferenced, leave it and say
-so.** An export you were unsure about and kept costs a line of explanation. An export
-you removed on a guess costs a production incident. Unverifiable candidates are
-reported, not acted on.
-
 ```
 BEFORE REMOVING ANY export, ALL MUST HOLD:
 [ ] Not framework-resolved (checked against the list above)
@@ -310,7 +312,7 @@ Any box unchecked → report the candidate, do not touch it.
 
 ### Step 3: Apply Changes Incrementally
 
-Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
+Make one simplification at a time and run tests after each change, so a failure points to the change that caused it. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
 
 ```
 FOR EACH SIMPLIFICATION:
@@ -322,9 +324,7 @@ FOR EACH SIMPLIFICATION:
 4. If either fails → revert and reconsider
 ```
 
-Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
-
-**The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods or AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
+**The Rule of 500:** If a refactoring would touch more than 500 lines, stop and propose it — the scope, the approach (codemod or AST transform included), and the affected files — instead of applying it, unless the user explicitly asked for that scope. A change that size is no longer scoped to what changed (Principle 5), and manual edits at that scale are error-prone and exhausting to review.
 
 ### Step 4: Verify the Result
 
@@ -334,29 +334,40 @@ Then step back and evaluate the whole:
 
 ```
 COMPARE BEFORE AND AFTER:
-- Is the simplified version genuinely easier to understand?
-- Did you introduce any new patterns inconsistent with the codebase?
-- Is the diff clean and reviewable?
-- Would a teammate approve this change?
+- Is the simplified version genuinely easier to understand and review?
+- Did you introduce any pattern inconsistent with the surrounding code?
 ```
 
-If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
+If either answer is wrong, revert. Not every simplification attempt succeeds.
+
+## Report
+
+End every pass with one report. Every pre-scan candidate lands in exactly one bucket,
+and each entry names the file, the candidate, and the reason. A candidate you could not
+verify goes under **Unsure**, never into the code: an export kept on doubt costs a line
+of explanation, one removed on a guess costs an incident.
+
+**Group the noise, itemize the decisions.** Candidates under **Left alone on purpose**
+that share a tool and a reason collapse into one line with a count and the threshold or
+rule that dismissed them (for example, "14 complexity hits below nesting depth 3"). Every
+candidate in the other buckets gets its own entry.
+
+- **Applied** — what changed, and the check that proved it (type checker, tests)
+- **Not applied — changes behavior** — what the fix would alter: ordering, concurrency,
+  mutation, error surface, or name resolution
+- **Unsure** — what you could not verify, and which evidence is missing
+- **Propose-only** — API reshapes and refactors past the Rule of 500: the proposed change
+  and the files it would touch
+- **Left alone on purpose** — candidates not worth changing, with the reason
+
+Close with anything that limited the pass: missing test coverage, or formatter drift you
+reverted.
 
 ## Language-Specific Guidance
 
 ### TypeScript / JavaScript
 
 ```typescript
-// SIMPLIFY: Unnecessary async wrapper
-// Before
-async function getUser(id: string): Promise<User> {
-  return await userService.findById(id);
-}
-// After
-function getUser(id: string): Promise<User> {
-  return userService.findById(id);
-}
-
 // SIMPLIFY: Verbose conditional assignment
 // Before
 let displayName: string;
@@ -454,15 +465,12 @@ function UserBadge({ user }: Props) {
 
 ## Common Rationalizations
 
-| Rationalization                                      | Reality                                                                                                                                               |
-| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "It's working, no need to touch it"                  | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change.                               |
-| "Fewer lines is always simpler"                      | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count.                                |
-| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused.                                  |
-| "The types make it self-documenting"                 | Types document structure, not intent. A well-named function explains _why_ better than a type signature explains _what_.                              |
-| "This abstraction might be useful later"             | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed.                       |
-| "The original author must have had a reason"         | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
-| "I'll refactor while adding this feature"            | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history.                                        |
+| Rationalization                              | Reality                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| "Fewer lines is always simpler"              | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count.               |
+| "This abstraction might be useful later"     | Speculative abstractions are complexity without value. If nothing uses it now, remove it under the dead-code and export rules above. |
+| "The original author must have had a reason" | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's the residue of iteration.    |
+| "I'll refactor while adding this feature"    | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history.                       |
 
 ## Red Flags
 
@@ -471,36 +479,34 @@ function UserBadge({ user }: Props) {
 - Renaming things to match your preferences rather than project conventions
 - Removing error handling because "it makes the code cleaner"
 - Simplifying code you don't fully understand
-- Batching many simplifications into one large, hard-to-review commit
-- Refactoring code outside the scope of the current task without being asked
+- Touching code outside the requested scope without being asked
 - Deleting an export because a tool reported it unused, without checking whether the
   framework resolves it by name (`page.tsx`, `route.ts`, stories, config-referenced files)
 - Acting on a pre-scan candidate you could not verify — report it instead
+- Applying a propose-only row (module collapse, barrel deletion) without user sign-off
 - Treating a green test run as proof a visibility change was safe without a type check
 - Unexporting a symbol whose only importer is a test, then editing the test to match
-- Applying a propose-only row (module collapse, barrel deletion) without user sign-off
 - Trusting "the compiler would catch it" in a project the type checker does not cover
+- Dropping `async` or `return await` as a "simplification" — it changes how errors and stack traces surface
 
 ## Verification
 
 After completing a simplification pass:
 
 - [ ] All existing tests pass without modification
+- [ ] Type checker passes, if the project has one
 - [ ] Build succeeds with no new warnings
-- [ ] The project's own formatter was detected and run on the touched files — no formatter the project has not adopted was used
-- [ ] Formatting touched only the changed files (no repo-wide reformat mixed in)
+- [ ] The project's own formatter ran on the touched files only
 - [ ] Linter passes (no style regressions)
 - [ ] Each simplification is a reviewable, incremental change
-- [ ] The diff is clean — no unrelated changes mixed in
+- [ ] The diff holds nothing outside the requested scope
 - [ ] Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
 - [ ] No error handling was removed or weakened
 - [ ] No dead code was left behind (unused imports, unreachable branches)
-- [ ] The Step 2a pre-scan was run, and every candidate is either fixed or explained
-- [ ] Export surface matches actual consumers — nothing exported without a caller outside its file
-- [ ] Type checker passes — no unexport broke an importer
+- [ ] Every removed `export` cleared the pre-removal checklist
 - [ ] No framework-resolved export was unexported, renamed, or deleted
-- [ ] Every removed `export` cleared all boxes of the pre-removal checklist
 - [ ] No test was edited to accommodate a visibility change
 - [ ] Propose-only findings were reported, not applied
+- [ ] Every pre-scan candidate appears in the Report, itemized or counted in a grouped line
 - [ ] Behavior is bit-for-bit identical: same inputs, outputs, side effects, error paths
 - [ ] A teammate or review agent would approve the change as a net improvement

package/src/templates/mate-skills/claude/mate-apply-change/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: mate-apply-change
+description: Implement a change on a recorded delivery branch, offering change/<change-name> instead of a protected branch. Builds on the OpenSpec apply workflow. Use when the user wants to implement, apply, or continue implementing a reviewed change.
+allowed-tools: Bash(mate:*), Bash(openspec:*), Bash(git:*)
+license: MIT
+compatibility: Requires the mate CLI and the openspec capability enabled.
+metadata:
+  author: mate
+  version: "1.0"
+---
+
+# Mate Apply Change
+
+The Apply change stage of the Delivery Path. Before any code changes, it records the
+Working Repository branch the change is delivered through, so archive and publication
+later know which merge to wait for. Then it runs the OpenSpec apply workflow.
+
+## Step 1: Read the branch and the record
+
+In the Working Repository, read local Git state only:
+
+```bash
+git symbolic-ref --quiet --short HEAD          # current branch; fails when detached
+git symbolic-ref --quiet --short refs/remotes/origin/HEAD   # default branch
+```
+
+Read the change's existing record without changing it:
+
+```bash
+mate artifact link "<change-name>" --json
+```
+
+## Step 2: Settle the delivery branch
+
+A branch is **protected** when it is the default branch or matches a configured
+protected pattern; `mate artifact link` refuses a
+protected branch unless it is recorded as a direct delivery.
+
+- **A branch is already recorded** and it is the current branch → continue. When the
+  current branch differs, warn, name both branches, and ask before implementing
+  whether to switch to the recorded branch or record the current one.
+- **On `change/<change-name>`** → record it without asking:
+  `mate artifact link "<change-name>" --branch "change/<change-name>" --json`.
+- **On another unprotected branch** (a shared feature branch) → ask once whether this
+  change is delivered through it, then record it on confirmation.
+- **Detached HEAD** → ask for the branch name, then record it.
+- **On a protected branch** → do not implement there by default. First name every
+  local commit that is not on the remote (`git log --oneline HEAD --not --remotes`) and
+  leave them where they are; never move, reset, or rebase them. Then offer:
+  1. **Create `change/<change-name>`** (default): `git switch -c change/<change-name>`;
+     uncommitted edits carry over. Record it.
+  2. **Use an existing branch**: switch to the branch the user names and record it.
+  3. **Work directly here** — only when the user explicitly chooses it. Record it as a
+     direct delivery: `mate artifact link "<change-name>" --branch "<branch>" --direct --json`.
+
+Record the branch before writing any code. When `mate artifact link` refuses, report
+its message and ask; never work around it.
+
+When its result lists `warnings`, a `dependsOn` change is not implemented yet, so this
+change would be built without the code it builds on. Report each warning and ask
+whether to apply the dependency first or continue here.
+
+## Step 3: Apply
+
+Read [references/openspec-apply-change.md](references/openspec-apply-change.md) and
+follow it for the implementation. The PR need not exist yet; the branch is the delivery.
+After implementation, the optional peers `/mate-show-me` and `/mate-simplify-code` may
+run in any order, then `/mate-archive-change`. Name them as next steps; do not invoke
+them.
+
+## Guardrails
+
+- Never push, open a PR, or merge on the user's behalf.
+- Never record a protected branch except as an explicit direct delivery.
+- The forge token, when one is used by `mate artifact link`, is never printed or
+  written; do not read or echo `MATE_GIT_TOKEN`.