@slowdini/slow-powers-opencode 0.2.0 → 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/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

@@ -38,13 +38,24 @@ Before claiming any task is finished, making a success claim, or declaring a bug
 
 ---
 
-## Finishing: Review First, Then Verify
+## 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 this finishing sequence in order — review **before** the final verification, so the evidence you hand back covers the exact code being returned:
+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 the diff.** Invoke your harness's built-in code-review capability over the change. Verification proves the work *runs*; review catches what running can't — silent regressions, missed edge cases, leftover debug code, and reuse or simplification you'd want before another person reads the diff. This is a quick final check, not a second project. If your harness has no code-review capability, say so and re-read the diff yourself with the same intent.
-2. **Address what it surfaces.** Fix or explicitly flag each finding. Any fix changes the code.
-3. **Run the final verification last, on the result.** Now apply the Gate Function fresh to the post-review code and present *that* output as your evidence. Running verification before review would prove a version of the code you then changed — the check the user sees must be the check on the code the user gets.
+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.
 
 ---
 
@@ -69,7 +80,7 @@ Verified, reviewed work is still *your* checkpoint, not a decision to merge. Int
 | "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 step of finishing, not the whole sequence. Review the diff, then run the final check on the reviewed code. |
+| "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. |
 
 ---

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.

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

@@ -0,0 +1,85 @@
+# Reviewing the Comments
+
+This is **phase 3** — the last step of the finishing sequence in [`SKILL.md`](SKILL.md).
+By now the code has been reviewed (phase 1), and verified (phase 2). The code is frozen;
+**this pass touches only comments.** That is the whole reason it comes last: a
+comment edit can't change behavior, so it can't invalidate the verification you
+just ran — there is nothing here to re-test. Do it as the final polish before the
+handoff.
+
+---
+
+## The comment-hygiene pass
+
+Review **every comment in the changed code** with one goal: **delete as many as
+possible.**
+
+This runs against your own instinct. Writing a comment feels like preserving the
+narrative — why this approach, what was tried, which ticket it traces to. But a
+human reading code finds it *very hard* to skip a comment; every one they hit,
+they stop and read. Narrative comments tax every future reader to record a story
+that belongs in the commit message or the PR, not the source. Left in, they
+become the thing the user has to delete by hand before merging — so delete them
+now, on their behalf.
+
+A comment survives only if it fits one of two categories **and** meets its bar:
+
+1. **Explanation.** Code that is genuinely hard to follow from reading it — a
+   subtle algorithm, a deliberate break from the usual pattern, a non-obvious
+   constraint. The comment fills the gap with an *evergreen* reason (true a year
+   from now, not "fixes the bug from Tuesday"). These are **extremely rare**:
+   well-written code is self-commenting, and a reader fluent in code can follow
+   even sophisticated paths when the code itself is clear. If the right fix is to
+   make the code clearer, do that instead of explaining unclear code.
+2. **Documentation.** A concise doc-style comment (jsdoc and equivalents) on an
+   **exported** member, where the text is surfaced by doc generators and editor
+   hints to readers who *don't* have the source in front of them. These almost
+   always earn their place. Keep them concise and evergreen, matching the
+   surrounding style; they may describe usage more freely since that's their job.
+
+**Everything else gets deleted — about 99.9% of the time.** The most common
+offender, and the one that feels most defensible, is **step-by-step narration**
+that walks through what the code already says — `// Step 1: lowercase`,
+`// now strip the accents`, `// finally, trim the dashes`. It reads as helpful
+structure, and *that feeling is the trap*: the numbered steps restate control
+flow the reader can already see in the code, so most such comments carry no
+information the line below them doesn't — they only add something else to read.
+"The steps make it easier to follow" is the rationalization to delete *through*,
+not act on; the code is the structure. Strip the narration and nothing is lost.
+The same goes for prose narrative ("first we… then we…"), time-sensitive comments
+(ticket numbers, "the previous solution…", "changed this because…"), and any
+comment that merely restates its line. A comment that fits neither surviving
+category, or fits one but misses its bar, is noise. **When in doubt, delete it.**
+A truly unique case might warrant a truly unusual comment — but treat that as the
+rare exception it is, not the default.
+
+```ts
+// BEFORE — every comment restates the line under it
+// Step 1: lowercase the title
+const lower = title.toLowerCase();
+// Step 2: replace whitespace runs with a single hyphen
+const hyphenated = lower.replace(/\s+/g, "-");
+
+// AFTER — the code already says all of that
+const lower = title.toLowerCase();
+const hyphenated = lower.replace(/\s+/g, "-");
+```
+
+**A kernel of value doesn't save the comment around it.** The hardest case is
+the *mixed* comment — mostly narration, with one genuinely useful clause buried
+in it (a real constraint, a non-obvious *why*). Keeping the whole block "because
+part of it is useful" is exactly how noise survives review: a reader will keep a
+comment that's 90% restatement for the sake of the 10% that matters. Don't.
+**Extract the useful part, delete the rest, and if what remains earns a comment,
+write it as a tight standalone one** — the kernel alone, not the narration that
+carried it. A four-line "Step 1… / Step 2 *(the one real reason)* / Step 3… /
+Step 4…" block collapses to a single comment stating that one reason, and the
+numbered narration is gone.
+
+---
+
+## Then: hand it back
+
+These were comment-only edits — they change no behavior, so there is **nothing to
+re-verify**: the verification from phase 2 still covers the code being returned.
+Return to the finishing sequence in [`SKILL.md`](SKILL.md) for the handoff.