npm - claude-code-session-manager - Versions diffs - 0.26.0 → 0.28.0 - Mend

claude-code-session-manager 0.26.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/.claude-plugin/marketplace.json +21 -0
package/dist/assets/{TiptapBody-BsI_35c5.js → TiptapBody-CJ6GK5CM.js} +1 -1
package/dist/assets/index-DtQ4LzuV.js +3534 -0
package/dist/assets/index-Dwb94Uxm.css +32 -0
package/dist/index.html +2 -2
package/package.json +3 -1
package/plugins/session-manager-dev/.claude-plugin/plugin.json +19 -0
package/plugins/session-manager-dev/skills/develop/SKILL.md +112 -0
package/plugins/session-manager-dev/skills/develop/standards.md +67 -0
package/plugins/session-manager-dev/skills/explain-to-me/SKILL.md +192 -0
package/plugins/session-manager-dev/skills/explain-to-me/assets/style-reference.html +163 -0
package/plugins/session-manager-dev/skills/local-project-health/SKILL.md +58 -0
package/plugins/session-manager-dev/skills/my-feedback/SKILL.md +132 -0
package/plugins/session-manager-dev/skills/optimize-kpi/SKILL.md +289 -0
package/plugins/session-manager-dev/skills/prd/SKILL.md +134 -0
package/plugins/session-manager-dev/skills/process-feedback/SKILL.md +183 -0
package/plugins/session-manager-dev/skills/project-status/SKILL.md +244 -0
package/plugins/session-manager-dev/skills/requesting-code-review/SKILL.md +105 -0
package/plugins/session-manager-dev/skills/requesting-code-review/code-reviewer.md +146 -0
package/plugins/session-manager-dev/skills/security-review/SKILL.md +105 -0
package/src/main/__tests__/scheduler-autofix-select.test.cjs +95 -0
package/src/main/__tests__/scheduler-autopromote.test.cjs +33 -0
package/src/main/hives.cjs +96 -36
package/src/main/scheduler.cjs +135 -11
package/src/main/templates/PRD_AUTHORING.md +316 -0
package/src/preload/api.d.ts +8 -7
package/dist/assets/index-BKkf6gtA.css +0 -32
package/dist/assets/index-C61eFtxs.js +0 -3525

package/plugins/session-manager-dev/skills/explain-to-me/assets/style-reference.html ADDED Viewed

