@slowdini/slow-powers-opencode 0.1.5 → 0.3.0

package/skills/evaluating-skills/runner/workspace-teardown.test.ts

@@ -0,0 +1,227 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  cleanupWorkspace,
+  PROMOTED_MARKER,
+  SNAPSHOT_META,
+} from "./workspace-teardown";
+
+const FIXTURE_ROOT = join(
+  tmpdir(),
+  `slow-powers-workspace-teardown-test-${process.pid}`,
+);
+
+beforeAll(() => {
+  mkdirSync(FIXTURE_ROOT, { recursive: true });
+});
+
+afterAll(() => {
+  rmSync(FIXTURE_ROOT, { recursive: true, force: true });
+});
+
+let caseSeq = 0;
+function freshWorkspace(): string {
+  caseSeq += 1;
+  const workspaceRoot = join(
+    FIXTURE_ROOT,
+    `case-${caseSeq}`,
+    "skills-workspace",
+  );
+  mkdirSync(workspaceRoot, { recursive: true });
+  return workspaceRoot;
+}
+
+function writeJson(path: string, value: unknown) {
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** Build an iteration dir; `opts` controls which artifacts it carries. */
+function makeIteration(
+  workspaceRoot: string,
+  skill: string,
+  iteration: string,
+  opts: {
+    promoted?: boolean;
+    benchmark?: boolean;
+    runRecord?: boolean;
+    grading?: boolean;
+    scaffoldingOnly?: boolean;
+  },
+): string {
+  const dir = join(workspaceRoot, skill, iteration);
+  mkdirSync(dir, { recursive: true });
+  if (opts.scaffoldingOnly) {
+    writeFileSync(join(dir, "dispatch.json"), "[]\n");
+  }
+  if (opts.benchmark) {
+    writeJson(join(dir, "benchmark.json"), { delta: { pass_rate: 0.5 } });
+  }
+  if (opts.runRecord) {
+    writeJson(join(dir, "eval-e1", "with_skill", "run.json"), {
+      eval_id: "e1",
+    });
+  }
+  if (opts.grading) {
+    writeJson(join(dir, "eval-e1", "with_skill", "grading.json"), {
+      summary: { pass_rate: 1 },
+    });
+  }
+  if (opts.promoted) {
+    writeJson(join(dir, PROMOTED_MARKER), {
+      promoted_at: "2026-06-04T00:00:00.000Z",
+      baseline_dir: "/somewhere/evals/baseline",
+      commit: "abc1234",
+    });
+  }
+  return dir;
+}
+
+function makeSnapshot(
+  workspaceRoot: string,
+  skill: string,
+  label: string,
+  source: "ref" | "working-tree" | null,
+): string {
+  const dir = join(workspaceRoot, skill, "snapshots", label);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), "snapshot body\n");
+  if (source !== null) {
+    writeJson(
+      join(dir, SNAPSHOT_META),
+      source === "ref" ? { source, ref: "HEAD~1" } : { source },
+    );
+  }
+  return dir;
+}
+
+describe("cleanupWorkspace — iterations", () => {
+  test("removes a promoted iteration and prunes the emptied workspace", () => {
+    const ws = freshWorkspace();
+    const iter = makeIteration(ws, "mr-review", "iteration-1", {
+      promoted: true,
+      benchmark: true,
+      grading: true,
+    });
+
+    const summary = cleanupWorkspace(ws, "mr-review");
+
+    expect(existsSync(iter)).toBe(false);
+    expect(summary.removedIterations).toEqual(["iteration-1"]);
+    expect(summary.workspaceRemoved).toBe(true);
+    // Skill dir and the workspace root are pruned once empty.
+    expect(existsSync(join(ws, "mr-review"))).toBe(false);
+    expect(existsSync(ws)).toBe(false);
+  });
+
+  test("keeps an unpromoted iteration that holds a benchmark, and reports it", () => {
+    const ws = freshWorkspace();
+    const iter = makeIteration(ws, "mr-review", "iteration-1", {
+      benchmark: true,
+    });
+
+    const summary = cleanupWorkspace(ws, "mr-review");
+
+    expect(existsSync(iter)).toBe(true);
+    expect(summary.removedIterations).toEqual([]);
+    expect(summary.keptIterations.map((k) => k.iteration)).toEqual([
+      "iteration-1",
+    ]);
+    // Nothing was emptied, so the workspace stays.
+    expect(existsSync(ws)).toBe(true);
+  });
+
+  test("keeps an unpromoted iteration that holds only a run record", () => {
+    const ws = freshWorkspace();
+    const iter = makeIteration(ws, "mr-review", "iteration-1", {
+      runRecord: true,
+    });
+
+    const summary = cleanupWorkspace(ws, "mr-review");
+
+    expect(existsSync(iter)).toBe(true);
+    expect(summary.keptIterations.map((k) => k.iteration)).toEqual([
+      "iteration-1",
+    ]);
+  });
+
+  test("removes an unpromoted scaffolding-only iteration (no captured results)", () => {
+    const ws = freshWorkspace();
+    const iter = makeIteration(ws, "mr-review", "iteration-1", {
+      scaffoldingOnly: true,
+    });
+
+    const summary = cleanupWorkspace(ws, "mr-review");
+
+    expect(existsSync(iter)).toBe(false);
+    expect(summary.removedIterations).toEqual(["iteration-1"]);
+  });
+
+  test("mixed: promoted removed, unpromoted-with-results kept, skill dir NOT pruned", () => {
+    const ws = freshWorkspace();
+    const promoted = makeIteration(ws, "mr-review", "iteration-1", {
+      promoted: true,
+      benchmark: true,
+    });
+    const kept = makeIteration(ws, "mr-review", "iteration-2", {
+      benchmark: true,
+    });
+
+    const summary = cleanupWorkspace(ws, "mr-review");
+
+    expect(existsSync(promoted)).toBe(false);
+    expect(existsSync(kept)).toBe(true);
+    expect(summary.removedIterations).toEqual(["iteration-1"]);
+    expect(summary.keptIterations.map((k) => k.iteration)).toEqual([
+      "iteration-2",
+    ]);
+    expect(summary.workspaceRemoved).toBe(false);
+    expect(existsSync(join(ws, "mr-review"))).toBe(true);
+  });
+});
+
+describe("cleanupWorkspace — snapshots", () => {
+  test("removes ref snapshots, keeps working-tree and legacy (no-meta) snapshots", () => {
+    const ws = freshWorkspace();
+    const refSnap = makeSnapshot(ws, "mr-review", "old-ref", "ref");
+    const wtSnap = makeSnapshot(ws, "mr-review", "wt", "working-tree");
+    const legacySnap = makeSnapshot(ws, "mr-review", "legacy", null);
+
+    const summary = cleanupWorkspace(ws, "mr-review");
+
+    expect(existsSync(refSnap)).toBe(false);
+    expect(existsSync(wtSnap)).toBe(true);
+    expect(existsSync(legacySnap)).toBe(true);
+    expect(summary.removedSnapshots).toEqual(["old-ref"]);
+    expect(summary.keptSnapshots.sort()).toEqual(["legacy", "wt"]);
+  });
+});
+
+describe("cleanupWorkspace — safety", () => {
+  test("never touches another skill's workspace, and leaves the root intact", () => {
+    const ws = freshWorkspace();
+    makeIteration(ws, "mr-review", "iteration-1", { promoted: true });
+    const otherIter = makeIteration(ws, "other-skill", "iteration-1", {
+      benchmark: true,
+    });
+
+    cleanupWorkspace(ws, "mr-review");
+
+    expect(existsSync(join(ws, "mr-review"))).toBe(false);
+    expect(existsSync(otherIter)).toBe(true);
+    // Root survives because other-skill still lives there.
+    expect(existsSync(ws)).toBe(true);
+  });
+
+  test("returns an empty summary and does not throw when the skill has no workspace", () => {
+    const ws = freshWorkspace();
+    const summary = cleanupWorkspace(ws, "never-ran");
+    expect(summary.removedIterations).toEqual([]);
+    expect(summary.keptIterations).toEqual([]);
+    expect(summary.removedSnapshots).toEqual([]);
+    expect(summary.keptSnapshots).toEqual([]);
+    expect(summary.workspaceRemoved).toBe(false);
+  });
+});

