odyssey-improve

States: S_INTAKE -> S_SURVEY -> S_AUDIT -> S_DIAGNOSE -> S_FIX -> S_VERIFY -> S_GENERALIZE -> S_DISCOVER -> S_RECORD

• S_FIX/S_VERIFY skip when --skip-fix
• S_GENERALIZE/S_DISCOVER skip when --skip-generalize

Cross-phase loops:

• S_DIAGNOSE -> S_DIAGNOSE (hypothesis retry, max 3)
• S_VERIFY -> S_FIX (rework on failed verification)
• S_DISCOVER -> S_DIAGNOSE (new critical issue found, cross_phase_loops++)
• S_DISCOVER -> S_FIX (same-pattern fix with template)
• S_DISCOVER -> S_RECORD : triage complete AND remaining_actionable == 0
• S_DISCOVER -> S_RECORD : loops >= max_loops → MUST log each unfixed item with specific reason (blanket "pre-existing" is forbidden)

S_INTAKE

1. Parse target + flags -> resolve file list
2. Generate slug, create SESSION_DIR
3. Search prior knowledge: maestro search "<keywords>" + Glob prior sessions + ARCHITECTURE.md + spec load (coding, debug)
4. Derive phase_goals[] from flags (apply skip_when)
5. Write session.json + understanding.md §1
6. Display Goal Prompt (appendix), continue without blocking

Resume (-c): Glob latest session -> read session.json -> restore current_state -> jump.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_INTAKE — 目标解析"

S_SURVEY

spawn_agents_on_csv (Wave 1):

Write tasks.csv with Wave 1 rows:

"survey-deps","Dependency Audit","Analyze dependencies for {target_files}: package versions, known CVEs, unused deps, circular imports, dep depth. Return [{dep,version,issue_type,severity,detail}].","survey","","","1","pending","","",""
"survey-complexity","Complexity Scan","Measure complexity for {target_files}: cyclomatic complexity, function length, nesting depth, file size, export count. Return [{file,metric,value,threshold,status}].","survey","","","1","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:2, max_runtime_seconds:300, output_csv_path:"wave-1-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })

Merge -> evidence.ndjson (phase: "survey"). Extract baseline_metrics from survey results. Update §2. Mark G1 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_SURVEY — 调查"

S_AUDIT

spawn_agents_on_csv (Wave 2) — 6 agents (one per dimension):

Append Wave 2 rows to tasks.csv:

"audit-perf","Performance","Hot paths, N+1 queries, memory allocation, cache strategy, bundle analysis, lazy loading for {target_files}","audit","performance","","2","pending","","",""
"audit-security","Security","OWASP Top 10: injection, broken auth, data exposure, XXE, access control, misconfig, XSS, deserialization, deps, logging for {target_files}","audit","security","","2","pending","","",""
"audit-arch","Architecture","Layer boundaries, circular deps, coupling metrics, interface contracts, SRP compliance, dependency direction for {target_files}","audit","architecture","","2","pending","","",""
"audit-reliability","Reliability","Error handling completeness, retry logic, timeout config, circuit breakers, graceful degradation, resource cleanup for {target_files}","audit","reliability","","2","pending","","",""
"audit-observability","Observability","Logging coverage, structured logs, metrics emission, trace propagation, error reporting, health endpoints for {target_files}","audit","observability","","2","pending","","",""
"audit-maintain","Maintainability","Dead code, complex conditionals, test coverage gaps, magic numbers, naming clarity, doc debt for {target_files}","audit","maintainability","","2","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:6, max_runtime_seconds:600, output_csv_path:"wave-2-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })

Merge -> evidence.ndjson (phase: "audit"). Write audit_result with dimensions audited, finding count, severity distribution. Update §3. Mark G2 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_AUDIT — 审查"

S_DIAGNOSE

Root cause analysis for top audit findings (severity >= high).

1. Rank findings from audit, group by root cause pattern
2. CLI deep analysis for top finding clusters:

maestro delegate "PURPOSE: Root cause analysis for codebase quality issues in {target}
TASK: Trace origin of each finding | Identify shared root causes | Map dependency chains | Assess blast radius
MODE: analysis
CONTEXT: @{target_files} | Audit findings: {top_findings_json}
EXPECTED: JSON [{finding_ids, root_cause, origin_file, origin_line, blast_radius, fix_approach, confidence}]
CONSTRAINTS: Trace to origin, not just symptoms | Group related findings
" --role analyze --mode analysis

Execute with run_in_background: true, then wait for callback (do NOT halt the Odyssey flow).

3. Hypothesis testing: for each root cause — design verification -> execute -> evidence (phase: "diagnose")
4. Decision journal: ambiguity -> evidence (phase: "decision"); Normal: request_user_input | -y: defer
5. Confirmed diagnoses -> session.json.diagnoses[]: [{id, finding_ids, root_cause, evidence_refs, confidence, fix_approach}]

Escalation (3-strike): Hypothesis fails -> retry with broader scope via maestro delegate --role explore. After 3 retries: Normal -> request_user_input | -y -> mark INCONCLUSIVE, proceed.

Update §4. Mark G3 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_DIAGNOSE — 诊断"

S_FIX

Skip if --skip-fix.

1. Present diagnoses + proposed fixes, prioritized by blast radius. Normal: request_user_input to confirm. -y: auto proceed.
2. Implement fixes in priority order (highest blast radius first)
3. Record each fix in evidence (phase: "fix" + "decision")
4. Update §5

📌 Auto-commit: git add -A && git commit -m "odyssey-improve({slug}): S_FIX — 修复"

