odyssey-debug

<required_reading> Required reading: base (odyssey-base-codex.md) before any actions. Load and apply base invariants, execution discipline, and shared actions before proceeding. </required_reading>

--template <name>:

Template	Strategy	Use case
`performance`	profiling → hot path → allocation → cache	Performance degradation
`memory-leak`	heap snapshot → retention chain → lifecycle	Memory leaks
`race-condition`	timeline → concurrent access → lock analysis	Race conditions
`regression`	git bisect → diff analysis → boundary check	Regressions
`crash`	stack trace → null chain → error propagation	Crashes / exceptions

Session: .workflow/scratch/{YYYYMMDD}-debug-odyssey-{slug}/ Output: session.json | evidence.ndjson | explore.json | understanding.md

session.json — debug-specific fields:

{ "issue": "", "diagnosis_retries": 0, "root_cause": null, "confirmation": null,
  "patterns": [], "generalization_stats": null }

archaeology: sha, author, date, message, relevance
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, resolution
self-iteration: stage, round, assessment, expansion

explore.json: {call_chains, recent_changes, error_gaps, similar_patterns, cli_tool, timestamp}

phase_goals[]:

ID	Goal	done_when	phase	skip_when
G1	Root cause identified	phase=diagnosis result=confirmed	S_DIAGNOSE	—
G2	Explore context gathered	explore.json ≥1 category	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 none actionable	S_RECORD	—

understanding.md — 9 sections:

Issue & Scope ← S_INTAKE | 2. Archaeology ← S_ARCHAEOLOGY | 3. Exploration ← S_EXPLORE
Hypotheses ← S_DIAGNOSE | 5. Root Cause ← S_DIAGNOSE | 6. Fix & Confirmation ← S_FIX+S_CONFIRM
Generalization ← S_GENERALIZE | 8. Discoveries ← S_DISCOVER | 9. Learnings ← S_RECORD

Output boundary: ALL session artifacts MUST target the session directory (.workflow/scratch/{YYYYMMDD}-debug-odyssey-{slug}/) or .workflow/state.json only. Source code modifications during S_FIX are in-scope but MUST be committed per action. NEVER write session artifacts outside these paths.

Knowledge Persistence categories (§9):

Category	Content	Follow-up
Recurring root cause pattern	Type + triggers + fix + detection	`/spec-add debug`
Non-obvious workaround	Problem + steps + why obvious fix fails	`/spec-add learning`
Architecture boundary violation	Violation + correct boundary + verification	`/spec-add arch`
Reusable generalization pattern	Signature + risk + fix template + scope	`/spec-add coding`

<csv_schema>

Shared Output Schema (all waves)

{
  "type": "object",
  "properties": {
    "id": {"type":"string"}, "result_status": {"type":"string","enum":["completed","failed"]},
    "findings": {"type":"string","maxLength":500}, "evidence": {"type":"string"}, "error": {"type":"string"}
  },
  "required": ["id","result_status","findings"]
}

Termination Contract (embed in every instruction):

You MUST call report_agent_job_result EXACTLY ONCE before exiting.
Success → result_status=completed | Failure → result_status=failed with error | Timeout → completed with partial.
NEVER continue indefinitely. NEVER exit silently. Read-only — do NOT modify source files.
Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv.

tasks.csv

id,title,description,task_type,deps,wave,status,findings,evidence,error

Wave 1: Archaeology (git-timeline, git-blame) — parallel
Wave 2: Generalization (syntax-grep, semantic-scan, structural-match, historical-grep) — parallel, depends on root cause
Single-agent stages (explore, diagnose, fix, confirm) remain inline </csv_schema>

<self_iteration> Applies to: S_ARCHAEOLOGY, S_EXPLORE, S_DIAGNOSE, S_GENERALIZE. Logic in base. </self_iteration>

Phase Gates (MANDATORY, BLOCKING)

GATE 1: INTAKE → ARCHAEOLOGY

