quality-debug

Session Initialization

Parse from $ARGUMENTS:
  AUTO_YES       ← --yes | -y
  continueMode   ← --continue
  maxConcurrency ← --concurrency | -c N  (default: 5)
  fromUat        ← --from-uat <phase>  (default: null)
  fromAutoTest   ← --from-auto-test <phase>  (default: null)
  parallelMode   ← --parallel
  bugDescription ← remaining text after flag removal

Derive:
  phaseRef       ← fromUat || fromAutoTest || null
  sourceType     ← fromAutoTest ? "auto-test" : fromUat ? "uat" : "standalone"
  slug           ← bugDescription kebab-cased, max 40 chars
  dateStr        ← UTC+8 YYYYMMDD
  sessionId      ← phaseRef ? "{dateStr}-debug-P{phaseRef}-{slug}" : "{dateStr}-debug-{slug}"
  sessionFolder  ← ".workflow/.csv-wave/{sessionId}"

mkdir -p {sessionFolder}

Phase 1: Input Resolution -> CSV

Objective: Parse mode, gather symptoms or load UAT gaps, generate hypotheses, build tasks.csv.

Decomposition Rules:

1. Mode detection:

2. Related session discovery: Query state.json.artifacts[] for matching phase+milestone. Extract relevant outputs by type: execute -> .summaries/.task/, review -> review.json (guide hypotheses), debug -> understanding.md (avoid re-investigation), test -> uat.md + .tests/auto-test/report.json.

2b. Load codebase + wiki context (optional, informs hypothesis generation):

• If .workflow/codebase/ARCHITECTURE.md exists: read module boundaries to scope impact analysis
• Run maestro search "<symptom keywords>" --json 2>/dev/null; if results: check for prior investigations on similar issues
• Run maestro spec load --category debug --keyword "<symptom keywords>"; if tools found: extract known issues, workarounds, and root-cause notes to inform hypotheses
• All are optional — proceed without if unavailable

3. Symptom collection:

from-auto-test specifics: Each code_defect failure provides: scenario_id, req_ref, description, expected, actual, fix_suggestion.file, fix_suggestion.line, fix_suggestion.direction. Map these to symptoms: expected=failure.expected, actual=failure.actual, location=fix_suggestion.file:line, context=fix_suggestion.direction.

3. Hypothesis generation: Per symptom cluster, analyze affected code and generate 3-5 ranked hypotheses (each becomes a wave 1 row).

4. Fix task generation: Pre-generate wave 2 fix row per hypothesis (deps/context_from -> hypothesis ID). Only executes if hypothesis confirmed.

5. CSV generation: Hypothesis rows (wave 1) + fix rows (wave 2).

Wave computation: Simple 2-wave -- all hypothesis tasks = wave 1, all fix tasks = wave 2.

User validation: Display hypothesis breakdown (skip if AUTO_YES).

Phase 2: Wave Execution Engine

Objective: Investigate hypotheses wave-by-wave via spawn_agents_on_csv.

Wave 1: Hypothesis Investigation (Parallel)

1. Extract wave-1 input: filter master tasks.csv rows where wave == 1 AND status == "pending" → write wave-1.csv containing ONLY input columns (id, title, description, hypothesis, deps, context_from, wave). No lifecycle columns, no prev_context (wave 1 has no upstream).
2. Execute:

spawn_agents_on_csv({
  csv_path: `${sessionFolder}/wave-1.csv`,
  id_column: "id",
  instruction: WAVE1_INVESTIGATION_INSTRUCTION,  // see "Wave 1 Worker Contract" below
  max_concurrency: maxConcurrency,
  max_runtime_seconds: 3600,
  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
  output_schema: {
    type: "object",
    properties: {
      id:                  { type: "string" },
      result_status:       { type: "string", enum: ["completed", "failed"] },
      hypothesis_verdict:  { type: "string", enum: ["confirmed", "refuted", "inconclusive"], description: "Investigation outcome" },
      findings:            { type: "string", maxLength: 500 },
      evidence_for:        { type: "string" },
      evidence_against:    { type: "string" },
      error:               { type: "string" }
    },
    required: ["id", "result_status", "hypothesis_verdict", "findings"]
  }
})

