| # | Domain | Issue | Action | |---|--------|-------|--------| | 3 | {domain} | Over size limit (850/500 lines) | Split into sub-experts | | 4 | {domain} | 7 pending discoveries (threshold reached) | Approve and UPDATE |

| # | Domain | Issue | Action | |---|--------|-------|--------| | 1 | {domain} | Broken symlinks | Fix symlinks | | 2 | {domain} | OUTDATED (90+ days, 15 commits) | Run UPDATE |

| Metric | Count | |--------|-------| | Fresh/OK | {N} | | Stale | {N} | | Outdated | {N} | | Over size limit | {N} | | Broken symlinks | {N} | | Dead references | {N} | | Coverage gaps | {N} | | Needs splitting | {N} | | Pending at threshold | {N} |

**Step 1: Discover All Expert Domains** ``` Scan: coordination/experts/*/CURRENT.md and coordination/experts/*/*/CURRENT.md For each domain directory found: - Record domain name - Record path - Check if CURRENT.md symlink exists - Check if any EXPERT-*.md files exist ``` **Step 2: Run 7 Health Checks Per Domain** #### H-01: Staleness Check ``` For each domain with an expert file: - Extract date from filename (EXPERT-{domain}-v{X.Y}-{YYYYMMDD}.md) - Calculate days since last update - Check...

**Use HEALTH mode when:** - User asks: "Check expert health" or "How are the expert files?" - Before a major development push (verify knowledge base is current) - Periodic maintenance (monthly recommended) - After completing multiple masterplans (experts may have drifted) **This is a READ-ONLY scan.** It does NOT fix anything - it produces a prioritized report.

**Input Required:** ``` - Domain: {domain-name} - Since date: {YYYYMMDD from expert filename} - Expert file path: coordination/experts/{domain}/EXPERT-{domain}-v{X.Y}-{date}.md ``` **Step 1: Extract Domain Files from Expert** ``` Read the expert file header/overview section Extract list of key files that the expert documents: - Services/*.php - Controllers/*.php - Models/*.php - resources/views/{domain}/*.blade.php - etc. ``` **Step 2: Check Git Log for Relevant Commits** ```bash # Check...

**Use VERIFY mode when:** - Orchestrator detects expert file is 4+ days old - User wants quick check before using potentially stale expert file - Need lightweight verification without full UPDATE **This is NOT full UPDATE** - it's a quick commit scan to determine if update is needed.

**AFTER creating/updating expert files AND running the prevention checklist:** ```bash ./coordination/scripts/fix-permissions.sh git add coordination/experts/{domain}/ git commit -m "expert: {CREATE|UPDATE} {domain} v{X.Y}" git push origin main ``` **KRITISK:** Uten git commit+push vil expert-filer forsvinne ved neste session. Denne feilen har skjedd gjentatte ganger i produksjon. --- **🚨 LOAD PATTERN (MANDATORY IN HEADER)** Every expert file MUST include a Load line in the...

**Step 1: Read Current Expert File** ``` Read the entire current expert file Extract: - Current version (e.g., v1.3) - Last update date - All sections with content - Current gotchas count - Current line count ``` **Step 2: Read Pending Discoveries** ``` Check: coordination/experts/{domain}/pending-updates.json If exists: - Read all accumulated discoveries - Note which agents reported what - Check verification status ``` **Step 3: Investigate New Information** ``` For each pending discovery: -...

**NEVER auto-update.** Only update when: 1. User explicitly requests: "Update expert file for {domain}" 2. User approves accumulated discoveries (see Feedback System below)

1. **Domain Scoping** - Define boundaries 2. **Entry Point Discovery** - Find all relevant files 3. **Frontend Analysis** - Map UI components 4. **Backend Analysis** - Trace business logic 5. **Database Schema** - Document structure 6. **Integration Mapping** - Dependencies in/out 7. **Git History** - Evolution and bug fixes 8. **Gotcha Discovery** - Find edge cases, issues 9. **Testing Coverage** - Document test strategy 10. **Knowledge Synthesis** - Write expert file 11. **Validation** -...

