Files

9.1 KiB

/optimize Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Optimizer's /optimize ANALYSIS: <folder> optimises the detectors and the reading tools from one analysis; Diagnostic-App calls it once.

Architecture: /improve is moved to /optimize, derives its inputs from the analysis folder, keeps its detectors steps, then runs agents:tool-builder as a subagent and writes one summary. The tool-builder writes only in the session folder. Diagnostic-App's optimisation becomes a single claude -p turn in Optimizer.

Tech Stack: Claude Code skills and agents (Markdown), Python 3 (Diagnostic-App server and its check.py).

Spec: docs/superpowers/specs/2026-11-16-optimize-design.md

Global Constraints

  • English everywhere; every time UTC.
  • Commit by path, never git add -A; each repository on its current branch (Optimizer master, the others main); nothing pushed.
  • Commit messages end with an empty line then Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.
  • Optimizer is read-only on data/ and labeling/; the agents never run on an API key.
  • Detector fix commits stay improve: S<n>.

Review Focus

  • /optimize without inputs, or with an analysis folder lacking request.json: says what is missing, stops, touches neither detectors/ nor tools/ (Task 2, Step 4).
  • An analysis whose range carries no label (score.py exits with an error): the detectors part stops, the tools part still runs (Task 2 skill text, Step 4 review).
  • An analysis that ends at midnight: TO = the day after end, as Diagnostic-App does today (Task 2 skill text).
  • The tool-builder never writes in the analysis folder (Task 1).
  • Diagnostic-App with Optimizer lacking the tools link: a clear refusal (Task 3, Step 1).

Task 1: the tool-builder writes in its report's folder (agents)

