| name | improve-decompose-sweep |
| description | Calibrate the decompose-sweep workflow after a completed run. Reads telemetry, identifies patterns (defer reasons, overshoot rate, test failures), proposes threshold and heuristic changes backed by data, patches the workflow YAML, and reports a summary. |
| allowed-tools | Bash, Read, Edit, Write, Glob, Grep |
| skills | ["dancing-bear-rules"] |
Improve Decompose Sweep
Post-run calibration for workflows/code/decompose-sweep.yaml. Reads run telemetry, identifies patterns, proposes and applies data-backed changes, then validates and logs the calibration.
When to Use
- After a
decompose-sweep workflow run completes
- User says "improve decompose", "calibrate decompose", or "decompose retrospective"
- Recurring calibration pass (monthly, or after 3+ runs)
Step 1: Collect Telemetry
Run telemetry files land in the workflow's workspace_dir. The workflow engine resolves {work_dir} to <cwd>/out/ (see workflow/cli.py), so sweep runs write to:
out/decompose-sweep/run-metrics.json
out/decompose-sweep/run-<timestamp>/run-metrics.json
find out/decompose-sweep -name "run-metrics.json" | sort
find out/decompose-sweep -name "run-metrics.json" | sort | tail -1 | xargs cat
Fallback — if no telemetry files exist (e.g., run was aborted, workspace cleaned), parse agent summary messages from conversation context and note the source in the calibration log entry.
Step 2: Analyze Patterns
From the collected metrics, compute:
Defer rate by reason
How often each defer heuristic triggered. High rates indicate a threshold is too aggressive.
| Reason | Count | % of candidates |
|---|
| file_not_large_enough | N | N% |
| has_open_pr | N | N% |
| recently_modified | N | N% |
| imports_too_tangled | N | N% |
Overshoot rate
Files that were split but output modules still exceed the target line count. Indicates the plan-splits stage is over-estimating how cleanly a file divides.
Test failure domains
Which domains produced failing tests post-split. Cluster by root cause:
- Import errors (re-export facade incomplete)
- Missing shared fixtures (not extracted to shared submodule)
- Circular dependencies introduced
Strategy accuracy
| Strategy | Used | Met target | Avg lines saved | Avg output max |
|---|
| extract-submodules | N | N% | N | N |
| extract-package | N | N% | N | N |
| split-tests-by-class | N | N% | N | N |
| extract-helpers | N | N% | N | N |
Step 3: Calibrate
Propose changes with data citations. Each proposal must name the metric that motivates it.
Threshold adjustments — only lower if the defer rate for file_not_large_enough exceeds 40% across 3+ runs. Only raise if > 20% of splits produce files that still exceed target.
Defer heuristic changes — add a new heuristic only if the same pattern appears in 2+ runs. Remove one only if it has a 0% trigger rate across 3+ runs.
Strategy selection improvements — adjust strategy criteria if a strategy's "met target" rate is below 60% on 3+ uses.
New verification steps — propose only if the same root-cause test failure category appears in 2+ runs.
Step 4: Patch the Workflow
Apply approved calibration changes directly to workflows/code/decompose-sweep.yaml:
- Threshold changes: edit
trigger.params (line-count thresholds passed to the sweep)
- Defer heuristic changes: edit the
plan-splits stage description where defer criteria are listed
- Strategy criteria changes: edit the
plan-splits stage description where strategy selection logic is described
- New verification steps: edit the
verify-tests stage description
After each edit, lint and compile:
./bin/workflow lint workflows/code/decompose-sweep.yaml
./bin/workflow compile workflows/code/decompose-sweep.yaml
If lint fails, fix before proceeding — do not log a calibration entry for a broken workflow.
Step 5: Update Calibration Log
Append a one-line-per-change entry to the top comment block of workflows/code/decompose-sweep.yaml:
Bump version in the workflow metadata field (e.g., "1.0" → "1.1").
Step 6: Report
## Decompose Sweep Calibration — <date>
### Run Stats (last <N> runs)
- Files scanned: N
- Deferred: N (N%)
- Split: N
- Overshoot: N (N%)
- Test failures: N
### Changes Applied
- <change 1> — motivated by <metric>
- <change 2> — motivated by <metric>
### Proposed but Deferred (need more data)
- <change> — only N run(s), need 3
### Prediction for Next Run
Expected defer rate: ~N% | Expected overshoot rate: ~N%
Anti-Patterns to Avoid
- Lower thresholds without data: need 3+ runs before reducing any threshold
- Change strategy criteria on one failure: wait for 2+ occurrences of the same root cause
- Touch passing parts of the workflow: only edit what the data implicates
- Skip lint after patching: always validate — a broken workflow is worse than the status quo
- Log entries without metric citations: every calibration line must name the data that motivated it