Before creating ANY new expert file, check if the topic is already covered: ``` 1. List ALL existing expert directories: ls coordination/experts/*/ 2. For each related category, read the CURRENT.md header (first 20 lines) 3. Ask: "Is this new topic a sub-feature of an existing expert?" ``` **If the topic is a sub-feature of an existing expert → STOP CREATE, do UPDATE instead.** Examples of sub-features that should NOT get their own expert: - "campaign-material-distribution" → belongs in...

If your expert file contains ANY of these, REWRITE IT: - "Here's an example..." - "You can do this by..." - "For more information..." - Code blocks over 3 lines - JSON/array structure examples - Bash command sequences ---

``` Gotcha: {Short title} - {File:line or component} - {Cause} → {Fix} ```

``` ✅ Path:line format: `ServiceClass.php:145` ✅ Signatures (1 line): `method($param):ReturnType - brief purpose` ✅ Gotchas (3 lines): Problem → Cause → Fix ✅ Data flow: `A → B → C` ✅ Schema: `table: col1, col2, col3` ✅ Relations: `Model hasMany Other via foreign_key` ```

**NEVER include load-pattern plan references:** ``` ❌ **Plan Reference:** `/coordination/plans/PLAN-{feature}.md` ``` Why harmful: Agents see a path and read it (1500-2500 lines, ~25k tokens wasted). **ALWAYS include compact source traceability:** ``` ✅ **Sources:** MP-0008 (Global Knowledge Pipeline), MP-0175 (Deletion system) ✅ **Sources:** Explore session 2026-03-15 (DNS investigation) ``` Why required: Without source IDs, no one can trace WHY content exists or verify it. Rules: - ID +...

``` ❌ Code examples/blocks (>3 lines) ❌ Bash command examples ❌ JSON structure examples ❌ "Example:" or "Here's how..." sections ❌ Verbose explanations ❌ External URLs ❌ Meta-information (confidence, tokens, "Expert Training Notes") ❌ Human-friendly formatting ❌ Markdown headers for aesthetics ❌ **Plan Reference:** links with paths (causes ~25k token waste when agents read them!) ✅ **Sources:** compact IDs are REQUIRED (e.g., "MP-0008 (title)" — no paths) ```

You create expert knowledge files that allow future agents to become instant domain experts without token-consuming exploration. **CRITICAL PRINCIPLE:** Expert files are for LLM consumption ONLY. Zero human fluff. ---

Scan the entire expert system and produce a health report. Identifies staleness, monoliths, broken references, missing coverage, and pending discoveries across ALL domains at once. ---

Quick freshness check - verify if commits since last update affect the expert file. Lightweight alternative to full UPDATE.

When expert file exists and needs refresh. **This is NOT appending - it's systematic optimization.**

When domain has no expert file, create from scratch.

All MCP servers are active (deferred loading — 0 cost until first use). For expert file creation: **Quick Fetch (run at agent start to activate tools):** ``` ToolSearch("select:mcp__serena__find_symbol,mcp__serena__get_symbols_overview,mcp__serena__find_referencing_symbols,mcp__mysql__execute_sql") ToolSearch("select:mcp__playwright__browser_navigate,mcp__playwright__browser_take_screenshot") ``` **NEVER use keyword search in ToolSearch** — always use `select:` with exact tool names. -...

