map-debug

name	map-debug
description	Structured MAP debugging via task-decomposer, actor, and monitor agents. Use when reproducing a bug, isolating a regression, or diagnosing an error with specialized agents — including failing or flaky tests (pytest AssertionError), crashes and segmentation faults, memory-corruption or memory errors in native/C extensions, intermittent or load-dependent failures (e.g. 500s under load), data-corruption bugs that only appear in production, scripts or hooks that silently exit or produce no output, and any "find the root cause" / "walk me through diagnosing" / "help me investigate" request. Trigger on phrasing like "failing test", "mysterious error", "segfault", "memory error", "intermittently fails", "root cause", "isolate the cause", "debug why", "diagnose", or "investigate the error". Prefer this over generic investigation when the user wants a systematic decompose-reproduce-fix-verify workflow. Do NOT use for greenfield features; use map-plan or map-efficient.
effort	medium
disable-model-invocation	true
argument-hint	[bug description]

MAP Debugging Workflow

Workflow Guardrails

Use the specialized MAP agents because debugging depends on isolated root-cause evidence:

• Start with task-decomposer so investigation, fix, and verification work are separated.
• Use actor for each investigation or fix subtask rather than a general-purpose agent.
• Use monitor after each fix subtask so written code is validated before impact analysis.
• Use predictor and evaluator only after Monitor approves a fix, as described below.
• Do not combine phases to save time; each phase consumes the previous phase's evidence.

Debug the following issue using the MAP framework:

Debug Request: $ARGUMENTS

Use compact evidence-first examples from Evidence-First Output Examples when asking agents to report root causes, validation failures, or impact risks. Use the shared XML Prompt Envelope for long debugging prompts so logs, affected files, and fixes are separated from instructions and output contracts.

Effort and Parallelism Policy

thinking_policy: medium/adaptive
parallel_tool_policy: sequential_root_cause_first

• Spend reasoning on reproducing symptoms, isolating the root cause, and verifying the fix; do not drift into broad cleanup or feature work.
• Keep the debugging pipeline sequential because each phase depends on the latest evidence and written repo state.
• Parallelize only independent read-only log/code searches during initial investigation.

When Not To Expand Scope

• Do not turn a bug fix into a refactor, feature, or architecture cleanup unless the root cause requires that change.
• Do not add extra agents beyond the documented debugging sequence; switch workflows only if the task stops being a debugging task.
• Do not continue polishing after the original symptom is reproduced, fixed, and verified.

Mutation Boundary Constraints

These constraints apply to every fix subtask:

• Do not edit unrelated files, even if they are nearby or easy to clean up.
• Do not add, remove, or upgrade dependencies unless the root cause evidence explicitly requires that dependency change.
• Do not refactor neighboring code unless the bug cannot be fixed and verified without that exact refactor.
• If a dependency change, broad refactor, or scope expansion seems necessary, report it as a blocker/tradeoff instead of doing it silently.

Workflow Overview

Debugging workflow focuses on analysis before implementation:

1. DECOMPOSE → task-decomposer (break down debugging steps)
2. REPRODUCE → write an executable probe; record_repro_probe MUST witness exit 42
   ("no fix without root cause") before any fix is written
3. FOR each fix step:
   4. IMPLEMENT → actor (edit files directly)
   5. VALIDATE → monitor (check written files)
   6. PREDICT → predictor (assess impact of fix)
   7. EVALUATE → evaluator (verify fix quality)
   8. Keep Actor's already-written fix
9. VERIFY → verify_repro_resolved: the SAME probe MUST flip to exit 0 (resolved)
10. DONE → Suggest /map-learn if user wants to preserve patterns

Step 1: Analyze the Issue

Before calling task-decomposer, gather context:

1. Read error logs/stack traces (if provided in $ARGUMENTS)
2. Identify affected files: Use Grep/Glob to find relevant code
3. Reproduce the issue (if possible): Read test files or run commands

