# Debug

> A Claude skill from mattjaikaran/meridian.

- **Type:** Skill
- **Install:** `agentstack add skill-mattjaikaran-meridian-debug`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mattjaikaran](https://agentstack.voostack.com/s/mattjaikaran)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [mattjaikaran](https://github.com/mattjaikaran)
- **Source:** https://github.com/mattjaikaran/meridian/tree/main/skills/debug

## Install

```sh
agentstack add skill-mattjaikaran-meridian-debug
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /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
2. Search codebase for similar patterns
3. 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:

```bash
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

```bash
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](https://github.com/mattjaikaran)
- **Source:** [mattjaikaran/meridian](https://github.com/mattjaikaran/meridian)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mattjaikaran-meridian-debug
- Seller: https://agentstack.voostack.com/s/mattjaikaran
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.