process-logs

# Process Error Logs

Automated workflow for processing error logs from `/admin/logs`.

## CRITICAL REQUIREMENTS

> **YOU MUST FOLLOW THESE RULES. NO EXCEPTIONS.**

### 1. BEADS IS MANDATORY

**EVERY error MUST have a Beads task.** No direct fixes without tracking.

```bash
# ALWAYS run this FIRST for each error:
bd create --type=bug --priority=<1-3> --title="Fix: <error_message>" --files "<relevant_files>"
bd update <task_id> --status=in_progress
```

### 2. TASK COMPLEXITY ROUTING

**Route tasks by complexity:**

| Complexity  | Examples                              | Action                   |
| ----------- | ------------------------------------- | ------------------------ |
| **Simple**  | Typo fix, single import, config value | Execute directly         |
| **Medium**  | Multi-file fix, migration, API change | **Delegate to subagent** |
| **Complex** | Architecture change, new feature      | Ask user first           |

**Subagent selection for MEDIUM tasks:**

- DB/migration → `database-architect`
- API/tRPC → `fullstack-nextjs-specialist`
- Types → `typescript-types-specialist`
- UI → `nextjs-ui-designer`

**Execute directly for SIMPLE tasks:**

- Single-line fix (typo, wrong value)
- Import path correction
- Config constant change
- Comment fix

### 3. CONTEXT7 IS MANDATORY

**ALWAYS query documentation before implementing:**

```
mcp__context7__resolve-library-id → mcp__context7__query-docs
```

### 4. BUG FIXING PRINCIPLES

> **This is PRODUCTION. Every bug matters.**

**Fix fundamentally, not superficially:**

- Find and fix the ROOT CAUSE, not just symptoms
- If error happens in function X but cause is in function Y → fix Y
- Don't add workarounds/hacks that mask the problem
- Ask: "Why did this happen?" until you reach the actual cause

**Never ignore errors:**

- Every error indicates a real problem
- "Works most of the time" is NOT acceptable
- External service errors → add retry logic or graceful degradation
- Config warnings → fix config or make truly optional

**Propose improvements:**

- If you see code that could be better → create separate Beads task
- If fix reveals related issues → document them
- If pattern repeats → suggest refactoring to prevent future bugs
- Format: `bd create --type=chore --title="Improve: <description>"`

**Quality over speed:**

- Take time to understand the full context
- Test the fix mentally: "What else could break?"
- Check for similar patterns elsewhere in codebase
- One good fix > multiple quick patches

### 5. LOG NOTES (MANDATORY)

**Always write notes when updating log status.** Keep it brief, in English.

| Status        | What to write in notes                                                                           |
| ------------- | ------------------------------------------------------------------------------------------------ |
| `resolved`    | Root cause + fix applied. Example: `Missing constraint. Added 'approved' to enum via migration.` |
| `auto_muted`  | **System-assigned.** Don't change. Skip these errors in processing.                              |
| `ignored`     | **Never use.** Fix or ask user.                                                                  |
| `to_verify`   | Why pending + what to check. Example: `External API timeout. Monitor for 24h.`                   |
| `in_progress` | Beads task ID. Example: `Working on mc2-5ch`                                                     |

**Format:** `<root_cause>. <action_taken>.` — Max 100 chars.

**Examples:**

- `ESM import conflict. Renamed generator.ts to generator-node.ts.`
- `Constraint missing 'approved'. Added via migration 20250115_fix_status.`
- `Cloudflare 500. External issue, retry logic already exists. Monitoring.`

### 6. AUTO-MUTED ERRORS

Some errors are **automatically ignored** by the system with status `auto_muted`. These are expected events, NOT bugs.

**Current auto-mute rules** (from `src/shared/logger/auto-classification.ts`):

| Pattern                            | Reason            | Description                                |
| ---------------------------------- | ----------------- | ------------------------------------------ |
| `Redis connection (ended\|closed)` | graceful_shutdown | Redis disconnects during app restart       |
| `graceful.*shutdown`               | graceful_shutdown | Server shutdown events during deploys      |
| `/api/trpc/health.*404`            | monitoring_probe  | tRPC health endpoint probes (Uptime Kuma)  |
| `/health.*404`                     | monitoring_probe  | Generic health check probes                |
| `Cloudflare.*5\d{2}`               | external_service  | Cloudflare edge errors (502, 503, 521)     |
| `ECONNRESET.*external`             | external_service  | External API connection resets             |
| `Layer failed, trying next`        | cascading_repair  | Repair layer failed, trying next layer     |
| `Critique-revise attempt failed`   | cascading_repair  | Layer 2 retry attempt failed               |
| `Zod.*validation failed.*Layer`    | cascading_repair  | Layer 1 validation failed, escalating      |
| `Job stalled`                      | job_lifecycle     | BullMQ job restarted (long LLM operations) |
| `Unexpected exit code: 10`         | job_lifecycle     | Worker TTL timeout (10 min), will retry    |
| `No RAG chunks found`              | expected_behavior | Course without docs, generates w/o RAG     |
| `Mermaid.*fallback.*used`          | graceful_fallback | Diagram gen failed, fallback to text       |

**Total rules: 29** (test validates sync with code)

**When you see `auto_muted` errors:**

- Skip them in processing — they don't need fixes
- If you see a pattern that should be auto-muted, add it to `auto-classification.ts`

**How to add a new auto-mute rule:**

1. Edit `packages/course-gen-platform/src/shared/logger/auto-classification.ts`:

   ```typescript
   {
     pattern: /your-pattern/i,
     reason: 'category',  // graceful_shutdown | monitoring_probe | external_service