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 -p to get a targeted fix
- Returns an
eval-fix candidate 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.
<example>
正确: 第一次生成 + 有 evaluator baseline failures
$ python3 scripts/propose.py --target /path/to/skill --source baseline-failures.json --state-root ./state
→ 候选 1: LLM-proposed SKILL.md fix targeting failed tasks (category=prompt, risk=low)
→ 候选 2-4: template candidates (docs, reference, guardrail)
→ stdout: /state/candidate_versions/run-001.json
</example>
<anti-example>
错误: 同一个 category 失败 3 次后还继续重试
→ 应该用 --trace 注入失败信息让 generator 自动切换到其他 category
</anti-example>
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
--source with failure traces
- improvement-evaluator: Baseline failures fed back as
--source to inform candidate generation
