odyssey-debug

<purpose>
Closed-loop deep debugging: archaeology → explore → diagnose → fix & confirm → generalize → discover siblings → persist.
Treats every bug as a learning signal with exhaustive iteration until root cause confirmed or INCONCLUSIVE.
</purpose>

<boundary>
**范围内:** 单一 bug/issue 的完整闭环 — 考古 → 探索 → 诊断 → 修复 → 确认 → 泛化同类 → 沉淀
**范围外:** 新功能开发 → `/odyssey-planex` | 代码质量审查 → `/odyssey-review-test-fix` | UI 视觉优化 → `/odyssey-ui` | 架构重设计 → `/maestro-plan`
**探索自由度:** 边界内自由探索 — 可追踪任意调用链、分析任意历史、测试任意假设。泛化阶段可扫描全项目寻找同类问题。
**Zero-residual principle:** Every finding MUST have a concrete action (fix / issue / decision). "Report and shelve" is not allowed. "Pre-existing issue" is not a valid skip reason — if discovered within scope, it must be addressed.
**模板支持:** `--template <name>` 从预定义调查策略启动，跳过假设生成直接进入针对性诊断：

| Template | 调查策略 | 适用场景 |
|----------|---------|---------|
| `performance` | profiling → hot path → allocation → cache | 性能劣化 |
| `memory-leak` | heap snapshot → retention chain → lifecycle | 内存泄漏 |
| `race-condition` | timeline → concurrent access → lock analysis | 竞态条件 |
| `regression` | git bisect → diff analysis → boundary check | 回归问题 |
| `crash` | stack trace → null chain → error propagation | 崩溃/异常 |
</boundary>

<execution_discipline>
**三条铁律（所有阶段适用）:**

1. **Phase auto-commit** — 每个阶段完成后**自动** `git commit`，无需用户确认
   - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-debug({slug}): {phase} — {摘要}"`
   - session.json / evidence.ndjson 为运行时状态，不纳入 commit
   - 确保每个阶段的进展可回溯、可恢复

2. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
   - Confident → edit code directly, commit
   - Needs decision → record `evidence.ndjson {"phase":"decision","status":"pending"}`, don't touch code
   - No speculative changes
   - ⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
     - Cross-module architectural tradeoffs requiring human direction
     - Ambiguous business semantics where the fix could alter intended behavior
     - Requires new dependency or breaking API change
   - ❌ "Unsure how to fix", "Large scope", "Pre-existing issue" are NOT valid decision reasons — either fix it, or explain specifically why it's unfixable

3. **多 CLI 辅助** — 利用 `maestro delegate` 调用多个 CLI 工具交叉验证
   - 关键判断用不同 `--role`（analyze / review / explore）获取多视角
   - 修复前后各做一次 CLI review 确认
   - 不同阶段可调用不同工具，综合多方意见再行动

4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
</execution_discipline>

<context>
$ARGUMENTS — issue description and optional flags.

**Flags:** `--skip-fix` analysis-only | `--skip-generalize` quick fix | `--template <name>` 预定义策略 | `--auto` no delegate confirmation | `-y` auto-confirm all decisions | `-c` resume last session

**Session**: `SESSION_DIR = .workflow/scratch/{YYYYMMDD}-debug-odyssey-{slug}/`

**Output — 4 files:**
```
SESSION_DIR/
  ├── session.json       # state + confirmation + patterns + phase_goals
  ├── evidence.ndjson    # append-only evidence trail (phase field distinguishes origin)
  ├── explore.json       # structured CLI exploration snapshot
  └── understanding.md   # evolving narrative — 9 sections
```

**session.json schema:**
```json
{
  "session_id": "debug-odyssey-{YYYYMMDD-HHmmss}", "issue": "",
  "flags": { "skip_fix": false, "skip_generalize": false, "auto": false, "auto_confirm": false },
  "current_state": "S_INTAKE", "diagnosis_retries": 0,
  "root_cause": null, "patterns": [], "confirmation": null,
  "phase_goals": [], "phase_goals_all_done": false, "self_iteration_log": [],
  "generalization_stats": null,
  "cross_phase_loops": 0, "max_loops": 5,
  "created_at": "", "updated_at": ""
}
```

**evidence.ndjson — unified trail:**
```json
{"ts":"","phase":"archaeology|explore|diagnosis|discovery|decision|self-iteration","type":"","source":"","content":"","note":""}
```
Phase-specific fields:
- `archaeology`: `sha`, `author`, `date`, `message`, `relevance` (high|medium|low)
- `explore`: `category` (call_chain|recent_change|error_gap|similar_pattern), `detail`
- `diagnosis`: `hypothesis`, `result` (confirmed|disproved|inconclusive)
- `discovery`: `file`, `line`, `classification` (safe|risk|bug), `action` (fix|issue|decision|skip)
- `decision`: `question`, `options`, `context`, `status` (pending|resolved|deferred), `resolution`
- `self-iteration`: `stage`, `round`, `assessment`, `expansion`

**explore.json schema:**
```json
{
  "call_chains": [{"entry":"","chain":["file:line"]}],
  "recent_changes": [{"file":"","commits":[{"sha":"","message":"","date":""}]}],
  "error_gaps": [{"file":"","line":0,"description":""}],
  "similar_patterns": [{"file":"","line":0,"description":""}],
  "cli_tool": "", "timestamp": ""
}
```

**phase_goals[] — auto-derived from flags:**

| ID | Goal | done_when | phase | skip_when |
|----|------|-----------|-------|-----------|
| G1 | Root cause identified | evidence.ndjson has phase=diagnosis result=confirmed | S_DIAGNOSE | — |
| G2 | Explore context gathered | explore.json ≥1 category populated | S_EXPLORE | — |
| G3 | Fix applied and confirmed | confirmation.overall == confirmed | S_CONFIRM | skip_fix |
| G4 | Pattern generalized | patterns[] ≥1 entry | S_GENERALIZE | skip_generalize |
| G5 | Discoveries triaged | all scan hits classified | S_DISCOVER | skip_generalize |
| G6 | Learnings persisted | spec entries created OR no actionable learnings | S_RECORD | — |

When `flags[skip_when] == true` → auto set `status: "skipped"`, `completion_confirmed: true`.

**understanding.md — 9 sections (written by owning phase):**
1. Issue & Scope ← S_INTAKE | 2. Archaeology Summary ← S_ARCHAEOLOGY | 3. Exploration ← S_EXPLORE
4. Hypotheses & Testing ← S_DIAGNOSE | 5. Root Cause ← S_DIAGNOSE | 6. Fix & Confirmation ← S_FIX+S_CONFIRM
7. Generalization ← S_GENERALIZE | 8. Discoveries & Decisions ← S_DISCOVER | 9. Learnings ← S_RECORD

### Pre-load（可选，缺失不阻塞）

| 层级 | 命令 | 作用 |
|------|------|-