debug

name	debug
description	Debug errors, test failures, or unexpected behavior. Auto-detects project type.
argument-hint	[error message or description]

Debug Command

Context

TECH_STACK = config_read("tech_stack", "generic")
LESSONS_PATH = config_read("lessons_path", ".agents/lessons/")

Bug Description

<bug_description>$ARGUMENTS</bug_description>

If the bug description above is empty, ask the user: "What error or issue are you experiencing? Please paste the error message or describe the unexpected behavior."

Do not proceed until you have a clear bug description.

Discover Similar Past Issues

Check if lessons directory exists, then discover similar past issues:

Task(subagent_type="majestic-engineer:workflow:lessons-discoverer",
     prompt="workflow_phase: debugging | tech_stack: [tech_stack from context] | task: [bug_description]")

If lessons found with score > 70:

Present the high-confidence matches to the user BEFORE starting investigation:

Found similar past issues:

1. [Lesson title] (score: 78)
   {lessons_path}/[category]/[filename].md

2. [Lesson title] (score: 65)
   {lessons_path}/[category]/[filename].md

Use AskUserQuestion:

High-confidence match found. Read the documented solution first?
1. Read Lesson 1 (Recommended)
2. Read Lesson 2
3. Continue with full investigation

If user chooses to read a lesson:

• Display the lesson content using Read(file_path="[lesson_path]")
• Ask: "Does this apply to your issue?"
• If yes: Apply the documented solution, verify it works
• If no: Continue with full investigation

Error handling:

• If lessons directory doesn't exist: Continue to Project Context Detection
• If discovery returns 0 lessons: Continue to Project Context Detection
• If discovery fails: Log warning, continue to Project Context Detection

This step is non-blocking - failures do not stop the workflow.

Project Context Detection

Step 1: Check config

Use "Tech stack" from Context above. If configured, use it to determine project type.

Step 2: Check AGENTS.md for debugging guidance

Look for AGENTS.md in the project root for:

• Debugging workflows
• Testing commands
• Project-specific conventions

Step 3: Fall back to file-based detection only if needed

If neither config nor AGENTS.md provides context, detect project type from files:

ls Gemfile package.json pyproject.toml setup.py go.mod Cargo.toml 2>/dev/null

File Found	Project Type	Debugger
Gemfile	Ruby/Rails	agent rails-debugger
package.json	Node.js	General debugging
pyproject.toml / setup.py	Python	General debugging
go.mod	Go	General debugging
Cargo.toml	Rust	General debugging

Workflow

For Rails Projects (from AGENTS.md or Gemfile detected)

Invoke the specialized Rails debugger agent:

agent rails-debugger "<bug_description>"

The rails-debugger will:

• Analyze stack traces and error messages
• Check recent git changes
• Inspect logs and database state
• Identify root cause and propose fixes

For Other Projects

1. Analyze the error message - Parse for error types, file paths, line numbers
2. Check recent changes - git log --oneline -10 and git diff HEAD~3
3. Search for solutions - Use web-research agent if needed
4. Propose fix - Provide minimal code changes to resolve

Output Format

After debugging, provide:

1. Root Cause - What's actually wrong (explain why, not just what)
2. Evidence - Specific logs, traces, or code proving the cause
3. Fix - Minimal code changes to resolve the issue
4. Verification - Commands or tests to confirm the fix works