@@ -0,0 +1,163 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>explain-to-me · style reference (copy this)</title>
+<!--
+  STYLE REFERENCE for the /explain-to-me skill.
+  This is a complete, self-contained exemplar page. When writing a HUMAN_LEARN
+  page, mirror this structure and CSS. Replace the placeholder "Widget Pipeline"
+  content with the real, file:line-grounded explanation of the user's topic.
+  Every component below is optional — use the ones the topic needs.
+-->
+<style>
+  :root{
+    --bg:#0d1117; --panel:#161b22; --panel2:#1c2330; --line:#2d333b;
+    --fg:#e6edf3; --dim:#9da7b3; --faint:#6e7681;
+    --blue:#60a5fa; --green:#34d399; --amber:#fbbf24; --violet:#a78bfa;
+    --pink:#f472b6; --red:#f87171; --cyan:#22d3ee;
+    --mono:ui-monospace,'SF Mono',Menlo,Consolas,monospace;
+  }
+  *{box-sizing:border-box;margin:0;padding:0}
+  html{scroll-behavior:smooth}
+  body{background:var(--bg);color:var(--fg);font:15px/1.6 ui-sans-serif,system-ui,sans-serif;padding:0 20px 80px}
+  .wrap{max-width:980px;margin:0 auto}
+  a{color:var(--blue);text-decoration:none} a:hover{text-decoration:underline}
+  .crumb{font-size:12px;color:var(--faint);margin:24px 0 14px}
+  h1{font-size:28px;letter-spacing:-.5px;margin-top:26px}
+  .sub{color:var(--dim);margin:8px 0 6px;max-width:780px}
+  h2{font-size:22px;margin:44px 0 12px;padding-top:18px;border-top:1px solid var(--line)}
+  h3{font-size:16px;margin:24px 0 8px}
+  p{margin:8px 0;color:var(--dim)} p strong,li strong{color:var(--fg)}
+  ul.tight{margin:6px 0 6px 20px;color:var(--dim);font-size:13.5px} ul.tight li{margin:4px 0}
+  code{font-family:var(--mono);font-size:12.5px;background:var(--panel2);border:1px solid var(--line);border-radius:4px;padding:1px 5px;color:var(--fg);white-space:nowrap}
+  pre{font-family:var(--mono);font-size:12px;background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:14px 16px;overflow-x:auto;margin:10px 0;line-height:1.55}
+  pre code{background:none;border:none;padding:0;white-space:pre}
+  /* signature element: every file:line reference is a traceable chip */
+  .loc{font-family:var(--mono);font-size:11px;color:var(--cyan);background:rgba(34,211,238,.08);border:1px solid rgba(34,211,238,.25);border-radius:99px;padding:1px 9px;white-space:nowrap}
+  /* layer badges — one color per place a step runs */
+  .proc{font-size:11px;text-transform:uppercase;letter-spacing:.08em;padding:1px 8px;border-radius:99px;border:1px solid}
+  .proc.hook{color:var(--amber);border-color:rgba(251,191,36,.4);background:rgba(251,191,36,.07)}
+  .proc.main{color:var(--green);border-color:rgba(52,211,153,.4);background:rgba(52,211,153,.07)}
+  .proc.sub{color:var(--violet);border-color:rgba(167,139,250,.4);background:rgba(167,139,250,.07)}
+  .proc.rend{color:var(--pink);border-color:rgba(244,114,182,.4);background:rgba(244,114,182,.07)}
+  .proc.disk{color:var(--cyan);border-color:rgba(34,211,238,.4);background:rgba(34,211,238,.07)}
+  .legend{display:flex;flex-wrap:wrap;gap:14px;margin:10px 0;font-size:12px;color:var(--dim)}
+  /* sticky in-page nav */
+  nav.toc{position:sticky;top:0;z-index:10;background:rgba(13,17,23,.92);backdrop-filter:blur(6px);border-bottom:1px solid var(--line);margin:0 -20px;padding:10px 20px}
+  nav.toc .row{max-width:980px;margin:0 auto;display:flex;gap:8px;flex-wrap:wrap}
+  nav.toc a{font-size:13px;padding:4px 14px;border-radius:99px;border:1px solid var(--line);color:var(--dim)}
+  nav.toc a:hover{color:var(--fg);border-color:var(--faint);text-decoration:none}
+  /* stat strip */
+  .statline{display:flex;gap:18px;flex-wrap:wrap;margin:16px 0}
+  .stat{background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:10px 18px}
+  .stat .v{font-size:22px;font-weight:700} .stat .k{font-size:11px;text-transform:uppercase;letter-spacing:.07em;color:var(--faint)}
+  /* horizontal flow diagram */
+  .flow{display:flex;flex-wrap:wrap;gap:8px;align-items:stretch;margin:16px 0}
+  .flow .box{flex:1 1 150px;min-width:150px;background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:10px 12px}
+  .flow .box .bt{font-weight:700;font-size:13px;margin-bottom:2px}
+  .flow .box .bd{font-size:12px;color:var(--dim)}
+  .flow .box .where{font-family:var(--mono);font-size:10px;color:var(--cyan);margin-top:6px}
+  .flow .arrow{align-self:center;color:var(--faint);font-size:18px;flex:0 0 auto}
+  .box.b-amber{border-top:3px solid var(--amber)} .box.b-green{border-top:3px solid var(--green)}
+  .box.b-violet{border-top:3px solid var(--violet)} .box.b-cyan{border-top:3px solid var(--cyan)}
+  .box.b-pink{border-top:3px solid var(--pink)}
+  /* callouts */
+  .callout{border-left:3px solid var(--amber);background:rgba(251,191,36,.06);border-radius:0 8px 8px 0;padding:12px 16px;margin:14px 0;font-size:14px;color:var(--dim)}
+  .callout.ok{border-color:var(--green);background:rgba(52,211,153,.06)}
+  .callout.bad{border-color:var(--red);background:rgba(248,113,113,.06)}
+  .callout strong{color:var(--fg)}
+  /* tables + collapsible knobs */
+  table{border-collapse:collapse;width:100%;margin:12px 0;font-size:13px}
+  th,td{text-align:left;padding:6px 11px;border:1px solid var(--line)}
+  th{background:var(--panel2);font-size:11.5px;text-transform:uppercase;letter-spacing:.05em;color:var(--dim)}
+  td{background:var(--panel);color:var(--dim)} td code{white-space:nowrap}
+  details.consts summary{cursor:pointer;font-size:13px;color:var(--blue);margin:10px 0}
+  /* two-column rationale */
+  .twocol{display:grid;grid-template-columns:1fr 1fr;gap:16px}
+  @media(max-width:760px){.twocol{grid-template-columns:1fr}.flow .box{flex-basis:100%}}
+  footer{margin-top:60px;padding-top:16px;border-top:1px solid var(--line);font-size:12px;color:var(--faint)}
+</style>
+</head>
+<body>
+<nav class="toc"><div class="row">
+  <a href="index.html">📖 HOME</a>
+  <a href="#flow">Flow</a>
+  <a href="#knobs">Knobs</a>
+  <a href="#why">Why</a>
+</div></nav>
+<div class="wrap">
+  <div class="crumb"><a href="index.html">HUMAN_LEARN</a> / Widget Pipeline</div>
+  <h1>⚙️ Widget Pipeline — how a request becomes a widget</h1>
+  <p class="sub">
+    One-sentence lead: what this is and when it runs. (Replace this whole page with the
+    real, <code>file:line</code>-grounded explanation of the user's topic — this file is only the
+    visual template.)
+  </p>
+  <div class="legend">
+    <span><span class="proc hook">trigger</span> what kicks it off</span>
+    <span><span class="proc main">core</span> main logic</span>
+    <span><span class="proc sub">worker</span> spawned work</span>
+    <span><span class="proc disk">store</span> persistence</span>
+  </div>
+  <div class="statline">
+    <div class="stat"><div class="v">5</div><div class="k">stages</div></div>
+    <div class="stat"><div class="v">20</div><div class="k">batch cap</div></div>
+    <div class="stat"><div class="v">8&nbsp;MB</div><div class="k">read window</div></div>
+  </div>
+  <h2 id="flow">The flow, step by step</h2>
+  <div class="flow">
+    <div class="box b-amber"><div class="bt">1 · Trigger</div><div class="bd">what starts it</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-green"><div class="bt">2 · Read</div><div class="bd">bounded input read</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-green"><div class="bt">3 · Transform</div><div class="bd">the core step</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-sub b-violet"><div class="bt">4 · Work</div><div class="bd">spawned subprocess</div><div class="where">file.ext:NN</div></div>
+    <div class="arrow">→</div>
+    <div class="box b-cyan"><div class="bt">5 · Persist</div><div class="bd">atomic write</div><div class="where">file.ext:NN</div></div>
+  </div>
+  <h3>3 · Transform <span class="proc main">core</span> <span class="loc">file.ext:120-148</span></h3>
+  <p>Prose explaining the step, with inline <code>constants</code> and a <span class="loc">file.ext:NN</span> for
+  each claim. Show a real snippet when it clarifies:</p>
+  <pre><code>doThing(input, { cap: 20, windowBytes: 8 * 1024 * 1024 })</code></pre>
+  <div class="callout ok"><strong>Key insight.</strong> The one thing a reader must take away —
+  e.g. why the design is correct, or the invariant it preserves.</div>
+  <h2 id="knobs">The knobs</h2>
+  <details class="consts" open><summary>All constants (real names + values)</summary>
+  <table>
+    <tr><th>Constant</th><th>Value</th><th>Where</th><th>Bounds</th></tr>
+    <tr><td><code>BATCH</code></td><td>20</td><td><span class="loc">file.ext:50</span></td><td>items per unit of work</td></tr>
+    <tr><td><code>MAX_BYTES</code></td><td>8 MB</td><td><span class="loc">file.ext:52</span></td><td>read window per run</td></tr>
+  </table>
+  </details>
+  <h2 id="why">Why it's shaped this way</h2>
+  <div class="twocol">
+    <div><h3>Constraint A</h3><p>The real reason — an incident, a platform limit, a cost guard.</p></div>
+    <div><h3>Constraint B</h3><p>Another forcing function that explains a non-obvious choice.</p></div>
+  </div>
+  <footer>
+    HUMAN_LEARN · &lt;project&gt; · generated &lt;date&gt; from <code>file.ext</code> + live on-disk state.
+  </footer>
+</div>
+</body>
+</html>

