odyssey-debug

Stage 1: Intake (S_INTAKE)

1. Parse arguments: issue description, flags
2. Generate slug, create SESSION_DIR
3. Search: maestro search "<keywords>" + Glob prior sessions + ARCHITECTURE.md + Grep keywords
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-debug({slug}): S_INTAKE — 目标解析"

Stage 2: Archaeology (S_ARCHAEOLOGY)

Step 1 — Git archaeology (spawn_agents_on_csv, Wave 1):

Write tasks.csv with Wave 1 rows:

id,title,description,task_type,deps,wave,status,findings,evidence,error
"arch-timeline","Git Timeline","Run git log --oneline -20 -- {files}. Return [{sha,date,author,message,files_changed}] as JSON.","archaeology","","1","pending","","",""
"arch-blame","Git Blame","Top 3 suspicious files: git blame -L {region}. Return [{file,line_range,sha,author,date,content}] as JSON.","archaeology","","1","pending","","",""

spawn_agents_on_csv({ csv_path:"tasks.csv", id_column:"id",
  instruction: ARCHAEOLOGY_INSTRUCTION + TERMINATION_CONTRACT,
  max_concurrency:2, max_runtime_seconds:300,
  output_csv_path:"wave-1-results.csv", output_schema: SHARED_OUTPUT_SCHEMA })

Merge results → evidence.ndjson (phase: "archaeology").

Step 2 — CLI change review:

maestro delegate "PURPOSE: Review recent modifications related to: {issue}
TASK: Analyze intent | Identify risky modifications | Flag potential bug sources
MODE: analysis
CONTEXT: @{relevant_files} | Git log: {top_10_commits}
EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]
CONSTRAINTS: Focus on behavioral changes, not formatting
" --role analyze --mode analysis

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

Step 3: Update understanding.md §2.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-debug({slug}): S_ARCHAEOLOGY — 考古"

Stage 3: Exploration (S_EXPLORE)

Skip if no enabled CLI tools (W006).

maestro delegate "PURPOSE: Gather codebase evidence for: {issue}
TASK: Trace call chains | Find recent changes | Identify error gaps | Check similar patterns
MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON {call_chains, recent_changes, error_gaps, similar_patterns}
CONSTRAINTS: Max 20 entries/category | Symptom-related code paths
Symptoms: {issue}  Archaeology hints: {suspicious_commits}
" --role explore --mode analysis

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

Parse → write explore.json + evidence (phase: "explore"). Update §3. Mark G2 done.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-debug({slug}): S_EXPLORE — 探索"

Stage 4: Diagnosis (S_DIAGNOSE)

1. Form hypotheses from evidence (archaeology + explore), ranked [HIGH]/[MEDIUM]/[LOW] → §4
2. Test each (rank order): design test → execute → evidence (phase: "diagnosis")
3. Decision journal: ambiguity → evidence (phase: "decision"); Normal: request_user_input | -y: defer
4. Root cause: confirmed → session.json.root_cause + §5. Mark G1 done.

Escalation (3-strike): All hypotheses fail → increment diagnosis_retries.

• < 3: broaden scope via maestro delegate --role analyze, form new hypotheses.

• = 3: Normal → request_user_input (broaden/new/INCONCLUSIVE) | -y → auto INCONCLUSIVE, proceed to S_RECORD.

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

Stage 5: Fix (S_FIX)

Skip if --skip-fix.

1. Present root cause + proposed fix. Normal: request_user_input | -y: auto proceed
2. Implement fix
3. Record in evidence (phase: "decision")

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

Stage 6: Confirmation (S_CONFIRM)

Skip if --skip-fix.

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

maestro delegate "PURPOSE: Review fix for: {issue}
TASK: Verify correctness | Check regressions | Assess completeness
MODE: analysis
CONTEXT: @{modified_files} | Root cause: {summary} | Diff: {git_diff}
EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regression_risk}
CONSTRAINTS: Focus on correctness, not style
" --role review --mode analysis

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

3. Write session.json.confirmation: {test_result, cli_review, overall, timestamp}
4. Update §6. needs_rework → Stage 5. confirmed → mark G3 done, advance.

📌 Auto-commit: git add understanding.md && git commit -m "odyssey-debug({slug}): S_CONFIRM — 确认"

Stage 7: Generalization (S_GENERALIZE)

Skip if --skip-generalize. 举一反三: extract pattern, scan for siblings.

Step 1 — Multi-layer pattern extraction:

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

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

Append Wave 2 rows to tasks.csv:

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

spawn_agents_on_csv({ csv_path:"tasks.csv", id_column:"id",
  instruction: GENERALIZATION_INSTRUCTION + TERMINATION_CONTRACT,
  max_concurrency:4, max_runtime_seconds:300,
  output_csv_path:"wave-2-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 §7 + session.json.generalization_stats: {patterns_extracted, total_hits, cross_layer_confirmed, regression_risks, by_layer, deepening_triggered}. Mark G4 done.

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

Stage 8: Discovery (S_DISCOVER)

Skip if no generalization hits.

1. Triage each hit: read ±10 lines → classify safe/risk/bug
2. Route (explicit action required for each classification):
   • bug + directly fixable → fix immediately (not just log an issue) → back to S_FIX
   • bug + 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 -y behavior. Append evidence (phase: "discovery" + "decision")
3. Cross-phase loop:
   • discovery finds new bug → S_DIAGNOSE (cross_phase_loops++)
   • same-pattern bug + fix template → S_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 §8. Mark G5 done.

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

Stage 9: Record (S_RECORD)

1. Finalize understanding.md §9
2. Write learnings to understanding.md §9: 按 Knowledge Persistence 表分类记录（临时），completion summary 列出建议的后续命令
3. Mark G6 done. Pending decisions: Normal → request_user_input | -y → 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:

--- DEBUG ODYSSEY COMPLETE ---
Issue:      {issue}
Root cause: {root_cause.hypothesis}
Fix:        {applied|skipped|inconclusive}
Patterns:   {patterns_extracted} ({by_layer} distribution)
Scan hits:  {total_hits} ({cross_layer_confirmed} cross-layer confirmed)
Issues:     {N} created
Decisions:  {N} resolved, {M} pending, {K} deferred
Learnings:  {N} spec entries persisted
Self-iter:  {N} quality gate rounds across {M} stages
Goals:      {done}/{total} confirmed ({skipped} skipped)
---

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

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

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

/goal 穷尽迭代：直到根因确认（或明确 INCONCLUSIVE）且修复验证通过
且泛化扫描穷尽且 phase_goals_all_done=true 才停。
假设失败时扩范围→换视角→升级工具，不轻易放弃。
泛化发现的同类 bug 全部修复或创建 issue，不允许遗留。
遇到 phase=decision 的 pending 必须 request_user_input，不得自行 resolve。