tribunal-kit 1.0.0 → 2.4.2

package/.agent/skills/python-patterns/SKILL.md

@@ -2,440 +2,228 @@
 name: python-patterns
 description: Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.
 allowed-tools: Read, Write, Edit, Glob, Grep
+version: 1.0.0
+last-updated: 2026-03-12
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Python Patterns
+# Python Development Principles
 
-> Python development principles and decision-making for 2025.
-> **Learn to THINK, not memorize patterns.**
+> Python's flexibility is its greatest weakness.
+> Without conventions, every project ends up with its own unpredictable shape.
 
 ---
 
-## ⚠️ How to Use This Skill
+## Framework Selection
 
-This skill teaches **decision-making principles**, not fixed code to copy.
+| Use Case | Recommended | When to Use |
+|---|---|---|
+| REST API, general-purpose | FastAPI | Type-safe, async, auto-docs via OpenAPI |
+| REST API, batteries-included | Django + DRF | Rapid development, ORM included, admin panel |
+| Microservice / minimal API | Flask | Simple, no overhead, full control |
+| Data pipeline / ETL | No framework | Standard library + pandas/polars as needed |
+| CLI tool | Click or Typer | Better than argparse for complex CLIs |
+| Async task queue | Celery + Redis | Background jobs, scheduled tasks |
 
-- ASK user for framework preference when unclear
-- Choose async vs sync based on CONTEXT
-- Don't default to same framework every time
+**Decision question:** Does this need an ORM, admin panel, and auth out of the box? → Django. Does it need type-safe inputs with automatic validation? → FastAPI. Is it small and needs nothing? → Flask.
 
 ---
 
-## 1. Framework Selection (2025)
+## Type Hints (Required on All New Code)
 
-### Decision Tree
+Python type hints are not optional — they are documentation that also enables static analysis.
 
-```
-What are you building?
-│
-├── API-first / Microservices
-│   └── FastAPI (async, modern, fast)
-│
-├── Full-stack web / CMS / Admin
-│   └── Django (batteries-included)
-│
-├── Simple / Script / Learning
-│   └── Flask (minimal, flexible)
-│
-├── AI/ML API serving
-│   └── FastAPI (Pydantic, async, uvicorn)
-│
-└── Background workers
-    └── Celery + any framework
-```
+```python
+# ❌ No type hints
+def create_user(email, role):
+    ...
 
-### Comparison Principles
+# ✅ Typed
+from typing import Literal
 
-| Factor | FastAPI | Django | Flask |
-|--------|---------|--------|-------|
-| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
-| **Async** | Native | Django 5.0+ | Via extensions |
-| **Admin** | Manual | Built-in | Via extensions |
-| **ORM** | Choose your own | Django ORM | Choose your own |
-| **Learning curve** | Low | Medium | Low |
+def create_user(email: str, role: Literal["admin", "user"] = "user") -> dict[str, str]:
+    ...
+```
 
-### Selection Questions to Ask:
-1. Is this API-only or full-stack?
-2. Need admin interface?
-3. Team familiar with async?
-4. Existing infrastructure?
+**Rules:**
+- All function parameters and return values must be typed
+- Use `from __future__ import annotations` for forward references
+- Run `mypy` or `pyright` as part of CI — type errors fail the build
 
 ---
 
-## 2. Async vs Sync Decision
-
-### When to Use Async
+## Project Structure
 
 ```
-async def is better when:
-├── I/O-bound operations (database, HTTP, file)
-├── Many concurrent connections
-├── Real-time features
-├── Microservices communication
-└── FastAPI/Starlette/Django ASGI
-
-def (sync) is better when:
-├── CPU-bound operations
-├── Simple scripts
-├── Legacy codebase
-├── Team unfamiliar with async
-└── Blocking libraries (no async version)
-```
-
-### The Golden Rule
+src/
+  api/          Route definitions (thin — parse and delegate)
+  services/     Business logic (no HTTP awareness)
+  repositories/ Database access (no business logic)  
+  models/       Pydantic models + SQLAlchemy models
+  lib/          Shared utilities
+  config.py     Settings via pydantic-settings
 