REQUIRED: Issue parsed, SESSION_DIR created, session.json initialized with phase_goals[].
BLOCKED if: no issue and no session (E001).

GATE 2: ARCHAEOLOGY → EXPLORE

REQUIRED: Git history analysis completed (timeline + blame agents), evidence phase=archaeology logged.
REQUIRED: understanding.md §2 updated.
BLOCKED if: both archaeology agents AND delegate failed (partial results via W003 are acceptable).

GATE 3: EXPLORE → DIAGNOSE

REQUIRED: explore.json written (or W006 skip logged), evidence phase=explore logged, G2 marked done.
BLOCKED if: exploration started but not completed.

GATE 4: DIAGNOSE → FIX

REQUIRED: Root cause confirmed with evidence refs, session.json.root_cause written, G1 marked done.
BLOCKED if: hypotheses failed 3 times without escalation decision.

GATE 5: FIX → CONFIRM

REQUIRED: Fix implemented with evidence phase=fix logged.
BLOCKED if: no fix attempted.

GATE 6: CONFIRM → GENERALIZE

REQUIRED: Tests pass, CLI review completed, confirmation overall == confirmed, G3 marked done.
BLOCKED if: needs_rework → route back to S_FIX.

GATE 7: GENERALIZE → DISCOVER

REQUIRED: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged.
REQUIRED: generalization_stats written with by_layer entries for all 3 layers, G4 marked done.
BLOCKED if: any layer not attempted (thoroughness floor violation).

GATE 8: DISCOVER → RECORD

REQUIRED: All hits triaged with per-item classification and reason.
REQUIRED: remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged, G5 marked done.
BLOCKED if: unclassified hits remain.

<state_machine>

S_ARCHAEOLOGY → S_EXPLORE : complete S_EXPLORE → S_DIAGNOSE : complete

S_DIAGNOSE → S_FIX : confirmed, !skip_fix S_DIAGNOSE → S_GENERALIZE : confirmed, skip_fix, !skip_generalize S_DIAGNOSE → S_RECORD : confirmed, skip_fix, skip_generalize S_DIAGNOSE → S_DIAGNOSE : all hypotheses failed, retries < 3 → A_ESCALATE_DIAGNOSIS S_DIAGNOSE → S_RECORD : retries >= 3 → INCONCLUSIVE

S_FIX → S_CONFIRM : fix implemented S_CONFIRM → S_GENERALIZE : confirmed, !skip_generalize S_CONFIRM → S_RECORD : confirmed, skip_generalize S_CONFIRM → S_FIX : needs_rework

S_GENERALIZE → S_DISCOVER : similar code found S_GENERALIZE → S_RECORD : no similar code

S_DISCOVER → S_DIAGNOSE : new bug → cross_phase_loops++ S_DISCOVER → S_FIX : same-pattern bug + fix_template, !skip_fix → cross_phase_loops++ S_DISCOVER → S_RECORD : remaining_actionable == 0 S_DISCOVER → S_RECORD : loops >= max_loops → log per-item reasons

S_RECORD → END : complete

A_INTAKE

Parse arguments, generate slug, create SESSION_DIR
maestro search "<keywords>" + Glob prior sessions + ARCHITECTURE.md + Grep keywords
Derive phase_goals[] from flags
Write session.json + understanding.md §1, call create_goal with phase_goals as success_criteria

Commit: "odyssey-debug({slug}): INTAKE — parse target and load context"

A_RESUME_SESSION

Glob latest session → read session.json → jump to current_state.

A_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 via maestro delegate --to claude --mode analysis (run_in_background: true):

PURPOSE: Review recent modifications related to {issue}
EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]

Update §2. Commit: "odyssey-debug({slug}): ARCHAEOLOGY — git history analysis"

A_EXPLORE

Skip if no CLI tools (W006).

maestro delegate --to claude --mode analysis (run_in_background: true):

PURPOSE: Call chains, recent changes, error gaps, similar patterns
EXPECTED: JSON {call_chains, recent_changes, error_gaps, similar_patterns}