package/skills/evaluating-skills/runner/workspace-teardown.ts

@@ -0,0 +1,136 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Marker `promote-baseline` drops into an iteration dir once that iteration's
+ * durable results (benchmark + gradings) are committed under the skill's
+ * `evals/baseline/`. Teardown treats its presence as "safe to delete" — the
+ * data now lives in version control.
+ */
+export const PROMOTED_MARKER = ".promoted.json";
+
+/**
+ * Provenance the `snapshot` command writes into each `snapshots/<label>/` dir,
+ * recording whether it was materialized from a git ref (reproducible) or copied
+ * from the working tree (not reproducible). Teardown only reclaims ref snapshots.
+ */
+export const SNAPSHOT_META = ".snapshot-meta.json";
+
+export type WorkspaceCleanupSummary = {
+  /** Iteration dir names removed (promoted, or pure scaffolding). */
+  removedIterations: string[];
+  /** Iterations kept because they hold uncommitted results, with the reason. */
+  keptIterations: { iteration: string; reason: string }[];
+  /** Snapshot labels removed (reproducible from a git ref). */
+  removedSnapshots: string[];
+  /** Snapshot labels kept (working-tree or legacy, can't be regenerated). */
+  keptSnapshots: string[];
+  /** True when the skill's whole workspace subtree was removed. */
+  workspaceRemoved: boolean;
+};
+
+/** Remove `dir` only if it exists and is empty. */
+function pruneIfEmpty(dir: string): void {
+  if (existsSync(dir) && readdirSync(dir).length === 0) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * An iteration carries "captured results" worth preserving if it reached the
+ * point of producing an aggregate (`benchmark.json`) or any per-run record or
+ * grading. Anything short of that (e.g. a `--dry-run` or a run staged but never
+ * dispatched) is reproducible scaffolding.
+ */
+function iterationHasResults(iterDir: string): boolean {
+  if (existsSync(join(iterDir, "benchmark.json"))) return true;
+  for (const entry of readdirSync(iterDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith("eval-")) continue;
+    const evalDir = join(iterDir, entry.name);
+    for (const cond of readdirSync(evalDir, { withFileTypes: true })) {
+      if (!cond.isDirectory()) continue;
+      const condDir = join(evalDir, cond.name);
+      if (existsSync(join(condDir, "run.json"))) return true;
+      if (existsSync(join(condDir, "grading.json"))) return true;
+    }
+  }
+  return false;
+}
+
+function snapshotSource(snapDir: string): string | null {
+  const metaPath = join(snapDir, SNAPSHOT_META);
+  if (!existsSync(metaPath)) return null;
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, "utf8")) as {
+      source?: string;
+    };
+    return meta.source ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * End-of-run cleanup of a skill's `skills-workspace/<skill>/` subtree, so a
+ * finished eval leaves behind nothing that wasn't meant to be committed —
+ * without ever destroying results the user hasn't moved into version control.
+ *
+ * Per iteration: promoted (marker present) → removed; unpromoted but holding
+ * captured results → kept and reported; unpromoted scaffolding → removed. Per
+ * snapshot: ref-sourced → removed; working-tree or legacy → kept. Empty parents
+ * (`snapshots/`, the skill dir, the workspace root) are pruned, but a non-empty
+ * one — e.g. another skill's artifacts — is never touched.
+ */
+export function cleanupWorkspace(
+  workspaceRoot: string,
+  skillName: string,
+): WorkspaceCleanupSummary {
+  const summary: WorkspaceCleanupSummary = {
+    removedIterations: [],
+    keptIterations: [],
+    removedSnapshots: [],
+    keptSnapshots: [],
+    workspaceRemoved: false,
+  };
+
+  const skillDir = join(workspaceRoot, skillName);
+  if (!existsSync(skillDir)) return summary;
+
+  for (const entry of readdirSync(skillDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith("iteration-")) continue;
+    const iterDir = join(skillDir, entry.name);
+    if (existsSync(join(iterDir, PROMOTED_MARKER))) {
+      rmSync(iterDir, { recursive: true, force: true });
+      summary.removedIterations.push(entry.name);
+    } else if (iterationHasResults(iterDir)) {
+      summary.keptIterations.push({
+        iteration: entry.name,
+        reason: "uncommitted results — not promoted to evals/baseline/",
+      });
+    } else {
+      rmSync(iterDir, { recursive: true, force: true });
+      summary.removedIterations.push(entry.name);
+    }
+  }
+
+  const snapshotsDir = join(skillDir, "snapshots");
+  if (existsSync(snapshotsDir)) {
+    for (const entry of readdirSync(snapshotsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const snapDir = join(snapshotsDir, entry.name);
+      if (snapshotSource(snapDir) === "ref") {
+        rmSync(snapDir, { recursive: true, force: true });
+        summary.removedSnapshots.push(entry.name);
+      } else {
+        summary.keptSnapshots.push(entry.name);
+      }
+    }
+    pruneIfEmpty(snapshotsDir);
+  }
+
+  pruneIfEmpty(skillDir);
+  summary.workspaceRemoved = !existsSync(skillDir);
+  pruneIfEmpty(workspaceRoot);
+
+  return summary;
+}

package/skills/evaluating-skills/schema/run-record.schema.json

@@ -70,11 +70,11 @@
     },
     "total_tokens": {
       "type": ["integer", "null"],
-      "description": "From the harness's task completion event. May be null if the harness does not surface this."
+      "description": "From the harness's task completion event, or derived from the persisted transcript by record-runs (usage summed across unique message ids, including cache creation/read tokens — a different accounting than the completion event). Canonical timing lives in the sibling timing.json, whose `source` field records which origin produced it. May be null if neither source is available."
     },
     "duration_ms": {
       "type": ["integer", "null"],
-      "description": "From the harness's task completion event. May be null if the harness does not surface this."
+      "description": "From the harness's task completion event, or derived from the persisted transcript by record-runs (wall clock between the first and last transcript timestamps). Canonical timing lives in the sibling timing.json. May be null if neither source is available."
     }
   }
 }