Step 2: Decompose Debugging Process

Task(
  subagent_type="task-decomposer",
  description="Decompose debugging steps",
  prompt="<documents>
  <document source='debug-request'>
    <document_content>$ARGUMENTS</document_content>
  </document>
  <document source='error-logs'>
    <document_content>[if available]</document_content>
  </document>
  <document source='affected-files'>
    <document_content>[from analysis]</document_content>
  </document>
</documents>

<task>
Break down this debugging process into atomic investigation, fix, and verification steps.
</task>

JSON contract reference: [Decomposition Output](../../references/map-json-output-contracts.md#decomposition-output).

<expected_output>
Output JSON with:
- subtasks: array of {id, description, debug_type: 'investigation'|'fix'|'verification', acceptance_criteria}
- root_cause_hypothesis: string
- estimated_complexity: 'low'|'medium'|'high'
</expected_output>

<constraints>
Debug types:
- investigation: analyze code, logs, reproduce issue
- fix: implement solution
- verification: test fix, check for regressions
</constraints>"
)

Step 2.5: Reproduce With an Executable Probe (MANDATORY root-cause gate)

No fix may be written until an executable probe has empirically reproduced the bug. This operationalizes the "no fix without root cause" Iron Law: the runner witnesses the bug instead of trusting a claim, and the probe becomes a deterministic artifact Monitor / final-verifier can re-run.

1. Write a small, self-contained executable probe under .map/<branch>/repro/ (it is gitignored — throwaway). Give it a shebang and the sentinel exit contract:

   • exit 42 when the bug reproduces (MAP_REPRODUCED)
   • exit 0 when the bug is absent (MAP_RESOLVED)
   • any other exit code or a timeout = inconclusive (the gate will not advance)

   Example .map/<branch>/repro/probe.sh (a shell wrapper makes this language-agnostic — wrap the real check for pytest / go test / node / etc.):

   #!/usr/bin/env bash
   # Reproduces the bug: <one-line root-cause hypothesis>.
   # Exit 42 while the bug is present, 0 once it is fixed.
   if python3 -c 'import sys; from app import parse; sys.exit(0 if parse("") == [] else 1)'; then
     exit 0     # correct behavior -> bug absent
   else
     exit 42    # wrong behavior -> bug reproduced
   fi
   

2. Record it. The runner copies the probe into an immutable locked snapshot, executes it, and arms the gate only when it actually exits 42:

   python3 .map/scripts/map_step_runner.py record_repro_probe \
     .map/<branch>/repro/probe.sh \
     --root-cause "<short root-cause statement>"
   

   • valid:true, phase:"reproduced" → the root cause is demonstrated; proceed to the fix.
   • valid:false (exit code != 42) → you do not yet understand the bug. Return to investigation; do NOT write a fix.

3. Only now implement the fix (Step 3), then verify the flip in Step 4.

Scope & honesty:

• Keep probes throwaway. Promote a probe to a real regression test only when the bug warrants permanent coverage.
• The runner proves a witnessed behavioral flip (42 → 0) on an immutable probe — not that the probe captures the real root cause. Monitor still judges that.
• If an executable probe is genuinely impossible (e.g. a pure docs/comment typo with no runtime behavior), STOP and surface a CLARIFICATION_NEEDED to the user with the reason. Never skip the gate silently or hand-write the artifact.

Step 3: For Each Debugging Step

Investigation Steps

For subtasks with debug_type: 'investigation':

Task(
  subagent_type="actor",
  description="Investigate issue",
  prompt="Investigate this debugging step:

**Step:** [description]
**Goal:** [acceptance_criteria]

Perform analysis and provide:
- quotes: array of {source, locator, quote, relevance}; quote exact logs, test output, or code fragments before root_cause
- findings: array of observations
- root_cause: string (if identified)
- next_steps: array of recommended actions
- code_locations: array of {file, line_range, issue_description}

Use Read, Grep tools to analyze code. Do NOT make changes yet."
)

Fix Steps

For subtasks with debug_type: 'fix':

Task(
  subagent_type="actor",
  description="Implement fix for [issue]",
  prompt="Implement a fix for this issue:

**Issue:** [from investigation]
**Root Cause:** [identified root cause]

Apply the fix directly with Edit/Write tools.
Do not edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the root cause evidence explicitly requires it. Report any required scope expansion as a blocker/tradeoff.

JSON contract reference: [Actor Change Summary](../../references/map-json-output-contracts.md#actor-change-summary).

Output JSON with:
- approach: string (fix strategy)
- files_changed: array of file paths actually edited
- tests_run: array of commands run, or [] if deferred to the orchestrator
- why_this_fixes_it: string (explain the fix)
- potential_side_effects: array of strings
- remaining_risks: array of strings

Do not serialize full file contents in your response."
)

Monitor Validation

After each fix (max 5 Actor->Monitor retry iterations per subtask):

• On the first Monitor rejection, pass feedback back to Actor normally.
• On the second or later rejection for the same fix attempt, run python3 .map/scripts/map_step_runner.py build_retry_quarantine debug-fix <retry_count> "<monitor feedback>" and make the next Actor prompt use .map/<branch>/retry_quarantine.json as CLEAN_RETRY context. Do not reuse the rejected approach unless the quarantine artifact explicitly preserves it.

Task(
  subagent_type="monitor",
  description="Validate fix",
  prompt="<documents>
  <document source='original-issue'>
    <document_content>[description]</document_content>
  </document>
  <document source='written-files'>
    <document_content>Written Files: [files_changed from Actor]</document_content>
  </document>
  <document source='root-cause'>
    <document_content>[identified root cause]</document_content>
  </document>
</documents>

<task>
Validate this debugging fix in the written repo state.
</task>

<instructions>
Check:
- Read the written files and verify the code exists in the repo
- Does the fix address the root cause?
- Are there any security issues introduced?
- Are there proper error handling?
- Is the fix testable?
- Are there any edge cases missed?
</instructions>

<expected_output>
Output JSON with:
- evidence: array of {file_path, line_range, quote, relevance}; cite the changed code or failing/passing test before verdict fields
- valid: boolean
- issues: array of {severity, category, description}
- verdict: 'approved'|'needs_revision'|'rejected'
- feedback: string
</expected_output>"
)

Predictor Impact Analysis

For approved fixes:

Task(
  subagent_type="predictor",
  description="Analyze fix impact",
  prompt="Analyze the impact of this debugging fix:

**Fix:** [paste actor JSON]
**Monitor Verdict:** approved

Analyze:
- Could this fix introduce new bugs?
- Are there other places with similar issues?
- Does this require updating tests?
- Are there performance implications?

Output JSON with:
- evidence: array of {file_path, line_range, quote, relevance}; include support for each similar issue or high-risk claim
- similar_issues: array of {file, line, description}
- risk_level: 'low'|'medium'|'high'
- recommended_additional_changes: array of strings
- regression_test_requirements: array of strings"
)

Evaluator Quality Check

Task(
  subagent_type="evaluator",
  description="Evaluate fix quality",
  prompt="Evaluate this debugging fix:

**Fix:** [paste actor JSON]
**Monitor Verdict:** [verdict]
**Predictor Analysis:** [paste predictor JSON]

Score (0-10):
- correctness: does it fix the issue?
- completeness: are all edge cases covered?
- clarity: is the fix understandable?
- testing: is it properly tested?

Output JSON with:
- evidence: array of {file_path, line_range, quote, relevance}; cite changed code or test output for any score below 7
- scores: object
- overall_score: number
- recommendation: 'proceed'|'improve'|'reject'
- justification: string"
)

Proceed After Evaluation

If evaluator recommends proceeding:

• Keep Actor's already-written changes
• Run tests to verify fix
• Check that original issue is resolved
• Write a deferred learning handoff so /map-learn can reuse the debug context later:

python3 .map/scripts/map_step_runner.py write_learning_handoff \
  map-debug \
  "$ARGUMENTS" \
  "Debugging workflow complete" \
  "Ship the fix, or run /map-review if you want independent scrutiny" \
  "<root cause + fix summary>"

This writes .map/<branch>/learning-handoff.md and .json, updates artifact_manifest.json, and keeps post-debug learning cheap.

Step 4: Verification

After all fixes applied:

1. Run full test suite to check for regressions

2. Verify the original issue is resolved with the repro-probe gate — re-run the SAME probe; it must flip from reproducing (42) to resolved (0):

   python3 .map/scripts/map_step_runner.py verify_repro_resolved
   

   valid:true, phase:"resolved" confirms the fix. valid:false (still reproducing or inconclusive) is a hard stop: the fix did not resolve the root cause — return to Step 3. The runner re-runs the immutable locked snapshot, so a sha256-mismatch error means the probe was altered — re-record_repro_probe from the original probe.

3. Check predictor's similar_issues - fix those too if relevant

4. Create commit with clear description of fix and root cause

5. Write a run health report with the terminal status that matches the verified debug outcome:

# Set from verification: complete, pending, blocked, won't_do, or superseded.
RUN_HEALTH_STATUS="${RUN_HEALTH_STATUS:?set RUN_HEALTH_STATUS from the debug verification outcome}"
python3 .map/scripts/map_step_runner.py write_run_health_report \
  map-debug \
  "$RUN_HEALTH_STATUS"

Use complete only when the bug is fixed and verified. Use pending when more code work remains, blocked when an external/tooling dependency prevents verification, won't_do when the fix is intentionally abandoned, and superseded when another branch/workflow owns the resolution. This writes .map/<branch>/run_health_report.json, updates the run_health stage in artifact_manifest.json, and gives reviewers one machine-readable snapshot of retries, artifact presence, hook status, and terminal state.

---

💡 Optional: Preserve Debugging Lessons

If you want to save debugging patterns for future use:

/map-learn

This is completely optional. Run it when debugging patterns are valuable for future reference.

MCP Tools for Debugging

• mcp__sequential-thinking__sequentialthinking - Complex root cause analysis

Debugging Constraints

• Identify the root cause before implementing fixes.
• Prove the root cause with an executable probe BEFORE any fix (record_repro_probe must witness exit 42); verify the same probe flips to exit 0 after the fix (verify_repro_resolved). See Step 2.5 — the gate is a hard stop, never skipped silently.
• Test after applying fixes.
• Check for similar issues in other parts of the codebase when Predictor flags them or the root cause pattern is reusable.
• Use the Task tool to call the specialized subagents in the sequence above.

Examples

User says: /map-debug TypeError in authentication middleware

You should:

1. Gather context (read error logs, find middleware file)
2. Task(subagent_type="task-decomposer") → get investigation + fix steps
3. For investigation steps: Task(subagent_type="actor") to analyze
4. For fix steps: actor → monitor → predictor → evaluator → apply
5. Run tests, verify fix
6. Done! Optionally run /map-learn to preserve debugging patterns

Begin debugging now.

Troubleshooting

• Issue: A fix is applied before the root cause is identified. Fix: Stop and return to investigation — the repro-probe gate (Step 2.5) requires record_repro_probe to witness exit 42 BEFORE any fix.
• Issue: verify_repro_resolved returns valid:false after the fix. Fix: Hard stop — the probe still reproduces (exit 42) or is inconclusive, so the root cause is not resolved. Iterate the fix and re-verify; do not commit. A sha256-mismatch reason means the locked probe was altered — re-record_repro_probe from the original.
• Issue: The same bug pattern may exist elsewhere. Fix: Check sibling code when Predictor flags it or the root cause is reusable (see "Debugging Constraints").
• Issue: The session was interrupted mid-workflow. Fix: Run /map-resume to recover.