-```
-I/O-bound → async (waiting for external)
-CPU-bound → sync + multiprocessing (computing)
+tests/
+  unit/         Isolated function tests
+  integration/  Database and external service tests
 
-Don't:
-├── Mix sync and async carelessly
-├── Use sync libraries in async code
-└── Force async for CPU work
+pyproject.toml  — single source of truth for deps, linting, test config
 ```
 
-### Async Library Selection
-
-| Need | Async Library |
-|------|---------------|
-| HTTP client | httpx |
-| PostgreSQL | asyncpg |
-| Redis | aioredis / redis-py async |
-| File I/O | aiofiles |
-| Database ORM | SQLAlchemy 2.0 async, Tortoise |
-
 ---
 
-## 3. Type Hints Strategy
+## Async Patterns
 
-### When to Type
-
-```
-Always type:
-├── Function parameters
-├── Return types
-├── Class attributes
-├── Public APIs
-
-Can skip:
-├── Local variables (let inference work)
-├── One-off scripts
-├── Tests (usually)
-```
-
-### Common Type Patterns
+FastAPI uses async by default. Know when to use it and when not to.
 
 ```python
-# These are patterns, understand them:
+# ✅ Use async for I/O-bound operations
+@app.get("/users/{user_id}")
+async def get_user(user_id: str, db: AsyncSession = Depends(get_db)):
+    return await user_service.find_by_id(db, user_id)
 
-# Optional → might be None
-from typing import Optional
-def find_user(id: int) -> Optional[User]: ...
+# ✅ Use sync for CPU-bound operations (or offload to thread pool)
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
 
-# Union → one of multiple types
-def process(data: str | dict) -> None: ...
+executor = ThreadPoolExecutor()
 
-# Generic collections
-def get_items() -> list[Item]: ...
-def get_mapping() -> dict[str, int]: ...
-
-# Callable
-from typing import Callable
-def apply(fn: Callable[[int], str]) -> str: ...
+@app.post("/process")
+async def process_image(file: UploadFile):
+    loop = asyncio.get_event_loop()
+    result = await loop.run_in_executor(executor, cpu_intensive_work, file)
+    return result
 ```
 
-### Pydantic for Validation
-
-```
-When to use Pydantic:
-├── API request/response models
-├── Configuration/settings
-├── Data validation
-├── Serialization
-
-Benefits:
-├── Runtime validation
-├── Auto-generated JSON schema
-├── Works with FastAPI natively
-└── Clear error messages
-```
+**Never:** `time.sleep()` inside an async function — use `await asyncio.sleep()` instead.
 
 ---
 
-## 4. Project Structure Principles
-
-### Structure Selection
-
-```
-Small project / Script:
-├── main.py
-├── utils.py
-└── requirements.txt
-
-Medium API:
-├── app/
-│   ├── __init__.py
-│   ├── main.py
-│   ├── models/
-│   ├── routes/
-│   ├── services/
-│   └── schemas/
-├── tests/
-└── pyproject.toml
-
-Large application:
-├── src/
-│   └── myapp/
-│       ├── core/
-│       ├── api/
-│       ├── services/
-│       ├── models/
-│       └── ...
-├── tests/
-└── pyproject.toml
-```
-
-### FastAPI Structure Principles
-
-```
-Organize by feature or layer:
-
-By layer:
-├── routes/ (API endpoints)
-├── services/ (business logic)
-├── models/ (database models)
-├── schemas/ (Pydantic models)
-└── dependencies/ (shared deps)
-
-By feature:
-├── users/
-│   ├── routes.py
-│   ├── service.py
-│   └── schemas.py
-└── products/
-    └── ...
-```
-
----
-
-## 5. Django Principles (2025)
-
-### Django Async (Django 5.0+)
-
-```
-Django supports async:
-├── Async views
-├── Async middleware
-├── Async ORM (limited)
-└── ASGI deployment
-
-When to use async in Django:
-├── External API calls
-├── WebSocket (Channels)
-├── High-concurrency views
-└── Background task triggering
-```
+## Error Handling
 