package/skills/evaluating-skills/schema/stray-writes.schema.json

@@ -11,11 +11,12 @@
     "iteration": { "type": "integer" },
     "totals": {
       "type": "object",
-      "required": ["violations", "warnings"],
+      "required": ["violations", "warnings", "live_source_reads"],
       "additionalProperties": false,
       "properties": {
         "violations": { "type": "integer" },
-        "warnings": { "type": "integer" }
+        "warnings": { "type": "integer" },
+        "live_source_reads": { "type": "integer" }
       }
     },
     "runs": {
@@ -23,7 +24,13 @@
       "description": "One entry per (eval, condition) run that had at least one finding.",
       "items": {
         "type": "object",
-        "required": ["eval_id", "condition", "violations", "warnings"],
+        "required": [
+          "eval_id",
+          "condition",
+          "violations",
+          "warnings",
+          "live_source_reads"
+        ],
         "additionalProperties": false,
         "properties": {
           "eval_id": { "type": "string" },
@@ -37,6 +44,11 @@
             "type": "array",
             "description": "Heuristic: a Bash command matched a mutating pattern (install, git, sed -i, redirection) without referencing the outputs dir.",
             "items": { "$ref": "#/definitions/finding" }
+          },
+          "live_source_reads": {
+            "type": "array",
+            "description": "A read tool or Bash command accessed the live skill-under-test directory instead of the staged copy — the arm may be contaminated (staged-slug resolution race).",
+            "items": { "$ref": "#/definitions/finding" }
           }
         }
       }

