Skip to content

oliverv/caro / .agents/skills/oma-backend

oma-backend

Unverified

Implement server APIs, authentication, and application data access. Schema modeling and query tuning use oma-db.

FileKindSize
SKILL.mdskill md9.9 KB
resources/checklist.mdmarkdown2.1 KB
resources/error-playbook.mdmarkdown3.9 KB
resources/execution-protocol.mdmarkdown2.3 KB
resources/orm-reference.mdmarkdown3.9 KB

resources/error-playbook.md

View on GitHub
# Backend Agent - Error Recovery Playbook

When you encounter a failure, find the matching scenario and follow the recovery steps.
Use the relevant recovery steps. If required information or authority is missing, pause the dependent action and continue independent work.

---

## Import / Module Not Found

**Symptoms**: Module/package not found errors

1. Check the import path: typo? wrong package name?
2. Verify the dependency exists in your package manifest
3. If missing: note it in your result as "requires install the missing dependency"; do NOT install yourself
4. If it's a local module: check the directory structure with `get_symbols_overview`
5. If the path changed: use `search_for_pattern("class ClassName")` to find the new location

---

## Test Failure

**Symptoms**: test runner returns FAILED, assertion errors

1. Read the full error output: which test, which assertion, expected vs actual
2. `find_symbol("test_function_name")` to read the test code
3. Determine: is the test wrong or is the implementation wrong?
   - Test expects old behavior → update test
   - Implementation has a bug → fix implementation
4. Run the specific failing test with verbose output
5. After the fix, run affected regression tests; run a broader suite only when impact or project requirements justify it
6. **After 3 failures**: Try a different approach. Record current attempt in progress and implement alternative

---

## Database Migration Error

**Symptoms**: Migration command fails, `IntegrityError`, duplicate column

1. Read the error; is it a conflict with existing migration?
2. Check current DB state: Check current migration state
3. If migration conflicts: Rollback one migration step then fix migration script
4. If schema mismatch: compare model with actual DB schema
5. **NEVER do this**: Force-mark migrations as applied (risk of data loss)

---

## Authentication / JWT Error

**Symptoms**: 401/403 responses, `InvalidTokenError`, `ExpiredSignatureError`

1. Check: is the secret key consistent between encode and decode?
2. Check: is the algorithm specified (`HS256` vs `RS256`)?
3. Check: is the token being sent in the correct header format? (`Bearer {token}`)
4. Check: is token expiry set correctly? (access: 15min, refresh: 7day)
5. Test with a manually created token to isolate the issue

---

## N+1 Query / Slow Response

**Symptoms**: API response > 500ms, many similar SQL queries in logs

1. Enable SQL logging on the database connection
2. Count queries for a single request
3. If N+1: add eager loading strategy appropriate for your ORM to the query
4. If slow single query: check indexes with `EXPLAIN ANALYZE`
5. If still slow: consider caching with Redis

---

## Rate Limit / Quota Error (LLM runtime)

**Symptoms**: `429`, `RESOURCE_EXHAUSTED`, `rate limit exceeded` (any vendor runtime — Gemini, Claude, Codex, etc.)

1. **Stop immediately**; do not make additional API calls
2. Save current work to `progress-{agent-id}[-{sessionId}].md`
3. Record Status: `quota_exceeded` in `result-{agent-id}[-{sessionId}].md`
4. Specify remaining tasks so orchestrator can retry later

---

## Workflow State Unavailable

Follow `../../_shared/runtime/memory-protocol.md`; state storage is independent of the code-intelligence provider.

1. Use the injected progress/result paths and session/task identity.
2. If a file operation fails, retry once when the failure may be transient.
3. Preserve work and report the failed path and error to the coordinator. Do not silently redirect artifacts to `/tmp` or mark a missing result as completed.
4. For read-only tasks, return the result through the runtime's response channel as required by the dispatch contract.

---

## General Principles

- **After 3 failures**: If same approach fails 3 times, must try a different method
- **Blocked**: If no progress after 5 turns, save current state and record `Status: blocked` in result
- **Out of scope**: If you find issues in another agent's domain, only record in result; do not modify directly
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall