aitbc/ai-memory/debugging-playbook.md

# Debugging Playbook

Standardized troubleshooting steps for common issues in the AITBC system.

---

## CLI Command Fails with Import Error

**Symptoms**
```
ModuleNotFoundError: No module named 'trading_surveillance'
```
or similar when running `aitbc <command>`.

**Checklist**
1. ✅ CLI venv has required packages: `numpy`, `pandas`, `aiohttp`, `fastapi`, `uvicorn`
   ```bash
   pip list | grep -E "numpy|pandas|aiohttp|fastapi|uvicorn"
   ```
2. ✅ `pyproject.toml` includes these dependencies under `[tool.poetry.dependencies]` or equivalent.
3. ✅ Service modules are reachable via PYTHONPATH. CLI command modules prepend the service path at runtime.
4. ✅ No name shadowing in the command file (imported functions aliased if needed).

**Fix**
- Install missing packages into CLI venv.
- Update `pyproject.toml` and reinstall.
- If shadowing, rename imports with `_svc` suffix.

---

## Brother Chain Node Stuck at Height 0

**Symptoms**
- Health returns `200`, but `getBlock` shows no blocks after genesis
- Mint transactions not confirmed

**Checklist**
1. ✅ `.env` configuration matches the intended chain ID and ports
2. ✅ Node started with `PYTHONPATH` including `apps/blockchain-node/src`
3. ✅ Proposer is configured:
   - `PROPOSER_ID` and `PROPOSER_KEY` set
   - In the consensus configuration, the proposer is listed as an authority
4. ✅ Check node logs for messages about "proposer" and "authority"
5. ✅ Verify RPC `syncStatus` reports progress

**Fix**
- If proposer not set, either set it in `.env` and restart, or manually create a block via RPC (if supported).
- Ensure the genesis file includes the proposer in the authority set.
- Check that the P2P node is running and not failing to accept connections.

---

## Regulatory Command Crashes with `slice(None, 1, None)`

**Symptom**
Running `aitbc regulatory test` or `aitbc regulatory generate-sar` produces:
```
KeyError: slice(None, 1, None)
```

**Cause**
Name shadowing: the command function `generate_sar` overwrote the imported service function `generate_sar`. When the code tried to call `generate_sar(...)`, it actually called the Click command object (which is subscriptable in a weird way), leading to the KeyError.

**Fix**
In `cli/aitbc_cli/commands/regulatory.py`:
- Import as: `from regulatory_reporting import generate_sar as generate_sar_svc`
- Replace all calls to `generate_sar(...)` with `generate_sar_svc(...)`
- Also fix `generate_compliance_summary` → `generate_compliance_summary_svc` and `list_reports` → `list_reports_svc`

**Reference**: See `ai-memory/bug-patterns.md` for full pattern.

---

## Gitea API Returns Empty or 403

**Symptoms**
- `curl` to `/api/v1/repos/...` returns `[]` or `403`
- Expected data not visible

**Checklist**
1. ✅ Token has `repo` scope (full control of private repositories)
2. ✅ Token user is a collaborator with Write permission on the repository
3. ✅ Using correct `GITEA_API_BASE` and `GITEA_REPO`
4. ✅ Token is correctly exported: `export GITEA_TOKEN=...`
5. ✅ User identity matches collaborator entry (`aitbc` or `aitbc1`)

**Fix**
- Generate a new token with sufficient scopes in Gitea (Settings → Applications)
- Ensure the user is added as collaborator with Write access (Repository → Settings → Collaborators)

---

## PR Merge Blocked by Branch Protection

**Symptoms**
- Merge button disabled in web UI
- API merge returns error about required approvals or status checks

**Checklist**
1. ✅ PR has at least one approval from the other agent
2. ✅ All required status checks are `success` (e.g., `aitbc/local-validation`)
3. ✅ Branch is up-to-date with `main` (no conflicts)
4. ✅ The reviewing agent's approval is from a different user than the author

**Fix**
- Address any failing checks.
- Request review from the sibling agent and wait for approval.
- Rebase if necessary to resolve conflicts.

---

## Lost Work Due to Duplicate Claims

**Symptom**
Two agents started work on the same issue independently.

**Prevention**
Always use the claim branch pattern before starting:
```bash
git checkout -b claim/<issue-number>
git push origin claim/<issue-number> || exit 1  # fails if already claimed
```
If push fails, another agent claimed it; pick a different issue.

---

## Auto-Review Script Fails to Checkout PR

**Symptoms**
`auto_review.py` logs "Failed to checkout PR#..."

**Checklist**
1. ✅ Token has `repo` scope to read PR branches
2. ✅ The branch exists on remote (`git ls-remote origin <branch>`)
3. ✅ `.git` directory exists and credentials are set for origin
4. ✅ Workdir cleanup on previous failures

**Fix**
- Ensure proper token.
- Manually verify branch exists: `git ls-remote --heads origin aitbc/...`
- Increase log verbosity to capture errors.

---

## Memory Layer Usage

Before attempting a fix, consult:
- `ai-memory/bug-patterns.md` for known patterns
- `ai-memory/architecture.md` for module responsibilities
- `ai-memory/debugging-playbook.md` for systematic troubleshooting
- `ai-memory/failure-archive/` for past failed approaches

---

*End of playbook.*