@shadowclone/skills 0.0.35 → 0.0.36

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "MIT",
   "homepage": "https://shadowclone.co",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "files": [
     "skills",
     "README.md",

package/skills/guided-pr-review/SKILL.md

@@ -14,14 +14,16 @@ metadata:
 
 A human needs to understand a PR and compare their observations with an agent's findings.
 The guide explains related behavior and exposes the actual code. It must account for the complete change.
+The reader may not know what the change is for. The guide must tell them before the first reading step.
 
 ## Gates
 
 1. Does the route account for every changed file, with accessible diffs and truthful coverage?
-2. Did shadowclone-review investigate locally without posting feedback or repeating CI checks?
-3. Do claims, visuals, and dry runs cite committed code and distinguish reasoning from executed checks?
-4. Can the human select prose or code, attach a comment, and save it into the original HTML?
-5. Are agent findings hidden until comparison, with inclusion and dismissal choices preserved?
+2. Can a reader who never opened the PR descriptions learn the problem, the result, and the approach?
+3. Did shadowclone-review investigate locally without posting feedback or repeating CI checks?
+4. Do claims, visuals, and dry runs cite committed code and distinguish reasoning from executed checks?
+5. Can the human select prose or code, attach a comment, and save it into the original HTML?
+6. Are agent findings hidden until comparison, with inclusion and dismissal choices preserved?
 
 ## Process
 
@@ -35,13 +37,16 @@ Write in the user's voice. Before you write, read `~/.agents/voice.md`. If it do
 6. With another supported engine, use the existing local prepare and analyze stages without the checks or publish stages.
 7. Without the CLI, follow shadowclone-review in the host agent and save its pinned findings locally.
 8. Follow surrounding callers, writes, consumers, and failure paths to explain how the change affects existing behavior.
-9. Group all changed files into a connected reading route. Start with the main contracts and their signatures.
-10. Connect related PRs and label ownership. Claim combined behavior only when Git establishes a combined head.
-11. Show each definition before its callers and effects. Pair each passage with its actual diffs and visible signature excerpts.
-12. Run a focused check only when it answers a named uncertainty. Record its actual result and limits.
-13. Write the input outside the public checkout, then run `node scripts/build.mjs <input.json> <review.html>`.
-14. Run `node scripts/check.mjs <review.html>` and inspect the real document before delivering it.
-15. Verify the reading order, complete file view, selection comments, and a same-file save and reopen cycle.
+9. Read each PR description, its linked issues, and its discussions. Compare their claims with the code.
+10. Write the overview: the problem, what changes, and how it works. For a stack, give each PR its role.
+11. If a description and the code disagree, follow the code and state the difference in the overview.
+12. Group all changed files into a connected reading route. Start with the main contracts and their signatures.
+13. Connect related PRs and label ownership. Claim combined behavior only when Git establishes a combined head.
+14. Show each definition before its callers and effects. Pair each passage with its actual diffs and visible signature excerpts.
+15. Run a focused check only when it answers a named uncertainty. Record its actual result and limits.
+16. Write the input outside the public checkout, then run `node scripts/build.mjs <input.json> <review.html>`.
+17. Run `node scripts/check.mjs <review.html>` and inspect the real document before delivering it.
+18. Verify the overview, the reading order, complete file view, selection comments, and a same-file save and reopen cycle.
 
 The script paths are relative to this skill. Node and Bun can run them.
 Place supporting files after the main behavior. Keep every file expanded, including the complete file view.

package/skills/guided-pr-review/assets/guide.mjs

@@ -5,6 +5,8 @@ let showFindings = false;
 let currentStep = 0;
 let currentPr = review.combined ? "stack" : review.pulls[0].id;
 let mode = "guide";
+const pages = [...document.querySelectorAll(".reading-step")];
+const pageTitle = (index) => pages[index].querySelector("h1").textContent;
 
 function renderFileList() {
   const search = document.getElementById("file-search").value.toLowerCase();
@@ -38,7 +40,7 @@ function refreshGuide() {
     .forEach((button) =>
       button.classList.toggle("selected", Number(button.dataset.step) === currentStep),
     );
-  document.querySelectorAll(".reading-step").forEach((element, index) => {
+  pages.forEach((element, index) => {
     element.hidden = index !== currentStep;
     element.querySelectorAll(".file-card").forEach((card) => {
       const file = getFile(card.dataset.file);
@@ -50,12 +52,10 @@ function refreshGuide() {
   const previous = document.getElementById("previous");
   const next = document.getElementById("next");
   previous.disabled = currentStep === 0;
-  next.disabled = currentStep === review.groups.length - 1;
-  previous.textContent = currentStep ? "← " + review.groups[currentStep - 1].title : "First step";
+  next.disabled = currentStep === pages.length - 1;
+  previous.textContent = currentStep ? "← " + pageTitle(currentStep - 1) : "First step";
   next.textContent =
-    currentStep < review.groups.length - 1
-      ? review.groups[currentStep + 1].title + " →"
-      : "Last step";
+    currentStep < pages.length - 1 ? pageTitle(currentStep + 1) + " →" : "Last step";
   document.querySelectorAll("[data-reviewed]").forEach((input) => {
     input.checked = review.annotations.reviewed.includes(input.dataset.reviewed);
   });
@@ -64,12 +64,11 @@ function refreshGuide() {
 }
 
 function selectStep(index) {
-  currentStep = Math.max(0, Math.min(review.groups.length - 1, index));
+  currentStep = Math.max(0, Math.min(pages.length - 1, index));
   mode = "guide";
   document.getElementById("selection-comment").hidden = true;
   refreshGuide();
-  const step = document.getElementById("step-" + review.groups[currentStep].id);
-  step.scrollIntoView({ block: "start" });
+  pages[currentStep].scrollIntoView({ block: "start" });
 }
 
 function showSource(id) {

package/skills/guided-pr-review/assets/presentation.mjs

@@ -51,6 +51,11 @@ p { margin: 10px 0; }
 .flow-proof, .sources { margin: 8px 0 18px; color: var(--muted); font-size: 12px; }
 .source-link { padding: 0; border: 0; background: none; font-size: 12px; text-decoration: underline; }
 .passage { margin: 20px 0; }
+.pr-roles { padding-left: 22px; }
+.pr-roles .passage { margin: 12px 0; }
+.pr-roles p, .terms p { margin: 4px 0; }
+.terms dt { margin-top: 12px; font-weight: 600; }
+.terms dd { margin: 0; color: var(--muted); }
 .step-files { margin: 24px 0; }
 .file-card { margin: 16px 0; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
 .file-card > summary { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 12px 14px; background: var(--panel); font: 12px/1.5 ui-monospace, monospace; overflow-wrap: anywhere; }

package/skills/guided-pr-review/references/report.md

@@ -11,6 +11,12 @@ Use these fields:
 {
   "title": "Review the job retry",
   "summary": "Follow the result and notification through failures.",
+  "overview": {
+    "problem": "A failed export job loses its result. The user must start the export again.",
+    "outcome": "The job retries up to three times. The user gets a notification after a saved result.",
+    "approach": "A retry boundary wraps the job callback. The notification starts after the result write.",
+    "terms": [{ "term": "Retry boundary", "meaning": "The code that repeats a failed callback." }]
+  },
   "pulls": [
     {
       "id": "pr-1",
@@ -18,6 +24,7 @@ Use these fields:
       "number": 1,
       "url": "<PR HTTPS URL>",
       "title": "Retry the job",
+      "role": "Adds the retry boundary around the job callback.",
       "checkout": "<private local checkout>",
       "baseSha": "<full SHA>",
       "headSha": "<full SHA>",
@@ -77,6 +84,23 @@ steps.files orders the actual diffs after that passage. Each file must belong to
 Without steps.files, the builder follows changed files in steps.evidence order.
 The group's remaining files follow its main passages. Every file starts expanded and links to its exact PR diff.
 
+## Overview
+
+The guide opens on the overview page, before the first reading step. Write it for a reader who has not opened the PRs.
+Use the PR descriptions, linked issues, discussions, and the code at the pinned heads as sources.
+
+- problem: the gap or failure that the change answers, and who sees it.
+- outcome: what works after the change merges, for users and for the system.
+- approach: the main mechanism and design choice, in a few sentences.
+- terms: optional. Explain each domain word that the reading steps use without a definition.
+- pulls.role: required for a stack. Say what that PR adds and what it builds on. List the pulls in merge order.
+
+The summary stays the reading plan: where to start and what the route covers.
+Do not put the reading plan in the overview, and do not copy a description that the code contradicts.
+If a description and the code disagree, follow the code and state the difference.
+The builder refuses an input without problem, outcome, and approach, or a stack PR without a role.
+Human notes can attach to the overview text. Their anchors start with `overview:`.
+
 ## Complete coverage
 
 Every changed PR/file pair must appear in groups.files. Repeating a file across related groups does not inflate totals.

package/skills/guided-pr-review/scripts/build.mjs

@@ -83,6 +83,7 @@ try {
     id,
     title: input.title,
     summary: input.summary,
+    overview: input.overview,
     status: input.status ?? "complete",
     pulls,
     groups,

package/skills/guided-pr-review/scripts/check.mjs

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
+import { checkOverview } from "./overview.mjs";
 
 function requireText(value, label) {
   if (typeof value !== "string" || !value.trim()) throw new Error(label + " must contain text.");
@@ -88,6 +89,7 @@ export function checkInput(input) {
     for (const edge of group.diagram?.edges ?? [])
       if (!edge.evidence?.length) throw new Error("Every diagram transition needs code evidence.");
   }
+  checkOverview(input);
 }
 
 export function checkCoverage(review) {

package/skills/guided-pr-review/scripts/overview.mjs

@@ -0,0 +1,79 @@
+import { escapeHtml, markdown } from "./format.mjs";
+
+const overviewTitle = "What this change does";
+
+const overviewSections = [
+  { key: "problem", title: "The problem" },
+  { key: "outcome", title: "What changes" },
+  { key: "approach", title: "How it works" },
+];
+
+const hasText = (value) => typeof value === "string" && value.trim() !== "";
+
+const pullsWithRoles = (pulls) => (pulls.length > 1 ? pulls : []);
+
+export function checkOverview(input) {
+  const terms = input.overview?.terms ?? [];
+  if (!Array.isArray(terms)) throw new Error("overview.terms must be a list.");
+  const missing = [
+    ...overviewSections
+      .filter((section) => !hasText(input.overview?.[section.key]))
+      .map((section) => "overview." + section.key),
+    ...pullsWithRoles(input.pulls)
+      .filter((pull) => !hasText(pull.role))
+      .map((pull) => "the role of PR #" + pull.number),
+    ...terms
+      .filter((entry) => !hasText(entry?.term) || !hasText(entry?.meaning))
+      .map(() => "each term and its meaning"),
+  ];
+  if (missing.length)
+    throw new Error("The overview needs text for " + [...new Set(missing)].join(", ") + ".");
+}
+
+function passageMarkup(options) {
+  const anchor = "overview:" + options.key;
+  return `<${options.element} class="passage" data-anchor="${anchor}" data-prs="${options.prs}">${options.heading}${options.body}<div class="inline-notes" data-notes-at="${anchor}"></div></${options.element}>`;
+}
+
+export function overviewRouteMarkup(review) {
+  const pullCount = review.pulls.length === 1 ? "1 PR" : review.pulls.length + " PRs";
+  return `<button class="route-step" data-step="0" type="button"><span>0</span><span>${overviewTitle}<small>Start here · ${pullCount}</small></span></button>`;
+}
+
+export function overviewMarkup(review) {
+  const allPulls = review.pulls.map((pull) => pull.id).join(",");
+  const sections = overviewSections.map((section) =>
+    passageMarkup({
+      element: "section",
+      key: section.key,
+      prs: allPulls,
+      heading: "<h3>" + section.title + "</h3>",
+      body: markdown(review.overview[section.key]),
+    }),
+  );
+  const roles = pullsWithRoles(review.pulls).map((pull) =>
+    passageMarkup({
+      element: "li",
+      key: pull.id,
+      prs: pull.id,
+      heading: `<p><a href="${escapeHtml(pull.url)}" target="_blank" rel="noreferrer">#${pull.number}</a> <strong>${escapeHtml(pull.title)}</strong></p>`,
+      body: markdown(pull.role),
+    }),
+  );
+  const terms = (review.overview.terms ?? []).map(
+    (entry) => "<dt>" + escapeHtml(entry.term) + "</dt><dd>" + markdown(entry.meaning) + "</dd>",
+  );
+  const rolesMarkup = roles.length
+    ? '<h3>What each PR adds</h3><ol class="pr-roles">' + roles.join("") + "</ol>"
+    : "";
+  const termsMarkup = terms.length
+    ? passageMarkup({
+        element: "section",
+        key: "terms",
+        prs: allPulls,
+        heading: "<h3>Terms</h3>",
+        body: '<dl class="terms">' + terms.join("") + "</dl>",
+      })
+    : "";
+  return `<article class="reading-step overview-page" id="step-overview"><div class="step-meta"><span>Start here, then ${review.groups.length} reading steps</span></div><h1>${overviewTitle}</h1>${sections.join("")}${rolesMarkup}${termsMarkup}</article>`;
+}

package/skills/guided-pr-review/scripts/render.mjs

@@ -6,6 +6,7 @@ import {
   sourceExcerptMarkup,
 } from "../assets/presentation.mjs";
 import { escapeHtml, jsonForHtml, markdown, fileCard, behaviorMarkup } from "./format.mjs";
+import { overviewMarkup, overviewRouteMarkup } from "./overview.mjs";
 
 function sourceLinks(options) {
   return [...new Set(options.ids)]
@@ -93,7 +94,7 @@ function groupMarkup(options) {
     })
     .join("");
   const remaining = fileSlots(group.files.map((file) => file.path));
-  return `<article class="reading-step" id="step-${group.id}" data-group="${group.id}" ${index ? "hidden" : ""}><div class="step-meta"><span>Step ${index + 1} of ${review.groups.length} · ${numbers}</span><label><input type="checkbox" data-reviewed="${group.id}"> Reviewed</label></div><h1>${escapeHtml(group.title)}</h1><div class="passage" data-anchor="${group.id}:summary" data-prs="${group.prs.join(",")}">${markdown(group.summary)}<div class="inline-notes" data-notes-at="${group.id}:summary"></div></div><p class="why">${escapeHtml(group.why)}</p><div class="before-after"><div><span>Before</span><p>${escapeHtml(group.before)}</p></div><div><span>After</span><p>${escapeHtml(group.after)}</p></div></div>${flow}${passages}${remaining ? '<div class="step-files"><h3>Remaining file changes</h3>' + remaining + "</div>" : ""}<div class="group-findings" data-findings-for="${group.id}"></div>${dryRuns}</article>`;
+  return `<article class="reading-step" id="step-${group.id}" data-group="${group.id}" hidden><div class="step-meta"><span>Step ${index + 1} of ${review.groups.length} · ${numbers}</span><label><input type="checkbox" data-reviewed="${group.id}"> Reviewed</label></div><h1>${escapeHtml(group.title)}</h1><div class="passage" data-anchor="${group.id}:summary" data-prs="${group.prs.join(",")}">${markdown(group.summary)}<div class="inline-notes" data-notes-at="${group.id}:summary"></div></div><p class="why">${escapeHtml(group.why)}</p><div class="before-after"><div><span>Before</span><p>${escapeHtml(group.before)}</p></div><div><span>After</span><p>${escapeHtml(group.after)}</p></div></div>${flow}${passages}${remaining ? '<div class="step-files"><h3>Remaining file changes</h3>' + remaining + "</div>" : ""}<div class="group-findings" data-findings-for="${group.id}"></div>${dryRuns}</article>`;
 }
 
 export async function renderReview(review) {
@@ -120,11 +121,12 @@ export async function renderReview(review) {
       : "";
   const sidebar =
     '<aside class="route"><h2>Reading route</h2>' +
+    overviewRouteMarkup(review) +
     review.groups
       .map(
         (group, index) =>
           '<button class="route-step" data-step="' +
-          index +
+          (index + 1) +
           '" type="button"><span>' +
           (index + 1) +
           "</span><span>" +
@@ -170,7 +172,7 @@ export async function renderReview(review) {
       );
     })
     .join("");
-  const body = `<header><strong class="brand">◇ shadowclone <span>/ guided review</span></strong><div class="header-actions"><button id="toggle-findings" type="button">Agent findings <span>${findings}</span></button><button id="toggle-notes" type="button">Your notes <span id="note-count">0</span></button><button id="save-review" type="button">Save review</button><span id="save-status" role="status">Saved HTML</span></div></header><div class="document">${sidebar}<main><div class="overview"><h2>${escapeHtml(review.title)}</h2>${markdown(review.summary)}${review.status === "prototype" ? '<p class="prototype">Prototype: one part of the reading route. The full file inventory remains available.</p>' : ""}${prTabs}<div class="view-tabs"><button data-mode="guide" type="button">Guide</button><button data-mode="files" type="button">All changes (${count})</button></div><details class="pr-details"><summary>PR details and CI</summary>${ci}</details></div><div id="guide">${review.groups.map((group, index) => groupMarkup({ group, review, index })).join("")}<nav class="step-navigation"><button id="previous" type="button">Previous</button><button id="next" type="button">Next</button></nav></div><section id="files" hidden><h1>Every changed file</h1><p>These are the actual per-PR changes, including files outside the main reading step.</p><input id="file-search" type="search" placeholder="Find a file" aria-label="Find a changed file"><div id="file-list"></div></section></main></div><aside id="notes-panel" hidden><button id="close-notes" type="button">Close</button><section class="human-notes"><h2>Your review notes</h2><p>Save this HTML, then attach it to your chat and request staging.</p><div id="notes-list"></div></section><section class="agent-findings"><h2 id="findings-heading" hidden>Agent findings</h2><div id="findings-list"></div></section></aside><aside id="composer" hidden><form id="note-form"><div class="composer-title"><strong>Your note</strong><button id="cancel-note" type="button" aria-label="Cancel note">×</button></div><blockquote id="selected-quote"></blockquote><label id="target-label">Post on <select id="target-pr"></select></label><textarea id="note-body" aria-label="Your rough note" placeholder="Write the concern or question in your words." required></textarea><button type="submit">Save note</button></form></aside><button id="selection-comment" type="button" hidden>Comment</button><dialog id="source-dialog"><button id="close-source" type="button">Close</button><h2 id="source-title"></h2><p id="source-pin"></p><pre><code id="source-code"></code></pre><a id="source-link" target="_blank" rel="noreferrer">Open pinned source</a></dialog>`;
+  const body = `<header><strong class="brand">◇ shadowclone <span>/ guided review</span></strong><div class="header-actions"><button id="toggle-findings" type="button">Agent findings <span>${findings}</span></button><button id="toggle-notes" type="button">Your notes <span id="note-count">0</span></button><button id="save-review" type="button">Save review</button><span id="save-status" role="status">Saved HTML</span></div></header><div class="document">${sidebar}<main><div class="overview"><h2>${escapeHtml(review.title)}</h2>${markdown(review.summary)}${review.status === "prototype" ? '<p class="prototype">Prototype: one part of the reading route. The full file inventory remains available.</p>' : ""}${prTabs}<div class="view-tabs"><button data-mode="guide" type="button">Guide</button><button data-mode="files" type="button">All changes (${count})</button></div><details class="pr-details"><summary>PR details and CI</summary>${ci}</details></div><div id="guide">${overviewMarkup(review)}${review.groups.map((group, index) => groupMarkup({ group, review, index })).join("")}<nav class="step-navigation"><button id="previous" type="button">Previous</button><button id="next" type="button">Next</button></nav></div><section id="files" hidden><h1>Every changed file</h1><p>These are the actual per-PR changes, including files outside the main reading step.</p><input id="file-search" type="search" placeholder="Find a file" aria-label="Find a changed file"><div id="file-list"></div></section></main></div><aside id="notes-panel" hidden><button id="close-notes" type="button">Close</button><section class="human-notes"><h2>Your review notes</h2><p>Save this HTML, then attach it to your chat and request staging.</p><div id="notes-list"></div></section><section class="agent-findings"><h2 id="findings-heading" hidden>Agent findings</h2><div id="findings-list"></div></section></aside><aside id="composer" hidden><form id="note-form"><div class="composer-title"><strong>Your note</strong><button id="cancel-note" type="button" aria-label="Cancel note">×</button></div><blockquote id="selected-quote"></blockquote><label id="target-label">Post on <select id="target-pr"></select></label><textarea id="note-body" aria-label="Your rough note" placeholder="Write the concern or question in your words." required></textarea><button type="submit">Save note</button></form></aside><button id="selection-comment" type="button" hidden>Comment</button><dialog id="source-dialog"><button id="close-source" type="button">Close</button><h2 id="source-title"></h2><p id="source-pin"></p><pre><code id="source-code"></code></pre><a id="source-link" target="_blank" rel="noreferrer">Open pinned source</a></dialog>`;
   const format = (await readFile(new URL("./format.mjs", import.meta.url), "utf8")).replace(
     /^export /gm,
     "",