claude-code-session-manager 0.27.0 → 0.28.0

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

@@ -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

@@ -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

@@ -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.

package/plugins/session-manager-dev/skills/prd/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: prd
+description: >-
+  Write a PRD for the session-manager scheduler queue (the right place for
+  token-budget-managed work). Use this whenever the user says "make this a PRD",
+  "queue this up", "add to the scheduler", or asks for a PRD without specifying a
+  target location. Keywords: prd, queue, scheduler, scheduled-plans, token budget.
+---
+
+# /prd — author one scheduler PRD
+
+**Role:** `/prd` is the single authority on one PRD's *structure, location, and scope sizing*. It does not own the engineering rules (that's `standards.md`) and does not decompose a large ask into multiple PRDs (that's `/develop`). Never restate rules that live in `standards.md` — reference and append them.
+
+You are writing a PRD that will be executed by the user's session-manager scheduler — a system that runs `claude -p <prd-body> --dangerously-skip-permissions` jobs around 5-hour token-window resets, with auto-pause on rate-limit and auto-resume.
+
+## Canonical location — non-negotiable
+
+PRDs MUST be written to:
+
+```
+~/.claude/session-manager/scheduled-plans/prds/<NN>-<kebab-slug>.md
+```
+
+**Anywhere else doesn't get scheduled.** If you write to `data/prds/`, `docs/prds/`, or the project root, the scheduler will not see it and the user loses their token-budget-managed execution. There is exactly one queue for all projects — that's intentional, because the 5-hour token budget is global across all of the user's Claude work. The `~` expands to `os.homedir()` so the same convention works for any user on any machine.
+
+## Filename rules
+
+- `NN` is the **parallel group** (2-digit zero-padded). Jobs in the same group run in parallel up to a concurrency cap; groups run serially. Pick `NN` by reading the existing files in `~/.claude/session-manager/scheduled-plans/prds/` and choosing:
+  - The same `NN` as a sibling that's logically independent and can run in parallel.
+  - The next unused `NN` if this PRD has a hard dependency on prior work landing first.
+- `<kebab-slug>` is a short, descriptive kebab-case identifier (e.g. `voice-commands-send-cancel`, `ticker-velocity-mcp`). Keep under 60 chars.
+
+Compute the current max `NN` **deterministically** before writing — do NOT eyeball the `ls` or narrow the pattern (a grep like `'^10[0-9]'` silently misses `110+` and overwrites/mis-groups a PRD):
+
+```bash
+ls ~/.claude/session-manager/scheduled-plans/prds/ | grep -oE '^[0-9]+' | sort -n | uniq | tail -5
+```
+
+The last line is the highest in use; the next free group is **max+1**. Use that for an independent/dependent PRD, or reuse a specific sibling's `NN` only when you deliberately want it in that parallel group. Verify your chosen filename doesn't already exist before writing.
+
+## Required frontmatter
+
+```yaml
+---
+title: <one-line human-readable title>
+cwd: <path to target project — where claude -p will run>
+estimateMinutes: <integer wall-clock estimate>
+---
+```
+
+`cwd` is critical. Without it the job runs in the scheduler's default cwd (session-manager). Always set it to the path of the project the work targets. **Write it as `~/Projects/<repo>`** — the parser expands `~` to `os.homedir()` at ingest, so the same PRD works on Linux and macOS. Avoid hardcoding an absolute home path (`/home/<you>/Projects/<repo>`); it breaks on any machine with a different home directory.
+
+## Required body sections (in this order)
+
+```markdown
+# Goal
+
+<2-4 sentences. What the executor will build and why it matters. NO "as a user I want to" framing. Concrete: name the function, the file, the user-visible change.>
+
+# Acceptance criteria
+
+- [ ] <each line is a verifiable check the executor can run after building>
+- [ ] <include explicit file paths, function names, expected behavior>
+- [ ] a bounded test command passes, e.g. `timeout 300 npm run typecheck` / `pytest -x` / `cargo check` (the run-before-done / never-end-on-red rule lives in standards.md → Execution discipline; the AC just has to name the command).
+
+# Implementation notes
+
+<file paths the executor will need to read first; the architectural pattern to follow; any non-obvious constraints. Be specific. Quote function signatures if it saves the executor a Read call.>
+
+# Out of scope
+
+<short bulleted list of what NOT to build, to prevent scope creep>
+```
+
+## Self-containment is load-bearing
+
+The executor (`claude -p`) starts with NO conversation context — only this PRD body and the project files. So:
+
+- Include exact file paths (`src/main/index.cjs:142`).
+- Quote function signatures or relevant code blocks if the executor would have to grep for them.
+- Name the libraries / patterns to use (e.g. "use the existing `validatePath` helper in `config.cjs`").
+- Don't reference "the conversation we just had" or "the design we discussed."
+- If the PRD depends on another PRD's output, say so in `# Implementation notes` AND give it a higher `NN` so it queues after.
+
+## Scope sizing — keep it SMALL (data-driven, 2026-06)
+
+Across 400+ real runs the median PRD finishes in **~7 minutes**, p90 **~21 min**, p99 **~66 min** — yet authored `estimateMinutes` ran **5–8× too high**. Oversized scoping is the root problem: it anchors PRDs too big and pushes them into the rare >60-min tail where ~100% of true hangs live (deploy poll-loops, unbounded e2e suites).
+
+- **Target ~15 minutes of wall-clock work per PRD. Hard ceiling ~30 min — if you project more, SPLIT** into sequential `NN` PRDs and document the dependency in each.
+- Set `estimateMinutes` realistically: **p50≈8, p90≈21**. Don't write 60/90 — it's almost always wrong and it hides real outliers.
+- Each execution costs ~$0.50–$2; the 5-hour token window is global. Smaller PRDs = smaller blast radius when a run is rate-limited, timed out, or killed.
+- **`rateLimited` exit-1 is NOT a failure** — it's the scheduler's designed auto-pause; the job auto-resumes at the next window reset. Don't add retry logic for it.
+
+## Execution discipline — append it, don't restate it
+
+The runtime rules (bound every command, verify-before-done, fail-loud, stay-in-AC,
+negative-assertion-exits-0) have a single home: the **Execution discipline** section of
+`~/.claude/skills/develop/standards.md`. Don't paraphrase them here — they drift.
+
+Long hangs — not bad code — are the dominant *real* failure (the watchdog only fires at 4
+hours, so an unbounded command burns hours), so these rules are load-bearing and MUST reach
+the headless executor in the PRD body:
+
+- If this PRD is being authored **via `/develop`**, that skill already appends `standards.md`
+  verbatim — nothing to do here.
+- If you are authoring a PRD **directly** (`/prd` alone), **append the Execution discipline
+  section from `standards.md` to the PRD body** (under an `## Execution discipline` heading)
+  before queueing. That is the only way the bounded-command / verify-before-done rules reach
+  `claude -p`.
+
+The one rule worth echoing inline because it shapes the AC: **wrap every test/build/deploy/poll
+command in a hard timeout** (`timeout 300 npm run typecheck`, `timeout 120 npx playwright test
+one.spec.ts` — shard e2e to one spec, never a full suite; `curl --max-time 15`; bound any
+`until/while`). Never queue a publish that polls an endpoint until a condition — the #1 hang
+offender (PRD_AUTHORING §1/§5).
+
+## Workflow
+
+1. Read existing PRDs in `~/.claude/session-manager/scheduled-plans/prds/` to pick `NN`.
+2. Write the file with the structure above.
+3. Confirm to the user:
+   - The filename (so they can see it queued).
+   - The chosen `parallelGroup` (NN) and the rationale (parallel-with-X / serial-after-Y).
+   - The chosen `cwd` (so they can correct if it's wrong).
+   - Estimated wall time + a token-cost ballpark.
+4. Tell the user the PRD will fire when the scheduler's policy says — they can click "Run now" in the SchedulePanel to execute immediately, or wait for `when-available` polling.
+
+## What NOT to do
+
+- Don't write the PRD to `data/prds/`, `docs/prds/`, the project's own folder, or anywhere outside the canonical path. The user has explicitly flagged this as a recurring problem.
+- Don't combine multiple unrelated features into one PRD. Each PRD is one focused, completable unit.
+- Don't add a parallelGroup field to the frontmatter — the scheduler reads the filename prefix.
+- Don't leave `cwd` unset hoping for the default. Be explicit.
+- Don't write the PRD body inline in the chat for review *before* writing the file. Write the file directly, then confirm. The user wants the PRD queued, not draft-reviewed in chat.