Improvement Generator
Produces ranked improvement candidates from target analysis, feedback signals, and failure traces.
When to Use
- 为目标 skill 生成结构化改进候选
- 把上次失败的 trace 注入下一轮（GEPA trace-aware）
- 根据记忆模式避开已经失败过 >=3 次的策略
When NOT to Use
- 给候选打分 → use
improvement-discriminator - 评估 skill 结构 → use
improvement-learner - 全流程 → use
improvement-orchestrator
CLI
python3 scripts/propose.py \
--target /path/to/skill \ # REQUIRED: skill directory or single file
--state-root /path/to/state \ # default: lib/state_machine.DEFAULT_STATE_ROOT
--source memory.json \ # repeatable: feedback/memory/baseline-failures sources
--max-candidates 4 \ # default 4: max candidates to generate
--trace failure_trace.json \ # inject prior failure trace for retry prioritization
--run-id custom-run-id \ # default: auto-generated from target
--output candidates.json \ # default: {state-root}/candidate_versions/{run-id}.json
--lane generic-skill # default: generic-skill
| Param | Default | When to change |
|---|---|---|
--max-candidates |
4 | Lower to 2 for fast iteration; raise for diverse exploration |
--trace |
None | Pass when retrying after gate revert — deprioritizes failed category |
--source |
[] | Add feedback.jsonl, memory files, or evaluator baseline-failures.json |
--run-id |
auto | Set explicitly when integrating with external tracking |
6 Candidate Categories
| Category | Risk | Executor Support | Description |
|---|---|---|---|
docs |
low | Yes (append_markdown_section) |
Append operator notes/limitations to Markdown docs |
reference |
low | Yes (append_markdown_section) |
Add control-plane-friendly notes to reference files |
guardrail |
low | Yes (append_markdown_section) |
Add conservative auto-promote rules to guardrail docs |
prompt |
medium | No | SKILL.md prompt restructure (requires manual review) |
workflow |
medium | No | Workflow adapter/orchestration hook changes |
tests |
medium | No | Smoke-check/validation test cases |
Trace-Aware Generation
When --trace is provided, adjust_candidates_from_trace() deprioritizes the category that failed in the prior run and boosts alternatives:
failure_trace.json: {"candidate_id": "cand-01-docs", "reason": "gate rejected"}
→ docs candidates moved to end, reference/guardrail candidates boosted to front
Evaluator-Driven Fix (_find_evaluator_failures + _llm_propose_skill_fix)
When --source includes a baseline-failures.json (type=evaluator_baseline_failures), the generator:
- Reads failed task details (task_id, score, error)
- Sends current SKILL.md + failures to
claude -pto get a targeted fix - Returns an
eval-fixcandidate as highest priority (risk_level=low, executor_support=True)
Correction Hotspots (_find_correction_hotspots)
Scans feedback.jsonl sources for user correction events (outcome=correction|partial). Returns dimension_hint → count mapping used to prioritize candidates that address the most-corrected dimensions.
Output Artifact
{"schema_version": "1.0", "run_id": "...", "stage": "proposed",
"candidates": [{"id": "cand-01-docs", "category": "docs", "risk_level": "low",
"execution_plan": {"action": "append_markdown_section", "section_heading": "## Operator Notes",
"content_lines": ["..."]}, ...}],
"failure_trace_used": false, "truth_anchor": "/state/candidate_versions/run-001.json"}
Related Skills
- improvement-discriminator: Scores the candidates this skill produces → called by orchestrator as stage 2
- improvement-orchestrator: Calls generator as stage 1, passes
--sourcewith failure traces - improvement-evaluator: Baseline failures fed back as
--sourceto inform candidate generation