Files:

  • Modify: ~/agents/agents/tool-builder.md (lines 3, 44-45, 65)

  • Modify: ~/agents/agents/upgrader.md:3,8, ~/agents/agents/validator.md:3,8, ~/agents/README.md:8-10

  • Step 1: In tool-builder.md, Check step 1: --out <the folder of your report>/work/tools/ instead of <analysis>/work/tools/; Check step 2: rerun the report's commands with their --out replaced by <the folder of your report>/work/; add "You write nothing in the analysis folder." to "What you touch"; report template "figures in /work/tools/". Description: launched by Optimizer's /optimize (Agent tool, agents:tool-builder).

  • Step 2: "improve workflow" → "optimize workflow" in upgrader.md, validator.md; README table: requests "that of the optimize skill", the tool-builder's caller "Optimizer (/optimize)".

  • Step 3: grep -n "work/tools\|improve workflow\|improve\ skill" ~/agents -rreturns only` lines.

  • Step 4: Commit in ~/agents: Optimize: the tool-builder writes in its report's folder; run by Optimizer's /optimize.

Task 2: the /optimize skill (Optimizer)

Files:

  • Move: .claude/skills/improve/SKILL.md → .claude/skills/optimize/SKILL.md (git mv)
  • Create: link tools -> ~/tools (ignored or untracked, like the others)
  • Modify: README.md, CLAUDE.md

Interfaces:

  • Produces: request /optimize ANALYSIS: <analysis folder>/. OUT: sessions/<analysis>_<YYYYMMDDTHHMMZ>/. Caller's context: …; optional overrides DETECTORS, TOOLS, DATA, LABELS, FAMILIES; output <OUT>/summary.md (first line # optimize: <station>, <FROM> → <TO>, lines **Result**: and **Tools changed**:), <OUT>/tools.md.

  • Step 1: Skill frontmatter name: optimize, description: the workflow that, from one analysis, improves the detectors (upgrader, validator) and the reading tools (tool-builder).

  • Step 2: Inputs section per the spec: ANALYSIS, OUT required; defaults DETECTORS: detectors/, TOOLS: tools/, DATA: data, LABELS: labeling/auto, FAMILIES: labeling/families.md; derived STATION, FROM, TO (day after end), labels file, reference, CONTEXT. Missing ANALYSIS/OUT, no request.json, DETECTORS or TOOLS not a git repository: say so, stop, change nothing. Remove the DATA+STATIONS mode and its commands.

  • Step 3: Steps: "Part 1, detectors" = the current steps (unchanged; a stop in part 1 — no label on the range, an agent missing — goes to part 2, not to the end); "Part 2, tools", always: Agent tool agents:tool-builder, request Analysis: <ANALYSIS>/. Tools: <TOOLS>/. Write <OUT>/tools.md., plus the caller's context; its output missing: note it. Summary: title # optimize: …, the detectors part as now, **Tools changed**: under **Result**:, section ## Reading tools (copied: "Tools changed", "What I decided" of <OUT>/tools.md), ## Tools renamed ## Scripts of the agents. Answer: add the **Tools changed** line.

  • Step 4: Run env -u ANTHROPIC_API_KEY claude -p "/optimize" --plugin-dir agents --model haiku, then the same with "/optimize ANALYSIS: labeling/auto/analyses/nothing/. OUT: /tmp/x/". Expected: both say what is missing and stop; git -C detectors status --short and git -C tools status --short empty.

  • Step 5: ln -s ~/tools tools; check git status does not show tools as a new file to commit (add it to .gitignore if the other links are there).

  • Step 6: README.md: scope "the detectors and the tools, from an analysis"; the steps; the tools link; the by-hand command /optimize ANALYSIS: labeling/auto/analyses/<analysis>/. OUT: sessions/<analysis>_<YYYYMMDDTHHMMZ>/. with --add-dir ~/tools; what a session leaves (tools.md, work/). CLAUDE.md: the same scope, link and check command.

  • Step 7: Commit in Optimizer by path: the moved skill, README.md, CLAUDE.md, .gitignore if changed, the spec and this plan: Optimize: /optimize, the detectors and the tools from one analysis (ex /improve).

Task 3: Diagnostic-App calls /optimize once

Files:

  • Modify: ~/Diagnostic-App/app/server/analysis.py (docstring 1-11, IMPROVE 29-33, optimize 262-268, optimize_thread 275-297)
  • Test: ~/Diagnostic-App/app/server/check.py (check_optimization, 135-166)
  • Modify: ~/Diagnostic-App/CLAUDE.md:5,8, README.md:6,25, app/README.md:24,41

Interfaces:

  • Consumes: Task 2's request.

  • Step 1: the failing check. In check_optimization: create skills/optimize/SKILL.md instead of improve; the links loop ("data", "labeling", "detectors", "tools") with a refusal asserted before tools exists; after the run assert len(launched) == 1; request.startswith("/optimize ANALYSIS: labeling/auto/analyses/NORDEND_a/. OUT: sessions/NORDEND_a_"), k["cwd"] == analysis.OPTIMIZER.resolve(), "--plugin-dir" in args; remove the launched[1] tool-builder assertions; keep the old <analysis>/tools.md summary assertion.

  • Step 2: cd ~/Diagnostic-App && .venv/bin/python app/server/check.py → FAIL in check_optimization.

  • Step 3: IMPROVE → OPTIMIZE = "/optimize ANALYSIS: labeling/auto/analyses/{name}/. OUT: sessions/{name}_{time}/. Caller's context: Diagnostic-app, through Optimizer; read-only on data/ and labeling/; commit only in detectors/ and tools/, on their current branch; do not commit OUT."; optimize() checks skills/optimize/SKILL.md and the tools link; optimize_thread one turn in OPTIMIZER.resolve() with --plugin-dir AGENTS.resolve(), --add-dir detectors (station.links() already adds tools), --allowedTools Read,Write,Edit,Bash,Agent; the request.json read and TO computation removed (Optimizer derives them); docstrings say /optimize.

  • Step 4: .venv/bin/python app/server/check.py → passes.

  • Step 5: Docs: "Optimize the detectors" launches /optimize in optimizer/ on the analysis (detectors committed in detectors/, tools in tools/); contract "the request of /optimize"; app/README.md the single launch; summary path.

  • Step 6: Commit in Diagnostic-App by path: Optimize: a single /optimize call in Optimizer, the detectors and the tools.

Task 4: wording in detectors and tools

Files: ~/detectors/CLAUDE.md:3,12, ~/detectors/README.md ("Improving them"), ~/tools/README.md ("Who changes it")

  • Step 1: improve skill → optimize skill (detectors); the tool-builder "run by Optimizer's /optimize, after each analysis optimised" (tools). History references (wf-improve, improve: S<n>) unchanged.
  • Step 2: Commit each repository by path: Optimize: the skill is /optimize.

Task 5: final check

  • grep -rn "/improve\|improve\ skill|skills/improve" ~/Optimizer --include=*.md -l | grep -v "archive/|sessions/|docs/superpowers"and the same on Diagnostic-App (outsidedocs/superpowers, node_modules`), agents, detectors, tools: nothing left.
  • Diagnostic-App check.py passes; the Task 2 haiku runs stop cleanly.
  • Left to the user: a real session through the app's button (it commits in detectors and tools).