optimize

name	optimize
description	Reads .design/telemetry/costs.jsonl + .design/agent-metrics.json, runs rule-based analysis, writes .design/OPTIMIZE-RECOMMENDATIONS.md. Pure advisory - no auto-apply. User reviews + decides.
argument-hint	[--refresh] [--min-spawns=N]
user-invocable	true
tools	Read, Bash, Grep, Write

{{command_prefix}}optimize - Optimization Advisor

Role

Read the telemetry ledger (.design/telemetry/costs.jsonl) and per-agent aggregate (.design/agent-metrics.json), apply a fixed set of rule-based heuristics, and emit recommendations to .design/OPTIMIZE-RECOMMENDATIONS.md. Never modify agent files, budget config, or cache state. Output is a markdown table of proposals the user reviews manually, mirroring Phase 11 {{command_prefix}}apply-reflections. Advisory only: never edits agents/*.md, .design/budget.json, .design/cache-manifest.json. Never makes model calls - every rule is deterministic. See ./reference/heuristics.md §"Optimization rules" for the full rule catalog.

Refresh Step

Before analysis, invoke the aggregator:

node --experimental-strip-types scripts/aggregate-agent-metrics.ts

Idempotent. If --refresh absent and .design/agent-metrics.json generated within 60s, skip.

Inputs

• .design/telemetry/costs.jsonl - append-only; tolerant of malformed lines.
• .design/agent-metrics.json - per-agent aggregate; source of truth for cache_hit_rate, lazy_skip_rate, total_cost_usd, total_spawns.
• agents/*.md - frontmatter cross-reference for tier override churn + typical-duration drift.
• .design/budget.json - tier_overrides table (optional).

Optional Arguments

• --refresh - force aggregator refresh even if metrics file is fresh.
• --min-spawns=N - only emit recommendations for agents with ≥ N spawns (default 5).

Rules

Rule-based analysis. Full thresholds + emission templates in ./reference/heuristics.md §"Optimization rules"; here, the short rule catalog:

• R1 - Low cache hit rate. IF total_spawns >= --min-spawns AND cache_hit_rate < 0.20 → propose batching + investigate shared-preamble ordering.
• R2 - Expensive + rarely lazy-skipped. IF total_cost_usd > 0.50 AND lazy_skip_rate < 0.10 → propose adding a lazy gate at agents/{agent}-gate.md (Plan 10.1-04 pattern).
• R3 - Tier override churn. IF measured tier differs from frontmatter default-tier for multiple rows → propose updating frontmatter or removing budget.json override.
• R4 - Typical duration drift. IF measured typical_duration_seconds differs from frontmatter by > 50% → propose frontmatter update. (v1 only computes wall-clock duration if both spawn + complete rows have matching correlation IDs; otherwise flag "insufficient data".)

Output Format

Write .design/OPTIMIZE-RECOMMENDATIONS.md:

# Optimization Recommendations

**Generated:** {ISO-8601 timestamp}
**Telemetry rows analyzed:** {N}
**Agents analyzed:** {M}
**Min spawns threshold:** {--min-spawns value}

> Advisory only. No changes have been applied. Review each proposal and apply manually via the suggested action.

## Proposals

| Rule | Agent | Current | Proposed | Rationale |
|------|-------|---------|----------|-----------|
| R1 | ... | ... | ... | ... |

## Summary

- R1 matches: {count}
- R2 matches: {count}
- R3 matches: {count}
- R4 matches: {count}

## OPTIMIZE COMPLETE

The ## OPTIMIZE COMPLETE marker is the completion sentinel.

No Auto-Apply

This skill never modifies agents/*.md, .design/budget.json, .design/cache-manifest.json, or any other configuration. Never auto-applies proposals. If the user wants to act, they do so manually. Discipline mirrors {{command_prefix}}apply-reflections from Phase 11.

Integration with Phase 11 Reflector

The Phase 11 reflector (agents/design-reflector.md) reads both costs.jsonl and agent-metrics.json on its own cadence. {{command_prefix}}optimize is user-facing; the reflector is automation-facing. Outputs land in different files (.design/OPTIMIZE-RECOMMENDATIONS.md vs .design/reflections/*.md) and never collide.

Non-Goals

• Does not make model calls (rule-based, deterministic).
• Does not modify config.
• Does not propose changes outside the four rules - future rules added by future phases.
• Does not learn from history - Phase 11 reflector territory.

Failure Modes

• Missing .design/telemetry/costs.jsonl → emit No telemetry data yet — run {{command_prefix}}* commands to accumulate data, then retry. + ## OPTIMIZE COMPLETE.
• Missing .design/agent-metrics.json after refresh → emit Aggregator failed — check node --experimental-strip-types scripts/aggregate-agent-metrics.ts output manually.
• Zero rules matched → write No recommendations — all agents within healthy thresholds. + ## OPTIMIZE COMPLETE.