package/skills/evaluating-skills/templates/eval-task-prompt.md

@@ -61,7 +61,9 @@ User request:
 
 ## After the subagent completes
 
-The operator (or the runner) must capture:
+Two records must exist per run: `{{output_dir}}/../run.json` (matching `schema/run-record.schema.json`) and `{{output_dir}}/../timing.json`.
 
-1. The full transcript / tool invocations → convert via the harness adapter into `{{output_dir}}/../run.json` matching `schema/run-record.schema.json`.
-2. `total_tokens` and `duration_ms` from the harness's task completion event → `{{output_dir}}/../timing.json`. **These values may not be persisted anywhere else — save them immediately.**
+- **Harnesses with persisted transcripts (Claude Code):** `record-runs` assembles both from disk after all dispatches — carry-over fields from `dispatch.json`, `final_message` from `{{output_dir}}/final-message.md`, `tool_invocations`/tokens/duration from the transcript. The operator captures nothing per-task. Optionally, completion-event timing written to `timing.json` at dispatch time (with `"source": "completion-event"`) takes precedence — `record-runs` only backfills, never overwrites.
+- **Transcript-less harnesses:** the operator (or the runner) captures manually, as before:
+  1. The full transcript / tool invocations → convert via the harness adapter into `{{output_dir}}/../run.json`.
+  2. `total_tokens` and `duration_ms` from the harness's task completion event → `{{output_dir}}/../timing.json`. **These values may not be persisted anywhere else — save them immediately.**