-### Django Best Practices
-
-```
-Model design:
-├── Fat models, thin views
-├── Use managers for common queries
-├── Abstract base classes for shared fields
-
-Views:
-├── Class-based for complex CRUD
-├── Function-based for simple endpoints
-├── Use viewsets with DRF
-
-Queries:
-├── select_related() for FKs
-├── prefetch_related() for M2M
-├── Avoid N+1 queries
-└── Use .only() for specific fields
+```python
+# Custom exception hierarchy
+class AppError(Exception):
+    def __init__(self, message: str, code: str, status_code: int = 400):
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        super().__init__(message)
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, id: str):
+        super().__init__(f"{resource} {id} not found", "NOT_FOUND", 404)
+
+class ValidationError(AppError):
+    def __init__(self, message: str):
+        super().__init__(message, "VALIDATION_FAILED", 400)
+
+# FastAPI exception handler
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": exc.message, "code": exc.code}
+    )
 ```
 
 ---
 
-## 6. FastAPI Principles
+## Dependency Management
 
-### async def vs def in FastAPI
+Use `pyproject.toml` with `uv` or `poetry`:
 
-```
-Use async def when:
-├── Using async database drivers
-├── Making async HTTP calls
-├── I/O-bound operations
-└── Want to handle concurrency
-
-Use def when:
-├── Blocking operations
-├── Sync database drivers
-├── CPU-bound work
-└── FastAPI runs in threadpool automatically
-```
+```toml
+[project]
+name = "my-service"
+version = "0.1.0"
+requires-python = ">=3.11"
 
-### Dependency Injection
+dependencies = [
+    "fastapi>=0.110",
+    "pydantic>=2.0",
+    "sqlalchemy[asyncio]>=2.0",
+    "asyncpg>=0.29",
+]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "mypy>=1.0",
+    "ruff>=0.3",
+]
 ```
-Use dependencies for:
-├── Database sessions
-├── Current user / Auth
-├── Configuration
-├── Shared resources
-
-Benefits:
-├── Testability (mock dependencies)
-├── Clean separation
-├── Automatic cleanup (yield)
-```
-
-### Pydantic v2 Integration
 
-```python
-# FastAPI + Pydantic are tightly integrated:
-
-# Request validation
-@app.post("/users")
-async def create(user: UserCreate) -> UserResponse:
-    # user is already validated
-    ...
-
-# Response serialization
-# Return type becomes response schema
-```
+**Never use `requirements.txt` for production projects** — no lock file, no version bounds, no dev/prod separation.
 
 ---
 
-## 7. Background Tasks
+## Code Quality Tools
 
-### Selection Guide
+```bash
+# Linting + formatting (replaces black + flake8 + isort)
+ruff check . --fix
+ruff format .
 
-| Solution | Best For |
-|----------|----------|
-| **BackgroundTasks** | Simple, in-process tasks |
-| **Celery** | Distributed, complex workflows |
-| **ARQ** | Async, Redis-based |
-| **RQ** | Simple Redis queue |
-| **Dramatiq** | Actor-based, simpler than Celery |
+# Type checking
+mypy src/
 
-### When to Use Each
+# Testing
+pytest tests/ -v --tb=short
 
-```
-FastAPI BackgroundTasks:
-├── Quick operations
-├── No persistence needed
-├── Fire-and-forget
-└── Same process
-
-Celery/ARQ:
-├── Long-running tasks
-├── Need retry logic
-├── Distributed workers
-├── Persistent queue
-└── Complex workflows
+# Pre-commit (runs all of the above)
+pre-commit run --all-files
 ```
 
+Configure all tools in `pyproject.toml` — not `.flake8`, `.mypy.ini`, and `.ruff.toml` separately.
+
 ---
 
-## 8. Error Handling Principles
+## Output Format
 
-### Exception Strategy
+When this skill produces or reviews code, structure your output as follows:
 
 ```
