---
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.
license: CC BY-NC-SA 4.0
---

# 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?

**(d) Recompute-versus-compose — the set-level redundancy check the pairwise fold test cannot see.** The fold question above is **pairwise**: it catches two artefacts that do the same thing. It is blind to **N artefacts that each do a legitimately different thing while all re-deriving the same underlying state** — five board sweeps with five genuinely different queries (coordinate's comment sweep, fleet-dispatch's label reads, the delivery loop's lock check, the daily report's health queries, the attention sweep's cycle read), no two near-identical, every one passing the fold test, and every one re-deriving which projects are live, what is in flight and in what state, and what is blocked by what. So for each consumer artefact, ask instead: **is the state it derives already produced by another artefact's output?** Where it is, propose composing from that output rather than re-deriving it. Where a state is needed by two or more consumers and produced by none, propose which single artefact should produce it, and cite the consumers. Two caveats travel with any composition this check proposes, both already learned the hard way:

- **Outputs are prose, not data, so composition is lossy and degrades silently when a producer's format drifts.** Any proposed composition inherits `task-cycle-planning`'s *Composition gate* — do not lean on another artefact's output until that output has a track record, or two untested things fail together with no way to tell which broke (APP-501 / APP-630).
- **A producer that did not run must not read as a quiet day.** A consumer that finds its input missing, empty or stale falls back to its own read and says so, never treats absence as "nothing to report" — the same class as the dead-cycle trap where a stale object read exactly like a fresh one (APP-761).

The check proposes composing *outputs*, never consolidating the *reads* into one producer: each sweep carries hard-won trap handling and fails alone today, and a single producer would make the whole layer depend on one artefact not failing. The signature that this check was missing: eight closed `FRICTION:` tickets each taught one sweep to read more narrowly, and not one asked whether the read needed to happen at all (APP-258/288/327/493/530/552/587/622). (APP-816.)

### 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 — and no task left on a silently-inherited 'default'.** 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.

A task or routine whose model setting is **'default'** is itself a finding, independent of which model 'default' currently resolves to: 'default' inherits whatever the app resolves at run time, so a change to the app's default silently changes what the task runs on with no config change on our side — the same class of silent drift as a fat config drifting from canon, but on the model axis. Treat every 'default'-riding task/routine as a gap to close: propose an explicit pinned model for it (cheap for mechanical sweeps, stronger for reasoning-heavy passes) as part of this pass's regular output, alongside any right-model-for-the-job proposals. Where the review has not yet covered the full task/routine list, note which are still riding 'default' so the next run picks up where this one left off. (Prompted by APP-477, 2026-07-09 — `task-triage` was found resolving 'default' to `claude-fable-5` with nothing in the task config having chosen that model.)

**A new default-model generation is a standing re-check trigger for this pass.** When a new default model ships — e.g. Claude Opus 5 (1M-token context, thinking-by-default, fast mode) landing as the new default Opus — re-evaluate every task/routine model pin at once: which legs move to the new generation, which hold on the prior one, which drop to a cheaper tier now the price-and-capability frontier has moved. A new default also silently changes what every 'default'-riding task resolves to (the (a) gap above), so a generation change is exactly when that sweep pays off most. This is a coordinated pin review, not a blanket switch — decide per leg against cost and the work's reasoning depth, and cite the changelog for the generation. It is the scheduled-layer face of the same trigger convention-agent-runtime carries for the runtime substrate's model-tier-by-leg calculus. (Prompted by APP-863 — Claude Opus 5 shipping as the new default Opus.)

**(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. **Ordering alone is not sequencing when a human approval gate sits between producer and consumer.** Where a producer only *proposes* and a human must approve before the consumer may act — the Cycle-Planning-proposes / Aide-books pairing is the worked case — no fixed cron offset makes the approval reliably present by the consumer's slot, so widening the gap cannot fix it and the consumer must be **state-aware, not time-aware**: it tests that what it is about to consume has been approved *since* the latest proposal (freshness against the proposal), not merely that it exists, and reports-and-stops on a stale-but-present input exactly as it would on a missing one. So in this pass, for any producer-consumer pair separated by a human gate, check that the consumer's cycle-freshness / approval-signal handling is current — that it tests approval-since-proposal rather than mere existence — and flag it where it does not. (Prompted by APP-820. The aide/cycle-freshness canon itself — task-aide-loop, skill-attention-sweep, assistant-aide, task-cycle-planning — is authored by a sibling unit this run; this pass authors only its own check.)
- **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.

**(c) Right surface — Cowork vs Cloud Routine.** For each live schedule, check its surface against the placement rule in `core-operating-model` Layer 2: a job needing GitHub / repo network (the delivery loop, anything touching a repo) belongs on a **Cloud Routine**; a connector-only job (Linear / Gmail / Calendar, no repo network) belongs on a **Cowork task**. A GitHub-needing job on Cowork silently cannot run its core legs (APP-805), so a wrong-surface placement is a finding, the same class as the 'default'-riding model gap in (a) or a config drifted from its loader form. Route it as a schedule/model `OPS:` ticket to the operator (the surface is a config choice, not Forge work). This is a checkable axis only because the rule is now written down — do not re-derive it here.

---

## 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), including the explicit 'default'-riding sweep in (a). 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 (name 'default' explicitly where that is the current setting, not a resolved model name), 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 (including any 'default'-riding tasks found and their proposed pin), 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: **search the Pulse queue first and add the evidence to a same-root note if one exists, otherwise file a new FRICTION note** for the drain pass to assess, in capture step 3's literal shape — team Apps, project os.Claude, `FRICTION:` title, labels `task` + `work:configuration` + `PUL-5E`, Backlog, unassigned — filing the friction, never the run report.
