---
name: stellaris-logs
description: "Turn Stellaris logs into deterministic fixes."
---

## OBJECTIVE

**THE FORENSIC ENGINEER**: Turn Stellaris logs into deterministic fixes (syntax, missing keys, wrong scopes, broken localisation).

## PROTOCOL

### Phase 1: Acquire Evidence (Read Only)

Ask user for:

1. `error.log` (required)
2. `game.log` (optional)
3. Mod root path (to map errors back to `src/`)
4. Stellaris user dir (usually `~/Documents/Paradox Interactive/Stellaris/`)

### Phase 2: Triage (Fast Classification)

Classify each error line into one bucket:

| Bucket | Typical Log Clue | Usual Cause |
|--------|-------------------|-------------|
| **Parse/Syntax** | `Unexpected token` / `Malformed token` | `{}` imbalance, stray `=`, wrong nesting |
| **Unknown Trigger/Effect** | `Unknown trigger` / `Unknown effect` | typos, wrong scope, version mismatch |
| **Missing Localisation** | Key shows raw (`[NS]_foo`) | missing key, wrong file header, missing BOM |
| **Duplicate Keys** | `Duplicate key` | multiple defs loaded, soft override collision |
| **Missing Asset** | `Could not find texture` / `GFX_...` | `.gfx` not registered, wrong path/case |

### Phase 3: Pinpoint (Map to Victim File)

1. Use the file path/line references in logs when present.
2. If logs are vague, search the mod repo for:
    - the failing key (`[NS]_...`)
    - the failing id (`[NS].###`)
    - the missing asset name (`GFX_[NS]_...`)

### Phase 4: Fix Patterns

1. **Missing localisation**:
    - Ensure `.yml` is UTF-8 with BOM.
    - Ensure header is correct (`l_english:` etc).
    - Add the missing key with `:0`.
2. **Unknown trigger/effect**:
    - Verify scope (country/planet/system/ship) and move logic if needed.
    - Cross-check `ref/syntax_docs` (if present) before inventing syntax.
3. **Parse errors**:
    - Bracket-balance first. Then check for smart quotes.

## OUTPUT FORMAT

```markdown
## 🔎 STELLARIS LOG REPORT

### Evidence
- `error.log`: [provided]
- `game.log`: [provided / missing]

### Findings
- 🔴 [Error line] → Victim: `src/...` → Fix: [one sentence]
- 🟡 [Warning line] → Victim: `src/...` → Fix: [one sentence]

### Next Run
- Re-launch game with only this mod enabled.
- Re-check `error.log` for regressions.
```

## EXECUTION RULES

1. **Don’t edit logs**. Fix mod files.
2. **One fix loop**: apply smallest fix → re-run → re-check `error.log`.
3. **No Syntax Guessing**: Vanilla > `ref/syntax_docs` > web > hallucination.