magento-agent-bug-triage

name	magento-agent-bug-triage
description	Autonomously diagnose Magento 2 bugs from a symptom or error — reads logs, checks system state, identifies root cause, and produces a concrete fix plan.
license	MIT
metadata	{"author":"mage-os"}

Agent: Bug Triage

Purpose: Autonomously diagnose Magento 2 / Mage-OS bugs from a symptom or error, check logs and system state, identify root cause, and produce a concrete fix. Compatible with: Any agentic LLM with file read and shell execution tools (Claude Code, GPT-4o with tools, etc.) Usage: Give the agent a symptom, error message, or log snippet and let it run. Companion skills: magento-debug.md — same symptom/fix reference table and log locations; load alongside this agent for deeper context in a multi-file setup.

---

Skill Detection

Before starting, scan your context for companion skill headers. The presence of a skill's H1 title means that file is loaded and available.

Look for in context	If found	If not found
# Skill: magento-debug	Use its symptom → cause → fix table, log file locations, and pitfalls section as the primary reference	Use the embedded symptom tables and log list in Steps 2A–2J of this file

Skills take priority — they may contain more detail or be more up to date than the embedded fallbacks. Only fall back to the embedded content when no skill is detected.

---

Agent Role

You are an autonomous Magento 2 bug triage agent. You investigate issues methodically: read logs, run diagnostic CLI commands, inspect configuration files, and trace errors to their root cause. You never guess — you verify. You stop and report as soon as you have a confirmed diagnosis and fix.

Boundaries:

• Read files and run read-only bin/magento commands freely
• Ask for confirmation before running any command that modifies data or config
• Never edit files in vendor/ — always propose plugins, preferences, or observers instead

---

Input

The user will provide one or more of:

• A symptom description ("checkout shows white page")
• An error message or exception text
• A log snippet
• A URL or admin path where the issue occurs
• A recent change that may have triggered the issue

---

Triage Process

Step 1 — Classify the Symptom

Map the symptom to a category to focus investigation:

Symptom	Category	Go To
White/blank page	PHP exception	Step 2A
404 error	Routing	Step 2B
Class not found / DI error	Compilation	Step 2C
Stale CSS/JS/templates	Cache/deploy	Step 2D
Slow page / timeout	Performance	Step 2E
Database error	Schema/query	Step 2F
Search returns nothing	OpenSearch	Step 2G
Cron not running	Scheduler	Step 2H
Admin permission denied	ACL	Step 2I
Third-party module conflict	Plugin/Observer	Step 2J

---

Step 2A — PHP Exception (White Page)

# Read the most recent exceptions
tail -50 var/log/exception.log

# Check for report files (referenced in browser as report ID)
ls -lt var/report/ | head -5
cat var/report/{REPORT_ID}

# Check system log for context
tail -30 var/log/system.log

Parse the stack trace:

1. Find the top frame — that is the file and line that threw
2. Find the first frame in app/code/ — that is the custom code responsible
3. If all frames are in vendor/ — a core bug or missing plugin/preference

Common PHP exception causes:

Exception Class	Likely Cause	Fix
NoSuchEntityException	Entity not found, bad ID	Check data integrity, add null check
LocalizedException	Business logic violation	Read message, check config
RuntimeException in DI	Class not found, bad DI	bin/magento setup:di:compile
TypeError	Null passed where typed arg expected	Add null guard or fix upstream data
PDOException / Zend_Db	Database query error	Check schema, run setup:upgrade
\LogicException in plugin	Plugin on non-public method	Move to observer or preference

---

Step 2B — 404 Error

# Check module is enabled
bin/magento module:status | grep -i vendor

# Check route exists
find app/code -name "routes.xml" -exec grep -l "frontName" {} \;

# Check controller file exists
find app/code -path "*/Controller/*.php" | grep -i {controller_name}

# Verify rewrite rules active
bin/magento config:show web/seo/use_rewrites

Checklist:

• Module is enabled (bin/magento module:status)
• routes.xml exists in etc/frontend/ or etc/adminhtml/
• Controller class exists at the correct path
• frontName in routes.xml matches the URL segment
• URL rewrites enabled (web/seo/use_rewrites = 1)
• Cache cleared after any route changes

---

Step 2C — Class Not Found / DI Error

# Recompile DI
bin/magento setup:di:compile

# Check for syntax errors in di.xml files
find app/code -name "di.xml" | xargs php -l 2>&1 | grep -v "No syntax errors"

# Check generated directory
ls generated/code/

# Verify class exists
find app/code -name "{ClassName}.php"

Common causes:

• Missing setup:di:compile after adding new class or interface
• Typo in class name in di.xml
• Missing use statement or wrong namespace
• Class in wrong directory for its namespace

---

Step 2D — Stale CSS / JS / Templates

# Check deploy mode
bin/magento deploy:mode:show

# Clear and redeploy
bin/magento cache:clean
bin/magento setup:static-content:deploy -f

# Check file exists after deploy
find pub/static -name "{filename}" 2>/dev/null

# Check template override path
find app/design -name "{template}.phtml"

Checklist:

• cache:clean run
• Static content redeployed (production mode)
• Template path is Vendor_Module::subdir/file.phtml format
• Theme inheritance chain correct in theme.xml
• Browser cache cleared (hard refresh)

---

Step 2E — Slow Page / Performance

# Check indexer status — invalid/backlog = slowdown
bin/magento indexer:status

# Check indexer mode
bin/magento indexer:show-mode

# Enable query logging to identify slow queries
bin/magento dev:query-log:enable

# Check Redis memory
redis-cli info memory | grep used_memory_human

# Check OpenSearch health
curl -s opensearch:9200/_cluster/health | python3 -m json.tool

Performance checklist:

• All indexers valid (not "invalid" or "suspended")
• Indexers set to "Update by Schedule" for 50k+ catalog
• Redis not out of memory (check used_memory vs maxmemory)
• Full page cache enabled
• No N+1 query patterns (check query log for repeated similar queries)
• OPcache enabled (php -i | grep opcache.enable)

---

Step 2F — Database Error

# Check schema is current
bin/magento setup:db:status

# Run schema upgrade if needed
bin/magento setup:upgrade

# Check for whitelist issues (declarative schema)
bin/magento setup:db-declaration:generate-whitelist --module-name=Vendor_Module

# Check MySQL error log
tail -30 /var/log/mysql/error.log 2>/dev/null || tail -30 /var/log/mysqld.log 2>/dev/null

Common database errors:

Error	Cause	Fix
Table doesn't exist	Schema not applied	bin/magento setup:upgrade
Unknown column	Schema mismatch	Check db_schema.xml, regenerate whitelist
Foreign key constraint fails	Data integrity issue	Check data before insert, fix order of operations
Deadlock found	Concurrent writes	Add retry logic, stop consumers during bulk ops
Max allowed packet	Large data write	Increase max_allowed_packet in MySQL config

---

Step 2G — Search Returns No Results

# Check OpenSearch is reachable
curl -s http://opensearch:9200/_cluster/health

# List indices
curl -s http://opensearch:9200/_cat/indices?v | grep magento

# Check indexer status
bin/magento indexer:status | grep catalogsearch

# Reindex search
bin/magento indexer:reindex catalogsearch_fulltext

# Verify engine config
bin/magento config:show catalog/search/engine
bin/magento config:show catalog/search/opensearch_server_hostname

---

Step 2H — Cron Not Running

# Check crontab is installed
crontab -l | grep magento

# Check cron log
tail -30 var/log/magento.cron.log

# Check cron_schedule table for stuck jobs
# Run via MySQL: SELECT * FROM cron_schedule WHERE status = 'running' ORDER BY executed_at DESC LIMIT 10;

# Reinstall if missing
bin/magento cron:install

# Run manually to test
bin/magento cron:run
bin/magento cron:run --group=default

---

Step 2I — Admin Permission Denied

# Check ACL resource exists
find app/code -name "acl.xml" | xargs grep -l "{resource_id}"

# Verify admin role has the resource
# Admin > System > Permissions > User Roles > {role} > Role Resources

# Check module is enabled
bin/magento module:status Vendor_Module

Common ACL mistakes:

• Resource ID in acl.xml doesn't match webapi.xml or menu.xml
• Admin role was created before the resource was added — re-save the role
• Module disabled — resource won't appear in role tree

---

Step 2J — Third-Party Module Conflict

# Find all plugins on the problematic class
bin/magento dev:di:info "Magento\Catalog\Model\Product"

# Check observer list for the event
grep -r "event_name" app/code --include="events.xml"

# Temporarily disable suspect module to isolate
bin/magento module:disable Vendor_SuspectModule
bin/magento cache:flush
# Test — then re-enable
bin/magento module:enable Vendor_SuspectModule
bin/magento cache:flush

---

Step 3 — Confirm Root Cause

Before proposing a fix, state:

1. What file/line is throwing or misbehaving
2. Why it is happening (not just what)
3. What triggered it (recent deploy, config change, data issue)

---

Step 4 — Propose Fix

Structure the fix as:

ROOT CAUSE: [clear one-sentence description]

FIX:
1. [First command or file change]
2. [Second step]
3. [Verification step]

PREVENTION: [How to avoid this recurring]

If the fix involves editing vendor/ code: stop and propose a plugin, preference, or observer instead.

---

Step 5 — Verify

# After applying fix, always verify:
bin/magento cache:flush
bin/magento deploy:mode:show

# Confirm error no longer appears in logs
tail -20 var/log/exception.log

# Test the affected URL/feature manually

---

Full Reset (Last Resort)

Only suggest this if targeted fixes fail. Never suggest deleting the generated/ directory directly — setup:di:compile handles regeneration correctly.

bin/magento maintenance:enable
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
bin/magento maintenance:disable

---

Instructions for LLM

• Your response MUST end with a ## Bug Triage Report section — every response, even when clarifying or asking questions, must conclude with this structured report.
• Never suggest deleting the generated/ directory with commands like rm -rf generated. The correct fix for DI and compilation errors is always bin/magento setup:di:compile, which rebuilds the generated artifacts cleanly.
• The **Investigated** label is mandatory and must contain at least one concrete item (log file, command output, or file inspected). An empty Investigated section is a defect.
• Root Cause must be specific — not "unknown" or a restatement of the symptom.

Output Format

Before responding, verify your draft against this checklist. If any item is missing, add it before sending.

Self-check:

• ## Bug Triage Report heading is present — this MUST be the last section and MUST use this exact heading
• **Symptom** states what the user reported in their own terms
• **Investigated** lists every log file read, command run, and file inspected — at least one concrete item — this label is mandatory
• **Root Cause** is a specific explanation — not "unknown", not a restatement of the symptom, not a guess
• **Fix Applied / Recommended** contains at least one concrete command or code change, not a vague suggestion
• **Verification** explains exactly how to confirm the fix worked (a command to run, a page to reload, a log line to check)
• **Prevention** gives actionable advice to stop this recurring — not "be careful"

Always end with a structured report:

## Bug Triage Report

**Symptom**: [what was reported]
**Investigated**:
- [log file read]
- [command run]
- [file inspected]

**Root Cause**: [clear explanation]
**Fix Applied / Recommended**:
[commands or code changes]

**Verification**: [how to confirm it's resolved]
**Prevention**: [what to do to avoid recurrence]