3. Merge: for each row in wave-1-results.csv, look up master row by id and write master.status = result_status, then copy hypothesis_verdict, findings, evidence_for, evidence_against, error. Delete wave-1.csv and wave-1-results.csv.
4. Wave 2 gating (read from MASTER tasks.csv after merge, NOT from wave-1-results.csv):
   • For each FIX-H{N} row: read its context_from hypothesis ID (e.g., H{N}) from master; if master H{N}.hypothesis_verdict != "confirmed", set FIX-H{N}.status = "skipped" (with findings = "upstream hypothesis_verdict={H{N}.hypothesis_verdict}").
   • Only rows where status == "pending" proceed to wave 2.

Wave 1 Worker Contract (WAVE1_INVESTIGATION_INSTRUCTION)

The literal instruction string passed to spawn_agents_on_csv MUST include the following contract (substitute {sessionFolder} at build time):

You are a hypothesis investigation worker. ONE hypothesis row from wave-1.csv is assigned to you.

INPUT (from your CSV row):
  - id, title, hypothesis, description

REQUIRED STEPS:
  1. Read shared discoveries: {sessionFolder}/discoveries.ndjson (may be empty)
  2. Scan codebase for evidence using Read/Grep/Glob (read-only investigation)
  3. Classify the hypothesis based on evidence collected:
     - confirmed   → strong evidence supports the hypothesis (file:line proof) → result_status=completed, hypothesis_verdict=confirmed
     - refuted     → strong evidence contradicts the hypothesis → result_status=completed, hypothesis_verdict=refuted
     - inconclusive → insufficient evidence within time budget; do NOT guess → result_status=completed, hypothesis_verdict=inconclusive
     - failed      → tool error / cannot read files / blocked by environment → result_status=failed
  4. Append discoveries to {sessionFolder}/discoveries.ndjson if reusable (root_cause / hypothesis_evidence types)
  5. Call report_agent_job_result EXACTLY ONCE with the verdict

TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
  - Success path  → result_status=completed, hypothesis_verdict = confirmed | refuted, with evidence
  - Timeout path  → if approaching {max_runtime_seconds}, STOP investigation and report result_status=completed, hypothesis_verdict=inconclusive
  - Failure path  → on any unrecoverable error, result_status=failed with error message
  - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.

OUTPUT (return via report_agent_job_result; must match output_schema):
  {
    "id": "<your row id>",
    "result_status": "completed" | "failed",
    "hypothesis_verdict": "confirmed" | "refuted" | "inconclusive",
    "findings": "<one-sentence summary, max 500 chars>",
    "evidence_for": "<bullet list of file:line refs supporting, or empty>",
    "evidence_against": "<bullet list of file:line refs refuting, or empty>",
    "error": "<message if failed, else empty>"
  }

CONSTRAINTS:
  - Do NOT modify source code. This is investigation only.
  - Do NOT write to tasks.csv, wave-*.csv, or results.csv (orchestrator owns those).
  - Do NOT call spawn_agents_on_csv (no recursion).

Wave 2: Fix Attempts (Parallel, Confirmed Only)

1. If no master rows have wave == 2 AND status == "pending" after gating, skip wave 2 entirely.
2. Extract wave-2 input: filter master tasks.csv where wave == 2 AND status == "pending". For each row, build prev_context by concatenating findings/evidence_for from each ID in context_from (read from master). Write wave-2.csv with input columns + prev_context.
3. Execute:

spawn_agents_on_csv({
  csv_path: `${sessionFolder}/wave-2.csv`,
  id_column: "id",
  instruction: WAVE2_FIX_INSTRUCTION,  // see "Wave 2 Worker Contract" below
  max_concurrency: maxConcurrency,
  max_runtime_seconds: 3600,
  output_csv_path: `${sessionFolder}/wave-2-results.csv`,
  output_schema: {
    type: "object",
    properties: {
      id:            { type: "string" },
      result_status: { type: "string", enum: ["completed", "failed"] },
      fix_result:    { type: "string", enum: ["fixed", "fix_failed"], description: "Fix attempt outcome" },
      findings:      { type: "string", maxLength: 500 },
      fix_applied:   { type: "string" },
      verified:      { type: "string", enum: ["true", "false"] },
      error:         { type: "string" }
    },
    required: ["id", "result_status", "fix_result", "findings", "verified"]
  }
})

