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

   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:

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.