-In FastAPI:
-├── Create custom exception classes
-├── Register exception handlers
-├── Return consistent error format
-└── Log without exposing internals
-
-Pattern:
-├── Raise domain exceptions in services
-├── Catch and transform in handlers
-└── Client gets clean error response
+━━━ Python Patterns Report ━━━━━━━━━━━━━━━━━━━━━━━━
+Skill:       Python Patterns
+Language:    [detected language / framework]
+Scope:       [N files · N functions]
+─────────────────────────────────────────────────
+✅ Passed:   [checks that passed, or "All clean"]
+⚠️  Warnings: [non-blocking issues, or "None"]
+❌ Blocked:  [blocking issues requiring fix, or "None"]
+─────────────────────────────────────────────────
+VBC status:  PENDING → VERIFIED
+Evidence:    [test output / lint pass / compile success]
 ```
 
-### Error Response Philosophy
+**VBC (Verification-Before-Completion) is mandatory.**
+Do not mark status as VERIFIED until concrete terminal evidence is provided.
 
-```
-Include:
-├── Error code (programmatic)
-├── Message (human readable)
-├── Details (field-level when applicable)
-└── NOT stack traces (security)
-```
 
 ---
 
-## 9. Testing Principles
-
-### Testing Strategy
+## 🏛️ Tribunal Integration (Anti-Hallucination)
 
-| Type | Purpose | Tools |
-|------|---------|-------|
-| **Unit** | Business logic | pytest |
-| **Integration** | API endpoints | pytest + httpx/TestClient |
-| **E2E** | Full workflows | pytest + DB |
+**Slash command: `/tribunal-backend`**
+**Active reviewers: `logic` · `security` · `dependency` · `type-safety`**
 
-### Async Testing
+### ❌ Forbidden AI Tropes in Python
 
-```python
-# Use pytest-asyncio for async tests
+1. **Missing Type Hints** — writing `def func(a, b):` instead of fully typing parameters and return values.
+2. **Bare `except:` blocks** — catching all exceptions blindly without logging or raising `AppError`.
+3. **`requirements.txt` over `pyproject.toml`** — hallucinating outdated dependency management practices.
+4. **Blocking the async event loop** — writing synchronous I/O or `time.sleep()` inside an `async def` FastAPI route.
+5. **Assuming Django for microservices** — defaulting to a massive framework when `FastAPI` or `Flask` fits better.
 
-import pytest
-from httpx import AsyncClient
+### ✅ Pre-Flight Self-Audit
 
-@pytest.mark.asyncio
-async def test_endpoint():
-    async with AsyncClient(app=app, base_url="http://test") as client:
-        response = await client.get("/users")
-        assert response.status_code == 200
+Review these questions before generating Python code:
 ```
-
-### Fixtures Strategy
-
+✅ Are all function parameters and return types strictly typed?
+✅ Did I use the modern toolchain (`uv`/`poetry`, `ruff`, `mypy`)?
+✅ Did I accidentally block the async event loop with sync code?
+✅ Are domain errors properly caught and mapped to HTTP status codes without leaking stack traces?
+✅ Is my dependency selection precise and explicitly declared in `pyproject.toml`?
 ```
-Common fixtures:
-├── db_session → Database connection
-├── client → Test client
-├── authenticated_user → User with token
-└── sample_data → Test data setup
-```
-
----
-
-## 10. Decision Checklist
-
-Before implementing:
-
-- [ ] **Asked user about framework preference?**
-- [ ] **Chosen framework for THIS context?** (not just default)
-- [ ] **Decided async vs sync?**
-- [ ] **Planned type hint strategy?**
-- [ ] **Defined project structure?**
-- [ ] **Planned error handling?**
-- [ ] **Considered background tasks?**
-
----
-
-## 11. Anti-Patterns to Avoid
-
-### ❌ DON'T:
-- Default to Django for simple APIs (FastAPI may be better)
-- Use sync libraries in async code
-- Skip type hints for public APIs
-- Put business logic in routes/views
-- Ignore N+1 queries
-- Mix async and sync carelessly
-
-### ✅ DO:
-- Choose framework based on context
-- Ask about async requirements
-- Use Pydantic for validation
-- Separate concerns (routes → services → repos)
-- Test critical paths
-
----
-
-> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.