package/plugins/session-manager-dev/skills/local-project-health/SKILL.md ADDED Viewed

@@ -0,0 +1,58 @@
+---
+name: local-project-health
+description: >-
+  Run the CURRENT project's own definition of "health" and report one rollup.
+  Each project defines health differently (a trading bot tracks circuit-breakers
+  + benchmark alpha; a web app tracks uptime + error rate), so this skill runs
+  the project-supplied health entrypoint rather than imposing a generic check.
+  Use whenever the user asks "is this project healthy?", "/local-project-health",
+  "system health", "is everything running / green", or wants a one-shot status
+  rollup for the repo they're in. Keywords: health, status, healthcheck, is it
+  up, are we green, rollup, system health, project health.
+---
+# Local project health
+Report a single health verdict for the project in the current working directory
+by running **that project's own** health definition. Health is project-specific
+by design — do not invent generic checks.
+## Procedure
+1. **Find the project's health entrypoint**, checking these paths in order
+   (first hit wins):
+   - `scripts/health.sh`
+   - `.claude/health.sh`
+   - `bin/health.sh`
+   - `Makefile` / `justfile` target named `health`
+2. **If an entrypoint exists**, run it from the repo root and relay its output:
+   - `bash scripts/health.sh` (or the path found / `make health` / `just health`).
+   - These scripts are designed to print a human rollup and exit 0/1/2
+     (GREEN/YELLOW-or-UNKNOWN/RED). Show the user the rollup verbatim, then add a
+     one-line plain-English verdict leading with the overall color and the worst
+     layer (e.g. "🟡 YELLOW — performance is the drag: −3 pts vs SPY").
+   - If the script persists a structured artifact (e.g.
+     `data/system_health.json`), mention where it landed.
+   - If it exits non-zero, that is expected for YELLOW/RED — it is NOT a skill
+     failure. Only treat a *crash* (missing interpreter, traceback, unbound var)
+     as a failure to debug.
+3. **If NO entrypoint exists**, do not guess at health with ad-hoc commands.
+   Instead:
+   - Read `CLAUDE.md`, `README*`, and skim the repo to infer what "health" means
+     for THIS project (what it monitors, what would constitute degraded/broken).
+   - Propose a concrete `scripts/health.sh` that collapses those project-specific
+     layers into one GREEN/YELLOW/RED rollup (terminal output + a persisted
+     `*.json` artifact), reusing the project's existing CLIs/artifacts rather
+     than re-deriving thresholds.
+   - Offer to create it. Once created, it becomes the convention this skill runs
+     on every future invocation.
+## Notes
+- The contract is the **convention path**, not a shared implementation: every
+  project owns its own `scripts/health.sh`. This skill is just the launcher +
+  interpreter of the result.
+- Keep the relayed summary tight: overall color first, then the offending
+  layer(s), then where the full report is. Lead with the answer.