package/skills/hardening-plans/SKILL.md

@@ -44,7 +44,7 @@ Before the plan leaves your hands, re-read the whole draft once, top to bottom,
 
 When the plan is approved, implementation begins — and implementation has its own gate.
 
-> **REQUIRED NEXT SKILL:** Use `slow-powers:test-driven-development` for the implementation phase.
+> **REQUIRED NEXT SKILL:** You must complete `slow-powers:test-driven-development` next for the implementation phase.
 
 The plan should carry a tests section so the reader can see *what* will be verified. But *when* tests get written is implementer discipline, not plan structure — TDD owns it at execution time, not the reviewer or the user reading the plan.
 

package/skills/systematic-debugging/SKILL.md

@@ -11,6 +11,10 @@ Avoid "guess-and-check" coding. Always identify the root cause before making cha
 
 > **Violating the letter of the rules is violating the spirit of the rules.**
 
+> **REQUIRED PREREQUISITE:** You must have already completed `slow-powers:working-in-isolation` — debug from an isolated workspace.
+
+> **REQUIRED BACKGROUND:** You must understand `slow-powers:test-driven-development` — Phase 4 captures the bug with a failing test before fixing it.
+
 ---
 
 ## Phase 1: Root Cause Investigation

package/skills/test-driven-development/SKILL.md

@@ -13,6 +13,8 @@ Write production code before the test? Delete it. Start over. Do not keep it for
 
 > **Violating the letter of the rules is violating the spirit of the rules.**
 
+> **REQUIRED PREREQUISITE:** You must have already completed `slow-powers:working-in-isolation` — establish an isolated workspace before writing any test or production code.
+
 ---
 
 ## Red-Green-Refactor Cycle

package/skills/test-driven-development/evals/baseline/NOTES.md

@@ -60,7 +60,7 @@ Roughly in increasing order of effort / payoff:
    class of eval measurable. This is the high-value framework improvement.
 3. **Real harness-mode injection.** Reproduce the plan-mode suppression by running
    the eval subagent *inside* a real plan mode rather than a described one. Tracked
-   as a parity goal in `harness-parity-check.md`; the biggest lift.
+   as a parity goal in `skills/evaluating-skills/harness-parity.md`; the biggest lift.
 
 ## Bigger-picture testing strategy (from the maintainer)
 