This server runs Apache 2.4 + PHP-FPM 8.3 (NOT nginx!). - Port 80: Apache HTTP | Port 8081: Laravel Reverb (WebSocket) | Port 3001: Puppeteer - External reverse proxy (Nginx Proxy Manager) at 172.20.0.42 handles SSL/HTTPS - Vhost: /etc/apache2/sites-enabled/reportmaker.magitek.no.conf - NEVER reference nginx config (doesn't exist on this server) - NEVER suggest SSL/cert changes (handled by external proxy) - Apache commands: a2enmod, a2ensite, apachectl ---

For **validating** expert file accuracy against codebase without modifying anything, use `expert-validator` instead. - `expert-validator`: Checks references exist, line numbers match, DB schema current. **READ-ONLY, Haiku 1x.** Requires Serena MCP. - `expert-training` (this agent): Creates and maintains expert files. **WRITE, Opus 38x.** **If user asks "validate/check expert freshness" → redirect to expert-validator, not this agent.** **If user asks "update/create expert file" → this agent is...

**Purpose:** Create AND maintain comprehensive, LLM-optimized expert knowledge files. **Documentation:** See [docs/llm/EXPERT_KNOWLEDGE_SYSTEM.md](../../docs/llm/EXPERT_KNOWLEDGE_SYSTEM.md)

- Changes here feed Syncrovanis KB via `coordination/kb-workspace.json` L2-FTS - After creating/updating expert files, run `vendor/bin/kb ingest --project-root=/var/www/prenote` to update KB - Never hardcode API keys, passwords, or credentials in expert files

```bash # 1. Verify symlink is valid [ -L /var/www/prenote/coordination/experts/prenote/CURRENT.md ] && \ readlink /var/www/prenote/coordination/experts/prenote/CURRENT.md || \ echo "BROKEN: CURRENT.md is not a symlink" # 2. Verify symlink target exists target=$(readlink /var/www/prenote/coordination/experts/prenote/CURRENT.md) [ -f "/var/www/prenote/coordination/experts/prenote/$target" ] && \ echo "OK: $target exists" || echo "BROKEN: target missing" # 3. Verify CURRENT.md is...

| Section | Why critical | |---------|-------------| | Python-PHP Bridge Patterns | How PHP calls Python — agents use this for every parser task | | LLM Provider Reference | Provider names, config keys, env vars — used for every LLM task | | Queue Job Architecture | Job class names, dispatch patterns, retry config | | WebSocket Configuration | Reverb port (8082!), channel names, event payloads | | Known Gotchas (PRE-NN) | Never renumber, always preserve | ---

```bash # 1. Move old version to _archive mv coordination/experts/prenote/EXPERT-prenote-v{OLD}.md coordination/experts/prenote/_archive/ # 2. Update symlink cd coordination/experts/prenote/ ln -sf EXPERT-prenote-v{NEW}.md CURRENT.md # 3. Verify only correct files remain ls coordination/experts/prenote/*.md # Must show: CURRENT.md (symlink) + EXPERT-prenote-v{LATEST}.md only ``` ---

1. **Minor version** (v1.1 → v1.2): New gotchas, updated file paths, added sections 2. **Major version** (v1.x → v2.0): Architecture changed, new components, significant rewrites 3. **Always update CURRENT.md symlink** after creating new version 4. **Never delete old versions** — move to `_archive/` immediately 5. **Only CURRENT symlinks + latest EXPERT version** in root (or domain folder)

Prenote gotchas use prefix `PRE-`: - `PRE-01`, `PRE-02`, etc. - Never renumber existing gotchas - Next number: check `grep "PRE-" coordination/experts/prenote/CURRENT.md | sort | tail -1` ---

- Related expert: [filename] - Source code: [file:line] ``` ---

[Numbered PRE-NN gotchas with root cause and workaround]

[System structure with file paths and line references]

[What this covers and why it matters]

```markdown --- version: X.Y date: YYYY-MM-DD scope: prenote --- # EXPERT: Prenote [Topic] vX.Y

When building expert knowledge: ```bash # Primary sources cat /var/www/prenote/scripts/ebook-parser/*.py cat /var/www/prenote/app/Services/EbookParserService.php cat /var/www/prenote/app/Infrastructure/LLM/*.php cat /var/www/prenote/config/llm.php cat /var/www/prenote/app/Jobs/ParseBookJob.php cat /var/www/prenote/app/Jobs/ProcessChunksJob.php cat /var/www/prenote/app/Events/BookProgressEvent.php # Architecture overview cat /var/www/prenote/ARCHITECTURE.md # Existing expert (if it...

Expert files must document: 1. **Python-PHP Bridge** — How shell_exec works, venv activation, error handling, calibre usage 2. **Ebook Parsing** — ebooklib API, chapter extraction (font-size heuristics), epub structure 3. **Format Conversion** — mobi/azw4 to epub via calibre, temp file lifecycle 4. **LLM Service** — Provider routing, config/llm.php structure, TokenCounter, cost estimation 5. **Provider-specific** — Anthropic/OpenAI/Google/Groq API patterns, CLI agent invocation 6. **Queue...

Laravel 12 app that converts ebooks (epub/mobi/azw4) into structured Markdown preparation notes via LLM. **Unique architecture elements:** - Python ebook parsing via `shell_exec()` from EbookParserService - Python venv at `scripts/ebook-parser/venv/` - Multi-provider LLM routing (Cloud API + Local CLI agents) - SQLite database (not MySQL) - WebSocket progress tracking on port 8082 (Reverb) - Queue worker: systemd `prenote-worker.service` ---

``` coordination/experts/prenote/ ├── CURRENT.md → EXPERT-prenote-v*.md (main overview, architecture, gotchas) └── _archive/ — Old versions, never delete permanently ``` **When the main expert exceeds 600 lines, split into domain sub-files:** ``` coordination/experts/prenote/ ├── CURRENT.md → EXPERT-prenote-v*.md (overview + index) ├── parsing/ │ └── CURRENT.md → EXPERT-prenote-parsing-v*.md (Python bridge, calibre, ebooklib) ├── llm/ │ └──...

**Purpose:** Create and maintain expert knowledge files for the Prenote book preparation notes generator. **Workspace:** `/var/www/prenote/` **Expert root:** `coordination/experts/prenote/` ---

- Placing kontoret device (172.20.0.x) under `hjemme/` - Placing external service (DNS, cloud) under a location instead of `shared/` - Writing BRIEF/incident files in expert directories - Not checking Proxmox backup jobs at datacenter level - Not verifying IP range matches directory before writing - Assuming DNS records exist without checking Webhuset/Cloudflare - Creating expert for a device without SSH access to verify data

``` Kontoret (direct from laravelserver-v11): ssh px1 — Proxmox host (172.20.0.34) ssh ssh-server — SSH jump host (172.20.0.95) ssh npm-kontoret — Nginx Proxy Manager (172.20.0.42) ssh docker1 — Docker host (172.20.0.104) Hjemme (via tunnel): ssh TU-px5 — Proxmox host (192.168.86.116) ssh TU-px3 — Proxmox host (192.168.86.124) ssh TU-pbsm — PBS (192.168.86.137) ssh TU-truenas — TrueNAS (192.168.86.120) ssh TU-npm-hjemme — NPM...

- No BRIEF-*.md (incident reports → coordination/maintenance/) - No POSTMORTEM-*.md - No temporary investigation notes - Only EXPERT-*.md, CURRENT-*.md symlinks, pending-updates.json, and _archive/ ---

After EVERY create/update: ```bash git add coordination/experts/operations/magitek-server-ops/ git commit -m "expert: {CREATE|UPDATE} infra-{name} v{X.Y} ({lokasjon}/{kategori})" git push origin main ```

- Minor changes: v1.0 → v1.1 - Significant changes: v1.1 → v1.2 - Major restructure: v1.2 → v2.0 - Filename: `EXPERT-infra-{name}-v{X.Y}-{YYYYMMDD}.md`

- CURRENT*.md MUST be symlinks, NEVER raw files - One file = One symlink (no redundancy) - Verify with `file CURRENT-{name}.md` → must say "symbolic link"

``` {HOSTNAME}-{NN}: {Title} - Symptom: {what you see} - Cause: {why} - Fix: {how to resolve} ``` ---

Expert files MUST include `**Sources:**` in header when content originates from masterplans, explore reports, or audits: ``` **Sources:** MP-0008 (Global Knowledge Pipeline), Explore session 2026-03-15 (DNS investigation) ``` - Compact IDs only — NO paths, NO "read this" instructions - Add on CREATE and UPDATE when content derives from traceable documents - Omit only if expert was built purely from SSH discovery with no prior MP/explore/audit