S_VERIFY

Skip if --skip-fix.

1. Tests: auto-detect framework, run covering tests on modified files
2. CLI fix review:

maestro delegate "PURPOSE: Verify improvement fixes for: {target}
TASK: Check correctness | Assess regression risk | Verify no new issues introduced | Compare metrics
MODE: analysis
CONTEXT: @{modified_files} | Diagnoses: {summary} | Diff: {git_diff} | Baseline: {baseline_metrics}
EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regression_risk, metrics_comparison}
CONSTRAINTS: Focus on correctness and measurable improvement
" --role review --mode analysis

Execute with run_in_background: true, then wait for callback (do NOT halt the Odyssey flow).

3. Metrics comparison: measure post-fix metrics, compare with baseline_metrics
4. needs_rework -> S_FIX (loop). confirmed -> mark G4 done, advance
5. Update §5 with before/after metrics

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_VERIFY — 验证"

S_GENERALIZE

Skip if --skip-generalize. Extract patterns from confirmed diagnoses, scan for siblings.

Step 1 — Multi-layer pattern extraction:

Write session.json.patterns[]: [{id, source_diagnosis, layer, signature, description, risk, fix_template}]

Step 2 — 4-agent scan (spawn_agents_on_csv, Wave 3):

Append Wave 3 rows to tasks.csv:

"gen-syntax","Syntax Grep","Grep syntax-layer signatures '${signatures}' across project. Return [{file,line,context,risk_level,layer:'syntax',confidence}].","generalization","syntax","","3","pending","","",""
"gen-semantic","Semantic Scan","Check related modules for anti-pattern: ${description}. Return [{file,line,context,risk_level,layer:'semantic',confidence}].","generalization","semantic","","3","pending","","",""
"gen-structural","Structural Match","Find structurally similar files to ${diagnosed_files}, check for same anti-pattern. Return [{file,line,description,risk,layer:'structural',confidence}].","generalization","structural","","3","pending","","",""
"gen-historical","Historical Grep","Run git log -S '${signature}' --oneline. Return [{sha,file,date,type:'introduced|fixed',context}].","generalization","historical","","3","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:4, max_runtime_seconds:300, output_csv_path:"wave-3-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })

Step 3 — Cross-layer dedup: same file:line multi-layer -> boost confidence | single-layer -> needs_review | historical fixed -> regression_risk

Step 4 — Iterative deepening: module >= 3 hits -> targeted deep scan (max 1 round).

Step 5 — Quality Gate (self-iteration).

Step 6: Write generalization_stats: {patterns_extracted, total_hits, cross_layer_confirmed, regression_risks, by_layer, deepening_triggered}. Update §6. Mark G5 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_GENERALIZE — 泛化"

S_DISCOVER

Skip if no generalization hits.

1. Triage each hit: read +-10 lines -> classify safe / risk / bug / issue
2. Route:
   • bug/issue + directly fixable → fix immediately → back to S_FIX
   • bug/issue + requires cross-module/architectural decision → create issue (with fix suggestion + impact analysis)
   • risk → evaluate if guard/validation can mitigate directly; if yes, fix it
   • safe → mark skip See appendix for -y behavior. Append evidence (phase: "discovery" + "decision")
3. Cross-phase loop:
   • Discovery finds new critical issue → S_DIAGNOSE (cross_phase_loops++)
   • Same-pattern with fix template → S_FIX (!skip_fix)
   • S_DISCOVER → S_RECORD: triage complete AND remaining_actionable == 0
   • S_DISCOVER → S_RECORD: loops >= max_loops → MUST log each unfixed item with specific reason (blanket "pre-existing" is forbidden)
4. Update §7. Mark G6 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_DISCOVER — 发现"

S_RECORD

1. Finalize §8: before/after metrics comparison table
2. Write §9: structured by Knowledge Persistence table (temporary)
3. Mark G7 done. Pending decisions: Normal -> request_user_input. -y -> skip, show deferred count
4. Goal audit: all confirmed -> phase_goals_all_done = true. Any false: Normal -> request_user_input (回退/跳过/接受). -y -> auto accept
5. Completion: current_state = "COMPLETED", emit summary:

--- IMPROVE ODYSSEY COMPLETE ---
Target:      {target}
Dimensions:  {audited_list}
Baseline:    {baseline_summary}
Audit:       {C}C {H}H {M}M {L}L across {dim_count} dimensions
Diagnoses:   {N} root causes ({confirmed} confirmed, {inconclusive} inconclusive)
Fix:         {F} applied, {S} skipped | Before: {baseline} -> After: {post_fix}
Patterns:    {N} extracted ({by_layer} distribution)
Scan:        {total} hits ({cross_layer} cross-layer confirmed)
Issues:      {N} created
Decisions:   {resolved}/{pending}/{deferred}
Self-iter:   {R} quality gate rounds across {P} stages
Goals:       {done}/{total} ({skipped} skipped)
---

Next steps: $manage-issue list --source improve-odyssey, $learn-decompose <module>, $quality-review, $learn-second-opinion <understanding.md>, $learn-investigate "<question>"

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-improve({slug}): S_RECORD — 总结"

Improve Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：

/goal 穷尽迭代：直到所有 findings 均已处理（fix/issue/decision）
且 phase_goals_all_done=true 才停。修复按 severity 逐轮迭代，每轮修复后 re-verify。
Baseline metrics 必须在修复前采集，修复后必须与 baseline 对比。
不允许"只报告不处理"。遇到 phase=decision 的 pending 必须 request_user_input。