package/plugins/session-manager-dev/skills/my-feedback/SKILL.md ADDED Viewed

@@ -0,0 +1,132 @@
+---
+name: my-feedback
+description: >-
+  File a feedback/enhancement request FROM the current project INTO another
+  project's inbound feedback folder, following that project's own README
+  convention. The cross-project complement of /process-feedback (which works the
+  *current* project's inbox). Use whenever the user says "/my-feedback to X",
+  "send feedback to X", "file a feedback item to X", "request an enhancement
+  from X", "drop a note in X's feedback folder", or "ask X to add/fix Y". The
+  target project MUST be named — error if it is missing. Keywords: feedback,
+  cross-project request, enhancement request, upstream, downstream, service
+  boundary, file feedback, request a feature, inter-service.
+---
+# my-feedback
+**Role:** the *outbound* end of the agent↔agent channel — it files a request into another
+project's intake, where their `/process-feedback` picks it up and (if codeable) runs it
+through their `/develop` pipeline. It is the send side; `/process-feedback` is the receive
+side. **Never** cross the service boundary to fix the other project's code yourself — the
+deliverable is an auditable request, not a patch.
+Write one actionable feedback file into **another** project's intake folder, so
+the team that owns the boundary can act on it via their `/process-feedback`. The
+current project is the **From**; the named project is the **To**.
+This is the send side of the same channel `/process-feedback` reads. Respect the
+service boundary: you are *requesting* a change in their code, never reaching
+across to make it yourself.
+## 0. Resolve the target — error if missing
+The invocation is `/my-feedback to <<project>>` (or "send feedback to
+<<project>>"). **`<<project>>` is required.**
+- **If no target project is named, STOP and error.** Do not guess, do not file
+  into the current project. Print: *"Name the target project: `/my-feedback to
+  <project>`."* Then list candidate sibling projects that have an intake folder:
+  ```bash
+  for d in ~/Projects/*/; do
+    [ -d "$d/feedback" ] && echo "  - $(basename "$d")  (feedback/)"
+    [ -d "$d/external-feedback" ] && echo "  - $(basename "$d")  (external-feedback/)"
+  done
+  ```
+  and stop.
+- Resolve the path: `~/Projects/<project>/feedback/` (some projects
+  use `external-feedback/` — check both). Fuzzy-match a near miss to a real
+  directory, but confirm the resolved name before writing.
+- **If the target has no feedback/external-feedback folder, STOP.** Don't invent
+  one — say the project doesn't accept feedback this way and ask how to proceed
+  (it may take requests via issues, a different folder, or not at all).
+## 1. Read the target's README FIRST — it is the authority
+**Every project's feedback folder has its own `README.md`, and the convention is
+unique per project** (file-naming scheme, required sections, the status-log
+table, the closing ritual). Read it before writing anything:
+```bash
+cat ~/Projects/<project>/feedback/README.md
+ls  ~/Projects/<project>/feedback/                # open items + numbering
+ls  ~/Projects/<project>/feedback/processed/ 2>/dev/null   # closed examples to match
+```
+Read one **processed** example end-to-end to copy the house format exactly — the
+processed files are the calibrated bar. If the README and an example disagree,
+the example wins (it's what actually got accepted).
+## 2. Name the file by their convention
+Most intakes use `YYYY-MM-DD-NN-short-slug.md` (today's date, next free `NN` for
+the day — check existing files so you don't collide). Use the **target's** scheme
+if it differs. The "From" is the **current project** — derive it from the cwd
+basename, not an assumption.
+## 3. Write to the bar — make it closeable without a back-and-forth
+These hold across every intake (and most READMEs say the same):
+- **Cite real `file:line` from the target's current `src/`** — verify by `grep`,
+  not memory. "You spawn a process per call — `_burrow_mcp.py:75`" beats "your
+  transport seems slow." Quote the offending code, then name the contract/PRD it
+  violates so the gap is self-evident.
+- **Lead with the cost already paid.** A concrete incident ("the silent 11-day
+  mentions hole", "shorted into earnings on a stale zero") earns priority over a
+  hypothetical. Tie it to money/correctness, not taste.
+- **Give a copy-pasteable Fix _and_ the deps to unblock it** (env var, new tool,
+  rate bucket). Don't leave the closer to discover side-asks.
+- **Separate "must change" from "nice."** Credit what's already right so the file
+  reads as calibrated, not a pile-on.
+- **Name the symptom and hypothesize the cause, but don't confidently assign the
+  fix's home.** A wrong attribution stalls; "frozen at 06-08 (evidence) — maybe
+  scoring, maybe upstream gather" closes faster.
+- **Flag third-service dependencies up front.** If an ask needs *another*
+  project's tool/contract to land, say so — the closer forwards it on day one
+  instead of discovering it mid-fix. (You can also file the dependent half
+  directly into that third project with another `/my-feedback` pass.)
+- **End with concrete Asks + the target's closing ritual** (the README usually
+  specifies marking ✅ and appending `## RESOLUTION`). State what "done" looks
+  like, with an acceptance test per ask.
+- **One file = one coherent thread, scoped to the boundary.** Don't smuggle in
+  unrelated requests.
+Anti-patterns that stall: vague severity ("seems slow"), no reproduction, fixes
+that assume internals the other team can't see, asks with no acceptance test.
+## 4. Register and hand off
+- If the README keeps a **status-log table**, add a row for the new item (open/🆕)
+  using their exact column format. This is usually required — the log is the
+  durable index.
+- **Don't commit or push into the target repo unless the user asks.** The file in
+  their tree is the deliverable; their team picks it up via `/process-feedback`.
+  If you do commit, commit in the **target** repo only, and never touch their
+  source — just the feedback file + README log row.
+- Report back: the file path written, the From→To, priority, and the one-line
+  ask — so the user can relay or follow up.
+## Tips
+- **You're the sender, not the fixer.** Resist editing the target's code to
+  "just fix it" — that violates the boundary the channel exists to protect. The
+  whole point is an auditable request the owner acts on.
+- **Mirror their tone.** A terse intake wants terse; a structured one wants every
+  section. Match the processed examples.
+- **Reuse evidence you already have.** If this session surfaced the incident
+  (logs, audit rows, live tool output), quote it verbatim — freshly-gathered
+  `file:line` and timestamps are exactly what makes a file closeable.
+- **Stale-claim guard.** Feedback captures the world when written; note the
+  as-of timestamp on live data you cite, so the closer knows what to re-verify.
+- **If the right home is a third project,** file there too rather than overloading
+  one team with an ask they can only forward.

package/plugins/session-manager-dev/skills/optimize-kpi/SKILL.md ADDED Viewed

@@ -0,0 +1,289 @@
+---
+name: optimize-kpi
+description: >-
+  Project-agnostic North-Star-KPI optimization cycle. Reads the current project's
+  declared North-Star KPI from its CLAUDE.md, measures it, audits real
+  consumption/usage telemetry + operational logs, grades the prior iteration's
+  filed lever, then fans out 3 INDEPENDENT recommender agents (Opus 4.8, max
+  thinking) that each diagnose the gap and propose the single
+  highest-leverage improvement — every recommendation grounded in usage + logs,
+  not the scorecard alone; one consolidator agent merges them into ONE feedback
+  item filed into this project's own feedback inbox plus a ranked backlog.
+  Implementation is NEVER done inline — it always goes through the scheduler via
+  /process-feedback → /develop. Use whenever the user says "/optimize-kpi",
+  "optimize the KPI", "improve our north-star metric", or runs the daily KPI
+  optimization loop. Keywords: optimize, KPI, north-star, metric, coverage,
+  recommenders, consolidate, feedback, scheduler, attribution.
+model: opus
+---
+# /optimize-kpi — measure → grade last lever → 3 recommenders → consolidate → file → scheduler
+You are the optimization driver for **whatever this project has declared as its
+North-Star KPI**. You do not implement code. Each run is one closed iteration of a
+*converging* loop: **discover the KPI → measure + validate → grade the prior
+lever → fan out 3 independent recommenders → consolidate into one feedback item +
+backlog → hand off to the scheduler → log**.
+**Non-negotiable: never implement, review, commit, publish, or reboot inline.**
+The single consolidated recommendation is filed into this project's own feedback
+inbox and dispatched through **`/process-feedback` → `/develop`**, which queues
+PRDs onto the session-manager scheduler and tracks them to done. Bypassing the
+scheduler is the one thing this skill must not do.
+**Autonomy contract.** This skill is usually driven headless by a cron with
+`--dangerously-skip-permissions`, so it must run to completion without human
+input. **Never call `AskUserQuestion` or otherwise block on a prompt in loop
+mode.** If a decision genuinely needs the operator, take the reversible default,
+record the open question as a `> NOTE:` line in the feedback item, and continue —
+do not stall the loop. (Interactive, user-invoked runs may ask; detect this by
+whether a human is in the turn.)
+## Step 0 — Discover the project's North-Star KPI (do not assume)
+The KPI lives in the project's mission statement: read `./CLAUDE.md` and find the
+section whose heading names the **North-Star KPI** (e.g. `## Objective &
+North-Star KPI`). That section is the authority. Extract, by reading it and the
+files it points to:
+- **The KPI statement** — what is being optimized, the target (usually 100% / a
+  ceiling), and the precise definition doc it links (e.g. `docs/<kpi>.md`).
+- **The measurement command** — the scorecard/metric script it names (e.g.
+  `scripts/coverage_scorecard.py`). Prefer a `--json` form and a `--trend N`
+  form if they exist.
+- **The driving pipeline(s)** — which scheduled job(s) actually move the metric
+  (the gatherer/worker named in the KPI section or registry). You need this for
+  the validity gate in Step 1.
+- **The usage / consumption audit** — how the project's *outputs* are consumed
+  and the operational logs that show whether the machine is healthy. The CLAUDE.md
+  observability/telemetry pointer names them (e.g. a usage-audit script over a
+  request log, a metrics endpoint, the run-history DB, `data/logs/`). Capture the
+  exact audit command(s). If the project exposes **no** consumption telemetry at
+  all, that itself is a finding — recommend adding it.
+- **The levers** — the files the section names as the knobs (tiers/config,
+  selection, throughput/cadence/registry, etc.).
+- **The feedback intake** — `feedback/` (or `external-feedback/`) at the repo
+  root, and its `README.md` convention.
+**If CLAUDE.md declares no North-Star KPI section, STOP** and tell the user this
+project hasn't declared one — the KPI belongs in CLAUDE.md's mission statement
+(that's the convention this skill reads), and ask them to add it before running.
+Capture the discovered KPI statement, measurement command, driving pipeline,
+lever files, and intake path — you pass all of them verbatim into the recommender
+agents so they work from the project's own definition, not your guess.
+## Step 1 — Measure + validity gate (don't tune a corpse)
+Run the discovered measurement command in both its snapshot and trend forms (e.g.
+`<scorecard> --json` and `<scorecard> --trend 14`). Read the JSON outputs. Record:
+today's KPI value, any floor/SLO breaches, per-segment breakdown, the
+worst-performing units, and the trend direction over the last several days. This
+evidence block is the shared input every recommender receives.
+**Validity gate — before diagnosing, prove the metric is real.** A low KPI has
+two very different causes: a *mis-set knob* (a tuning problem) or *the driving
+pipeline didn't run / is wedged* (an ops problem). Confirm the Step-0 driving
+pipeline actually produced work in the measurement window — check the
+orchestrator/run history (last successful run, duration, whether it hung to its
+max-duration cap or held a lock). If the pipeline **did not run a healthy cycle
+in the window**, the metric is an artifact:
+- Do **not** run the recommender fan-out. A selection/tiering "fix" against a
+  dead pipeline is noise.
+- File a single feedback item whose Ask is **"restore the driving pipeline"**
+  (cite the stuck/missing runs), hand it to the scheduler (Step 5), log it, and
+  stop the iteration there.
+Only when the metric reflects a pipeline that genuinely ran do you proceed to the
+tuning loop.
+## Step 1b — Audit usage + logs (MANDATORY evidence, not optional)
+The scorecard says *how high* the KPI is; it never says *why*. The why lives in
+how the project's outputs are actually consumed and what the logs are screaming.
+**This step is required every run — a recommendation that cites only the
+scorecard is rejected in Step 4.**
+- **Usage / consumption audit.** Run the Step-0 usage-audit command (for a
+  contract/MCP project, the per-consumer + per-tool telemetry; for others, the
+  request/access log or metrics endpoint). Extract: who the consumers are, the
+  call distribution across outputs, **dark outputs** (shipped but never consumed),
+  **error hotspots** (esp. a write/auth path failing silently), and **latency/SLO
+  breaches**. Consumption shape tells you what's load-bearing vs dead weight — you
+  do not optimize what nobody reads, and a silently-failing consumer is often the
+  real KPI gap.
+- **Operational-log audit.** Scan the run history + `data/logs/` (or the
+  project's log sink) for failed/stuck runs, repeated errors, max-duration
+  overruns, and lock contention in the measurement window. These are frequently
+  the *direct* root cause of a depressed KPI (e.g. the gatherer hitting its
+  duration cap → fewer units visited → coverage falls) — and they're invisible to
+  the scorecard.
+Produce a compact **usage+log evidence block** alongside the Step-1 scorecard
+block. Both are handed to every recommender. If the audit surfaces an ops failure
+that is *itself* the dominant KPI cause (a dead consumer, a crashing pipeline),
+treat it like the validity gate: the recommendation is "fix that," and you may
+skip the tuning fan-out.
+## Step 2 — Grade the prior lever + read in-flight work (close the loop)
+Before proposing anything new, find out what the *last* iteration did and whether
+it worked. Open-loop optimizers don't converge — this step is what makes the loop
+learn.
+- **Read the optimization log** (`docs/kpi-optimization-log.md`, if present) for
+  the last filed lever, its predicted effect, and its measure-by date.
+- **Check whether it shipped:** look at the feedback folder (is last run's item
+  ✅/archived?) and the scheduler's PRD history for the ids it queued. Status:
+  *not yet queued* / *queued, running* / *shipped on `<date>`* / *failed*.
+- **Grade it against the metric:** if it shipped, compare the KPI/breach numbers
+  before vs after its ship date using the Step-1 trend. Did it move the metric in
+  the predicted direction and magnitude? Record `helped` / `no-effect` /
+  `regressed` / `too-early-to-tell`.
+- **Build the in-flight + cooldown set:** list every lever currently *queued or
+  awaiting its first post-ship measurement*. These are **off-limits this run** —
+  do not let the recommenders or consolidator re-file a lever that is already in
+  flight or whose effect hasn't been measured yet (cooldown). Re-filing the same
+  ask stacks duplicate PRDs on the scheduler and never learns.
+Carry forward into Step 3: `{last lever, its grade, why it under/over-performed,
+the in-flight/cooldown lever set}`.
+## Step 3 — Fan out 3 INDEPENDENT recommenders (parallel)
+Spawn **3 Agent calls in a single message** so they run concurrently and blind to
+each other. Each is a peer doing the full diagnosis independently — divergence is
+the point; do not coordinate them. (Default panel = 3; you may scale to 4–5 when
+the gap is large and token budget allows, or drop to 2 for a tiny gap — note the
+choice.)
+- **Model:** `opus` (Opus 4.8) with **failover to `sonnet`** — launch each agent
+  with `model: opus`; if an agent dies on a model/availability error, re-spawn
+  that one with `model: sonnet`. A **mixed panel** (some opus, some sonnet) is
+  fine — don't block waiting for a uniform fleet. (Fable is not GA and only
+  causes availability failures — do not use it.) Instruct each to think at
+  **maximum depth** before answering.
+- **Prompt (identical for all 3, vary only an angle hint):** give each the KPI
+  statement, the definition doc path, the Step-1 scorecard block, the **Step-1b
+  usage+log evidence block**, the **Step-2 prior-lever grade + in-flight/cooldown
+  set**, the lever files, and the project's standing design directives from the
+  KPI section. Ask each to:
+  1. Diagnose *why* the KPI is below target — name the single root cause with the
+     highest expected KPI delta. **Ground the diagnosis in the usage+log evidence,
+     not the scorecard alone:** cite the specific consumer behaviour, dark output,
+     error hotspot, or failing/over-running run that supports the root cause. A
+     diagnosis with no usage/log citation is not acceptable. Account for the prior
+     lever's result: if it under-performed, say why and whether to escalate or
+     abandon it.
+  2. Propose ONE concrete, highest-leverage change as numbered implementation
+     steps an executor could follow without further design: exact file(s), the
+     change, the lever value, the **expected KPI/breach delta as a falsifiable
+     numeric target with a measure-by horizon** (e.g. "floor breaches 82→<40
+     within 2 days"), and how the next measurement run will confirm it. Quality
+     bar / service contracts stay fixed — never raise the KPI by lowering a
+     quality gate. **Must not** be a lever in the in-flight/cooldown set.
+  3. State assumptions and the one risk that would make it backfire.
+  Give each a different framing nudge so they don't converge: e.g. agent 1
+  "selection/throughput first", agent 2 "tiering/cadence/targets-achievability
+  first", agent 3 "consolidation/architecture first". The nudge biases the lens,
+  not the conclusion — each still considers all levers.
+- **Output:** each agent **writes its recommendation to a temp file** and returns
+  the path. Use a per-run temp dir derived from the project + date, e.g.
+  `downloads/optimize-kpi/<YYYY-MM-DD>/agent-{1,2,3}.md` (create it; fall back to
+  `/tmp/optimize-kpi-<date>/` if `downloads/` doesn't exist). One file per agent,
+  full reasoning + the numbered steps. (Old per-run dirs are disposable — GC dirs
+  older than ~14 days when you create today's.)
+## Step 4 — Consolidate into ONE recommendation + a ranked backlog (single agent)
+Spawn **one** consolidator agent (same `opus`→`sonnet` failover, max thinking).
+Give it the 3 temp files **and** the Step-2 in-flight/cooldown set. It must:
+- Read all three, dedupe overlapping ideas, and **score** the distinct proposals
+  by expected KPI delta × achievability × reversibility.
+- **Reject any proposal not grounded in the usage+log evidence** — a root cause
+  citing only the scorecard is not eligible. The winning lever must trace to an
+  observed consumer behaviour, dark output, error hotspot, or failing/over-running
+  run.
+- **Drop any proposal that collides with the in-flight/cooldown set** (already
+  queued or awaiting measurement) — those are not eligible this run.
+- **Pick the single highest-leverage *eligible* lever** to change this iteration
+  (resist bundling — one lever per iteration), grafting the best supporting ideas
+  from the runners-up into the plan where they strengthen it.
+- Verify targets are achievable for real throughput — if a proposal sets targets
+  the system can't meet, say so and adjust rather than let the KPI lie.
+- **Route the lever by ownership first.** If the winning lever's root cause
+  belongs to an **upstream/downstream service** — the data source hasn't gathered
+  the inputs, an upstream contract drifted, a consumer needs a change — the
+  deliverable is a **cross-project filing via `/my-feedback <project>`** into THAT
+  service's intake, not a this-project item this repo can't action. (Canonical
+  case: signal-builder's sellable-KPI binding constraint is frequently the
+  `acquisition` cohort — tickers Burrow simply hasn't gathered — which is filed to
+  `burrow`, per this project's CLAUDE.md North-Star section.) A this-project-owned
+  lever is filed here (next bullet); a **mixed** lever splits — the local half here
+  via `/develop`, the upstream half via `/my-feedback`, each cross-referencing the
+  other. Leaving an upstream-owned lever buried as a local item it can't fix is the
+  failure mode this rule exists to prevent.
+- **Write ONE consolidated feedback item** (for the this-project-owned half) into
+  this project's intake folder, named by the folder README's convention
+  (`feedback/<YYYY-MM-DD>-NN-kpi-optimization.md`, next free `NN`), with: title,
+  **From:** `optimize-kpi loop`, date (PT), priority + why, **TL;DR**, **Evidence**
+  (cite the Step-1 scorecard numbers, the **Step-1b usage+log findings** the root
+  cause rests on, *and* the Step-2 prior-lever grade), **Why it matters**
+  (expected KPI gain), and **Ask** (the numbered implementation steps from the
+  winning proposal). The Ask **must** carry a falsifiable acceptance test: the
+  numeric success criterion + measure-by date the next run will grade it against.
+  Note which of the 3 agents it drew from and why it rejected the others.
+- **Write/refresh a ranked backlog** at `docs/kpi-optimization-backlog.md`: the
+  eligible-but-not-chosen levers, ranked, each with its one-line rationale and
+  expected delta. The next iteration reads this first and can pull the next-best
+  lever without re-deriving from scratch. Remove entries that shipped or went
+  stale.
+The consolidator writes the feedback file + backlog; it does **not** touch
+project source.
+## Step 5 — Hand off to the scheduler (do NOT implement)
+Dispatch the consolidated item through the scheduler pipeline:
+- Invoke **`/process-feedback`**, scoped to the one file you just wrote (name it
+  explicitly — never let it sweep unrelated open items). `/process-feedback`
+  evaluates it and queues the codeable work as PRDs via **`/develop`** onto the
+  session-manager scheduler, then tracks those PRDs to completion.
+- This skill does **not** edit code, run `/code-review`/`/security-review`, bump
+  `VERSION`, commit, or reboot anything. All of that happens as the scheduled
+  PRDs run headlessly. Your job ends at "filed + dispatched + tracked".
+## Step 6 — Log the iteration
+Append one line to `docs/kpi-optimization-log.md` (create if missing):
+`<date> | KPI <today> (trend <dir>) | breaches <n> | prior lever: <one-line> → <helped|no-effect|regressed|too-early> | lever filed: <one-line> (target: <numeric>, by <date>) | feedback: <file> | PRDs: <ids or "queued">`.
+This is the running record — and the input Step 2 grades next time.
+## Stop conditions
+- **No KPI declared** (Step 0) → STOP, ask the user to add it to CLAUDE.md.
+- **Validity gate fails** (Step 1) → file the "restore the driving pipeline" item,
+  hand off, log, and stop the iteration — skip the tuning fan-out entirely.
+- **Step-1b audit finds an ops failure that is itself the dominant KPI cause**
+  (a dead/failing consumer, a crashing or max-duration-overrunning pipeline) →
+  file *that* fix and skip the tuning fan-out; it outranks any tuning lever.
+- **KPI already at/above target** with zero breaches for 2 consecutive days →
+  file a *consolidation / quality-hardening* recommendation instead of a coverage
+  one (move toward the architecture end-state the KPI section describes).
+- **Everything eligible is in-flight/cooldown** (Step 2 leaves no eligible lever)
+  → do not invent a duplicate. Log "no eligible lever — N in flight" and stop;
+  next run grades them.
+- **Measurement, the agents, or `/process-feedback` fail** → STOP, leave the tree
+  untouched (you never modified source anyway), and report what broke. Never file
+  a recommendation built on a failed measurement.
+## Scheduling
+Typically run as a daily `/loop` (the project may install a cron that drives this
+skill headless). Each firing runs Steps 0–6 once. Because implementation is
+delegated to the scheduler, this skill stays fast and side-effect-light: its only
+writes to the repo are the temp recommender files, the one feedback item, the
+backlog, and the log line.