Debug

/meridian:debug — Systematic Debugging

4-phase systematic debugging with decision logging. Uses the protocol from references/discipline-protocols.md.

Arguments

• `` — Bug description or error message
• --plan — Associate with a specific plan
• --phase — Associate with a specific phase

Procedure

Phase 1: Investigation

1. Read the full error message and stack trace
2. Identify the exact file, line, and function
3. Check recent changes: git log --oneline -10 and git diff
4. Reproduce the error by running the failing test/command
5. Record findings

Phase 2: Pattern Recognition

1. Categorize the error type:

• Import/module error
• Type error / null reference
• Logic error / wrong behavior
• Race condition / timing
• Configuration / environment
• Data integrity

1. Search codebase for similar patterns
2. Check if this is a known issue pattern

Phase 3: Hypothesis

1. Form a specific hypothesis: "The error occurs because X"
2. Identify evidence that would confirm/refute
3. Test with minimal change
4. Record hypothesis and result as a decision:

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_decision
conn = connect(get_db_path('.'))
create_decision(conn, '', category='approach',
    rationale='', phase_id=)
conn.close()
"

Phase 4: Implementation

1. Fix at the source, not the symptom
2. Run the failing test — must pass now
3. Run full test suite — no regressions
4. Commit the fix with descriptive message

Escalation Rule

After 3 failed fix attempts:

• STOP fixing
• Record a deviation decision
• Re-examine assumptions
• Consider if the problem is architectural
• May need to re-plan the current phase

PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
from scripts.db import connect, get_db_path
from scripts.state import create_decision
conn = connect(get_db_path('.'))
create_decision(conn, 'Escalation: 3+ failed fixes on . Likely architectural.',
    category='deviation', rationale='')
conn.close()
"

Output

Report:

• Root cause identified
• Fix applied (file:line)
• Tests passing
• Decision logged

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mattjaikaran
• Source: mattjaikaran/meridian
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.