Write explore.json + evidence phase=explore. Update §3. Mark G2. Commit: "odyssey-debug({slug}): EXPLORE — codebase exploration"

A_DIAGNOSE

Hypotheses from evidence, ranked [HIGH]/[MEDIUM]/[LOW] → §4
Test each → evidence phase=diagnosis
Ambiguity → evidence phase=decision; Normal: request_user_input | -y: defer
Confirmed → session.json.root_cause + §5. Mark G1.

Commit: "odyssey-debug({slug}): DIAGNOSE — root cause confirmed"

A_ESCALATE_DIAGNOSIS

diagnosis_retries++. < 3: maestro delegate --to claude --mode analysis, new hypotheses, → S_DIAGNOSE. >= 3: Normal → request_user_input | -y → INCONCLUSIVE → S_RECORD.

A_FIX

Present root cause + proposed fix. Normal: request_user_input | -y: auto proceed
Implement fix, evidence phase=decision

Commit: "odyssey-debug({slug}): FIX — {summary}"

A_CONFIRM

Run covering tests
maestro delegate --to claude --mode analysis (run_in_background: true):
- EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regression_risk}
session.json.confirmation: {test_result, cli_review, overall: "confirmed|needs_rework"}
Update §6. needs_rework → S_FIX. confirmed → mark G3.

Commit: "odyssey-debug({slug}): CONFIRM — fix verified"

A_GENERALIZE

Skip if --skip-generalize. Pattern source: root cause + fix. Base shared_actions for 3-layer extraction + cross-layer dedup + iterative deepening.

Wave 2 — 4-agent scan (spawn_agents_on_csv):

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 })

Update §7. Mark G4. Commit: "odyssey-debug({slug}): GENERALIZE — pattern scan complete"

A_DISCOVER, A_RECORD

Base shared_actions. Debug overrides:

A_DISCOVER routes scan hits per csv_schema wave results. Commit: "odyssey-debug({slug}): DISCOVER — triage complete"
A_RECORD learnings per Knowledge Persistence table. Confirmation gate: Before writing spec entries, present proposed entries to user via request_user_input for confirmation. Skip confirmation only if -y flag is set.

Completion summary:

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

`-y` debug-specific points

Decision Point	Normal	`-y`
A_DIAGNOSE ambiguity	request_user_input	deferred
A_ESCALATE 3-strike	request_user_input	INCONCLUSIVE
A_FIX direction	request_user_input	auto proceed

Goal convergence rules

Stop when root cause confirmed (or INCONCLUSIVE), fix verified,
generalization exhausted, phase_goals_all_done=true.
All sibling bugs fixed or issued — no leftovers.

</state_machine>

<error_codes>

Code	Severity	Condition	Recovery
E001	error	No issue, no session	Provide issue or -c
E002	error	Target path not found	Check path
W001	warning	No relevant git history	Proceed
W002	warning	3 retries exhausted	INCONCLUSIVE
W005	warning	Pending decisions	Filter evidence phase=decision
W006	warning	No CLI tools	Skip explore
</error_codes>

<success_criteria>

Session + 4 output files + prior knowledge searched
Archaeology + CLI review → evidence phase=archaeology
CLI exploration → explore.json + evidence phase=explore
Hypotheses tested, root cause with evidence refs
understanding.md 9 sections progressive
Fix + confirmed (unless --skip-fix)
Generalization + scan (unless --skip-generalize)
Discoveries classified; unfixed findings individually justified
phase_goals + goal audit + resumable via -c
Completion summary </success_criteria>

<next_step_routing>

Condition	Next
Discovery issues	`/manage-issue list --source debug-odyssey`
Document pattern	`/learn-decompose <module>`
Formal review	`/quality-review <phase>`
Second opinion	`/learn-second-opinion <understanding.md>`
Related question	`/learn-investigate "<question>"`
Pending decisions	Filter evidence phase=decision status=pending
</next_step_routing>