package/skills/verifying-development-work/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: verifying-development-work
+description: Use before claiming any task is complete, fixed, or passing, and before handing finished work back to the user.
+---
+
+# Verifying Development Work
+
+Claiming work is complete without verification is an assumption, not a fact. Always verify before presenting success.
+
+> **THE IRON LAW:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.
+
+> **Violating the letter of the rules is violating the spirit of the rules.**
+
+---
+
+## The Gate Function
+
+Before claiming any task is finished, making a success claim, or declaring a bug fixed:
+
+1. **IDENTIFY:** What exact command or output proves this claim? (e.g., test command, compiler output, linter check).
+2. **RUN:** Execute that command fresh and in full. Do not rely on previous runs or assume "nothing changed."
+3. **READ:** Review the full output, verify exit code is `0`, and check for warning logs.
+4. **VERIFY:** Does the output confirm success?
+   * **If NO:** Correct the code or tests. Repeat verification.
+   * **If YES:** State your completion claim **and present the fresh verification output** as evidence to the user.
+
+---
+
+## Core Verification Types
+
+| Success Claim | What is Required | What is NOT Sufficient |
+| :--- | :--- | :--- |
+| **"Tests are passing"** | Fresh execution of the test suite showing `0 failures`. | "They should pass," or a test run from 15 minutes ago. |
+| **"Linter is clean"** | Linter execution output showing `0 errors` and `0 warnings`. | Assumed clean because it compiled. |
+| **"Build succeeds"** | Compiler/build output exiting with code `0`. | Linter passing (compilation could still fail). |
+| **"Bug is fixed"** | Consistently running the failing scenario showing it now succeeds. | The code change was made and "seems correct." |
+| **"Requirements met"** | A checklist of the plan's requirements matched against code verification. | Tests pass, but product criteria were skipped. |
+
+---
+
+## Finishing: Review Code, Verify, Then Review Comments
+
+The Gate Function above is your discipline at *every* completion claim. When you believe the work itself is done, run these three finishing phases **in order**. The order is deliberate: every code change happens in phase 1, *before* the verification, so the evidence you hand back is guaranteed to cover the exact code being returned — and comment cleanup comes *after*, where it can't disturb that check.
+
+1. **Review and fix the code** — follow [`code-review.md`](code-review.md). This is the only phase that changes behavior. Review catches what running can't — silent regressions, missed edge cases, leftover debug code, reuse or simplification — then you fix or flag each finding, and *the code is now frozen*. Size the review to the change: a quick check, not a second project. (Comments are **not** reviewed here — they get phase 3.)
+2. **Run the final verification** — apply the Gate Function fresh to the now-frozen code and present *that* output as your evidence. Because all code changes happened in phase 1, this check covers exactly what the user gets.
+3. **Review and clean the comments** — follow [`comment-review.md`](comment-review.md). This pass touches *only* comments, so it changes no behavior and needs **no re-verification**: delete narrative / step-by-step / ticket comments, keeping only true Explanation or exported-member Documentation, before the diff reaches a human.
+
+**Copy this checklist into your task tracker the moment you start finishing, and tick each box in order.** The ordering *is* the discipline — and an untracked checklist is one whose middle steps get skipped under momentum:
+
+```
+- [ ] Phase 1 — reviewed the CODE against intent, ranked findings, fixed/flagged each (per code-review.md); code is now frozen
+- [ ] Phase 2 — ran the final verification fresh on the frozen code, and presented that output as evidence
+- [ ] Phase 3 — reviewed the COMMENTS (per comment-review.md): deleted narrative / step-by-step / ticket comments, kept only true Explanation or exported Documentation
+- [ ] Surfaced integration options (merge / push+PR / leave as-is / discard) — did not merge or push on my own
+```
+
+The last box is its own gate; the section below is why it's never yours to skip.
+
+---
+
+## Don't Finish the Branch Unilaterally
+
+Verified, reviewed work is still *your* checkpoint, not a decision to merge. Integrating, publishing, or discarding work is the user's call.
+
+- **Never merge, push, open a PR, or delete a branch or worktree on your own initiative.** Surface the options and let the user choose.
+- **Present the choices, don't pick one.** State that the work is verified and reviewed, then lay out what could happen next (merge, push/PR, leave as-is, discard) and ask which they want.
+- **Never run a destructive or irreversible git action without explicit confirmation.** A discard that throws away work, a force action, anything you can't undo — name exactly what will be lost and wait for an unambiguous "yes" before doing it.
+
+---
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "I already manually tested it" | Manual testing is not reproducible verification. |
+| "The change is too small to need verification" | Small changes break things all the time. |
+| "I ran the tests earlier and they passed" | Earlier means a different codebase state. |
+| "Tests pass — a prior turn, a teammate, or the user already said so" | An inherited claim is not evidence. The Gate Function requires fresh output *you* produced, this turn. |
+| "It's obvious this is correct" | Obvious bugs are the most embarrassing. Reading code predicts behavior; only running it proves behavior. |
+| "I'll verify after committing" | Verification after the claim is too late. |
+| "The build should be fine" | "Should" is not evidence. |
+| "Tests pass, so we're done here" | Verification is one phase of finishing, not the whole sequence — review and fix the code, verify the frozen result, then clean the comments. |
+| "The user said ship it, so I'll just merge" | "Ship it" authorizes the user's choice, not a unilateral merge or push. |
+
+---
+
+## Red Flags — STOP and Verify
+
+- "Should work now" / "probably fixed" / "seems correct" / "looks correct"
+- Claiming completion before running verification
+- Relying on partial or scoped test runs
+- "The code was updated successfully" without execution evidence
+- About to write "committed", "pushed", "shipped", or "deployed" — did you actually run that command this session? Asserting an action that never happened is fabrication, the worst failure in this skill's domain
+- Echoing a "tests pass" you didn't produce with a fresh run
+- Tests run, but no review pass over the diff
+- About to merge, push, or discard without asking — or without a fresh test run first
+
+All of these mean: STOP. Run the command, analyze the output, and present the evidence.

