--- name: skill-optimisation-review type: skill description: Periodic Pulse review that keeps Aled's tooling conventions current, his operating shape sound, and his scheduled layer efficiently run, raising proposals into the os.Claude Backlog. Three passes — a docs-driven tooling pass (read each tool's current documentation and changelog, verify our conventions still match, propose convention fixes and adoption of under-used features), a workflow pass (does the operating shape match the skill-vs-task test), and a model-and-schedule pass (is each task/routine on the right model for token efficiency, and scheduled at the right time and in the right order given busy windows, sequencing/loops, and the operator's day). Read-only to canon; canon findings go to the Pulse friction queue, tooling/repo findings and schedule/model config changes to the Backlog. Never edits a SKILL.md, routine, schedule, or other canon directly. --- # skill-optimisation-review A periodic Pulse review with three passes — a **tooling pass**, a **workflow pass**, and a **model-and-schedule pass** — that surfaces improvement proposals into the os.Claude Backlog. It is proactive: rather than waiting for friction to be flagged (that is skill-ops-retro's job), it goes and reads the documentation of the tools we depend on, checks the operating shape, and reviews how efficiently the scheduled layer runs. It never edits canon or a schedule. Findings are routed by nature: a **canon or convention change** (a `convention-*` edit, a skill/agent/operating-shape change) is filed as a `FRICTION:` note into the **Pulse friction queue** (`agent:PUL-5E`), so the batch drain consolidates it with other intake and the operator saves it — never a Forge-routed apply ticket; a **tooling, repo, or infra change** (a GitHub setting, a Vercel config, code work) is filed as an `OPS:`/`FIX:` Backlog ticket on `agent:R3-LAY` for the normal Relay loop; a **schedule or model config change** (a cron slot, a cadence, a model choice) is filed as an `OPS:` Backlog ticket carrying the `human` executor and assigned to Aled, because applying it is an operator config edit, not Forge repo work. **Enumerating issues at scale:** `list_issues` always returns full description bodies. Filter by `label`+`state`+`project`/`team` on every call; prefer per-label/per-state probes over broad queries; delegate to a subagent for genuinely large sets. See convention-linear *Enumerating issues at scale*. --- ## Three passes, one skill ### Pass 1 — Tooling (docs-driven) This pass is **documentation-led and proactive**. For each tool we depend on, read its current official documentation and changelog (web access required — see Setup), then run three checks. Tools in scope: Claude / Cowork, Linear, GitHub, Vercel, Sanity, Shopify, Figma. **(a) Verify our conventions against the source.** For each tool, compare its current documented behaviour and model against our `convention-*` files and our stated understanding of how the tools relate to each other. Flag every drift in either direction: a convention that describes behaviour the tool no longer has (or has changed), a tool concept our conventions get wrong, or a relationship between tools we have misunderstood. Cite the specific doc page for each finding. **(b) Propose convention improvements.** Where the docs reveal a cleaner, safer, or more reliable way to do something we have conventionalised, propose the convention change — the specific edit, which `convention-*` file it touches, and the doc citation that motivates it. **(c) Propose feature adoption, tied to goals.** Surface capabilities we are under-using and connect each to a delivery or venture goal — not "consider using X" but "use X to achieve Y." Worked example: how should we use Linear **initiatives and cycles** to drive delivery against goals (initiatives as outcomes feeding skill-strategy-cascade and skill-plan; cycles as the delivery rhythm)? Other candidates as the docs warrant: GitHub merge queues and rulesets, Vercel preview environments, Sanity releases and scheduled publishing, Figma variables. Each becomes a concrete proposal. **Freshness:** this pass depends on reading current docs. If a run has no web access, do what it can from the connected tools and the conventions, and flag in the report that the currency check was limited — do not present a stale read as current. ### Pass 2 — Workflow Audit whether the operating shape is correctly structured, using the skill-or-task decision test from the `core-operating-model` skill. For each behavioural element (skills, tasks, routines), ask: - Does it run automatically on a schedule or trigger? Then it is a deployment of a skill — a Task (Cowork surface) or a Routine (Claude Code surface). - Does it define repeatable behaviour? Then it is a Skill. - Is it a named, accountable role? Then it is an Agent (functional) or an Operator (vertical). Also consider: is any skill getting too broad (candidate to split)? Is any pair near-identical (candidate to fold)? Would a new connector or capability unlock meaningful leverage? ### Pass 3 — Model and schedule (run efficiency) Review *how* the scheduled layer runs — the model each task/routine uses and when it fires — against token efficiency and the operator's day. Read the live scheduled-tasks list and Cloud Routines (their cron slots, cadences, and any model setting) alongside the canon `task-*`/`routine-*` set. **(a) Right model for the job.** For each task/routine, is its model matched to the work? Propose a cheaper, faster model for mechanical connector sweeps and status posts; a stronger model for reasoning-heavy passes (a drain, a spike, a review). Flag over-powered runs (cost with no benefit) and under-powered ones (a weak model on work that needs reasoning). Tie each proposal to token-usage / cost evidence where available. **(b) Right time and order.** For each schedule, is the slot and cadence right against three constraints together: - **Busy / cost windows** — avoid platform-peak times where they raise cost or latency; prefer cheap off-peak slots where latency allows. - **Sequencing and loops** — a producer must run before its consumer, and loop members in order: e.g. triage before the morning brief; pipeline-qualify before pipeline-graduation; plan before the weekly operator loops that read it. - **The operator's day** — deliverables land *before* the moment Aled needs them, not during it (the standing anchor: everything he reviews at the 9am stand-up is ready by then, so triage/plan/report finish beforehand). Propose the specific cron change and the reason. These are config edits the operator applies (`update_scheduled_task` / the routine config), so route them as schedule/model `OPS:` tickets (below), never auto-applied. --- ## Behaviour 1. **Tooling pass.** For each tool in scope, read its current docs and changelog, then run checks (a)–(c). Gather supporting evidence from connector data and visible configuration. Produce findings with doc citations. 2. **Workflow pass.** Read the skill roster in `CLAUDE.md` and the skill files. Apply the decision test from `core-operating-model`. Identify structural misfits. 3. **Model-and-schedule pass.** Read the live scheduled-tasks list and Cloud Routines against the canon task/routine set. Run checks (a)–(b). Produce model and cron proposals with their rationale and any token/cost evidence. 4. **Dedupe.** Before filing, search the os.Claude Backlog for an existing FRICTION:/OPS:/FIX: ticket covering the same opportunity. If found, add a dated comment rather than open a duplicate. 5. **File proposals, routed by nature.** One ticket per distinct opportunity, standard shape (per convention-linear): - **Canon / convention findings → the Pulse friction queue.** Title prefix `FRICTION:`; labels `type:task` + `work:configuration` + **`agent:PUL-5E`**; State Backlog; unassigned. Body: the observation plus a pointer to the candidate target artefact and the motivating citation — not a prescribed fix. The batch drain consolidates it and surfaces it for the operator to save. - **Tooling / repo / infra findings → the delivery loop.** Title prefix `OPS:` / `FIX:`; labels `type:task` + `work:configuration` + **`agent:R3-LAY`**; sections Objective, Why this matters, Proposed change (the specific edit and exactly which tool/setting/file it touches, with the doc citation), Notes for Aled, On completion; State Backlog; Assignee Aled only where a genuine decision is needed. - **Schedule / model config changes → the operator.** Title prefix `OPS:`; labels `type:task` + `work:configuration` + **`human`**; State Backlog; **assigned to Aled**. Body: the current slot/model, the proposed slot/model, and the efficiency/sequencing/day reason. These apply via `update_scheduled_task` or the routine config — an operator edit, not Forge work. 6. **Report.** Short summary: tickets filed (ID, title), duplicates merged, currency check coverage (which tools' docs were read), model/schedule proposals raised, anything skipped. No preamble. --- ## Guardrails - Propose, never apply. No edits to any SKILL.md, routine, convention, schedule, or other canon — the output is tickets: canon findings as Pulse `FRICTION:` intake, tooling/repo findings as delivery tickets, schedule/model changes as operator `OPS:` tickets. Canon is authored Claude-side and saved by the operator; the repo catches up via ops-sync; schedules are re-timed by the operator. - One opportunity per ticket. Don't bundle unrelated findings; don't split one finding across tickets. - Calibrate to evidence. A single observation is Low-priority; count instances and impact before escalating. Cite the doc for every tooling claim, and token/cost evidence for a model claim — no "I think the tool changed" and no "this model feels cheaper." - No ticket for nothing. A clean run files nothing. - Never files into Pipeline. Scope: the ops, tooling, and scheduled-layer only. --- ## Setup - Owned by **Pulse (PUL-5E)**. Cadence monthly — docs do not change weekly — or on demand. - Connectors: Linear + GitHub, the scheduled-tasks list, plus **web access** for the docs-driven tooling pass. - Deployed under the **wrapper model** (decision 2026-06-25) via a thin **loader config** — `task-optimisation-review` reads this skill: `Read .claude/skills/skill-optimisation-review/SKILL.md and follow it verbatim`. This SKILL.md is the canon and the single source of truth; the loader holds no instructions of its own, so every run tracks current canon. Behaviour changes are made here, never in the task config — matching how `skill-ops-sync` and `skill-task-health` describe their deployment. On finish, run skill-ops-retro capture on this run's friction: file a FRICTION note to the Pulse queue for the drain pass to assess.