4. Merge: write master.status = result_status, copy fix_result, findings, fix_applied, verified, error. Delete wave-2.csv and wave-2-results.csv.

Wave 2 Worker Contract (WAVE2_FIX_INSTRUCTION)

You are a fix worker. ONE confirmed hypothesis row is assigned to you.

INPUT (from your CSV row):
  - id (FIX-H{N}), title, description, prev_context (confirmed evidence from H{N})

REQUIRED STEPS:
  1. Read prev_context — the confirmed root cause evidence
  2. Apply the minimal fix using Edit / Write
  3. Run verification:
     - If project has tests: run the relevant test suite via Bash
     - If no tests: re-read the modified file and confirm the fix matches the planned change
  4. Append discoveries (type=fix_applied) to {sessionFolder}/discoveries.ndjson if reusable
  5. Call report_agent_job_result EXACTLY ONCE

TERMINATION CONTRACT (mandatory):
  - Success path → fix applied AND verified → result_status=completed, fix_result=fixed, verified="true"
  - Partial path → fix applied but verification failed → result_status=completed, fix_result=fix_failed, verified="false"
  - Timeout path → approaching {max_runtime_seconds} with no fix applied → result_status=completed, fix_result=fix_failed with error="timeout"
  - Failure path → cannot apply fix (file missing, parse error, etc.) → result_status=failed
  - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.

OUTPUT (return via report_agent_job_result; must match output_schema):
  {
    "id": "<your row id>",
    "result_status": "completed" | "failed",
    "fix_result": "fixed" | "fix_failed",
    "findings": "<one-sentence summary of what was changed, max 500 chars>",
    "fix_applied": "<file:line description of the change>",
    "verified": "true" | "false",
    "error": "<message if failed, else empty>"
  }

CONSTRAINTS:
  - Modify ONLY files implicated by prev_context evidence. No drive-by refactors.
  - Do NOT write to tasks.csv, wave-*.csv, or results.csv.
  - Do NOT call spawn_agents_on_csv (no recursion).

Phase 3: Results Aggregation

Objective: Generate final results and human-readable report.

1. Export final tasks.csv as results.csv

2. Generate understanding.md: Debug report with summary (mode, hypothesis/confirmed/fixed/verified counts), per-hypothesis results (hypothesis, evidence for/against, findings, status), per-fix results (fix applied, verified, findings), aggregated root causes, and next steps.

2b. Debug confidence scoring:

Dimensions (4): hypothesis_quality, evidence_completeness, root_cause_isolation, fix_confidence. Factors (weights): evidence_depth(.30), evidence_strength(.25), coverage_breadth(.20), reproduction(.15), consistency(.10). Map to legacy: <40% = low, 40-70% = medium, >70% = high. Append confidence assessment to understanding.md.

3. UAT update (if --from-uat): Update uat.md gaps with root_cause, fix_direction, affected_files for confirmed hypotheses.

4. Issue update: If issues.jsonl exists, update matching issues with status diagnosed, add context.suggested_fix and context.notes.

5. Register artifact (phase-scoped only): Append to state.json.artifacts[] with type: "debug", id: DBG-NNN, depends_on: triggering_review_id || exec_art.id.

6. Post-debug Knowledge Inquiry: Prompt user to capture knowledge when:

   • Recurring root cause pattern detected -> $spec-add debug
   • Non-obvious fix strategy used -> $spec-add learning
   • Architectural gap identified -> $spec-add arch

7. Next step routing:

9. Display summary.

Shared Discovery Board Protocol

Standard Discovery Types

Domain Discovery Types

Protocol

Read discoveries.ndjson before investigation. Append-only: dedup by type+key before writing, never modify/delete.

echo '{"ts":"<ISO>","worker":"{id}","type":"root_cause","data":{"location":"src/auth/login.ts:42","cause":"null_dereference","severity":"high","confidence":"confirmed"}}' >> {session_folder}/discoveries.ndjson