package/skills/verifying-development-work/code-review.md

@@ -0,0 +1,68 @@
+# Reviewing the Code
+
+This is **phase 1** of the finishing sequence in [`SKILL.md`](SKILL.md) — the
+code review. Review and fix the *code* here. This is the only phase that changes
+behavior, so once you finish it the code is frozen.
+
+---
+
+## Size the review to the change
+
+Review depth matches the size and risk of the diff. A one-line fix gets a careful
+read and a moment's thought about what it could break; a new subsystem gets more.
+Don't run a heavyweight audit over a trivial change to look thorough — a review
+that's louder than the change it covers is the failure this guidance exists to
+prevent.
+
+Do the review however your harness makes natural — read the diff inline, or
+dispatch it to a general purpose subagent.
+
+---
+
+## Read the diff against intent
+
+Read the actual diff — not your memory of what you changed — against the plan or
+the request. Cite findings by `file:line` so each one is checkable. Look for:
+
+- **Intent alignment** — does the change do what was asked? Are deviations
+  deliberate improvements, or drift?
+- **Correctness** — bugs, off-by-ones, wrong conditions, mishandled `null`/empty.
+- **Error & edge cases** — failure paths, boundaries, and inputs the happy path skips.
+- **Reuse & simplification** — existing helpers ignored, needless abstraction,
+  code that could be plainer.
+- **Leftover scaffolding** — debug prints, commented-out code, dead branches,
+  silent regressions to nearby behavior.
+- **Tests** — do they exercise real behavior, and do they cover what changed?
+
+This is not an exhaustive checklist to march through — it's where real problems
+tend to hide. Spend attention where this particular diff warrants it.
+
+---
+
+## Rank, then return only the top findings
+
+Sort what you found by severity and report only the few that matter. The point of
+ranking is to *drop* noise, not to pad a list.
+
+| Severity | What belongs here |
+|----------|-------------------|
+| **Critical — must fix** | Bugs, security holes, data loss, broken functionality. |
+| **Important — should fix** | Missing behavior, weak error handling, test gaps, architecture problems. |
+| **Minor — nice to have** | Style, micro-optimizations, polish. |
+
+Report the most important handful. **Drop Minor nitpicks unless nothing more
+serious exists** — a pile of trivia buries the one finding that mattered and
+trains the reader to skim past your review. Don't manufacture findings to fill the
+tiers; "nothing critical, one important thing" is a complete and good result.
+Close with a one-line verdict.
+
+---
+
+## Then: address the findings — and freeze the code
+
+Fix or explicitly flag each code finding you kept. Any fix changes the code — so
+make all of those changes *now*, in this phase. When you're done, the code is
+**frozen**: nothing in the remaining phases touches behavior. Return to the
+finishing sequence in [`SKILL.md`](SKILL.md) and run the **final verification**
+(phase 2) on this frozen result — the check you hand back is then guaranteed to
+cover the exact code being returned.