# Learnings

Corrections, insights, and knowledge gaps captured during development.

**Categories**: correction | insight | knowledge_gap | best_practice
**Areas**: frontend | backend | infra | tests | docs | config
**Statuses**: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill

## Status Definitions

| Status | Meaning |
|--------|---------|
| `pending` | Not yet addressed |
| `in_progress` | Actively being worked on |
| `resolved` | Issue fixed or knowledge integrated |
| `wont_fix` | Decided not to address (reason in Resolution) |
| `promoted` | Elevated to CLAUDE.md, AGENTS.md, TOOLS.md, or SOUL.md |
| `promoted_to_skill` | Extracted as a reusable skill |

## Skill Extraction Fields

When a learning is promoted to a skill, add these fields:

```markdown
**Status**: promoted_to_skill
**Skill-Path**: skills/skill-name
```

---

## [LRN-20260126-001] best_practice

**Logged**: 2026-01-26T08:12:00+01:00
**Priority**: high
**Status**: promoted
**Promoted**: TOOLS.md, AGENTS.md
**Area**: config

### Summary
Proaktive Cron-Nachrichten an Telegram erfordern `sessionTarget: "isolated"` + `deliver: true`

### Details
Bei der Erstellung eines Cron-Jobs für morgendliche News wurde zunächst folgende Konfiguration verwendet:
```json
{
  "sessionTarget": "main",
  "payload": {
    "kind": "systemEvent",
    "text": "..."
  }
}
```

Das Problem: Der Job triggerte zwar die main Session, aber die Nachricht wurde **nicht proaktiv an Telegram gesendet**. Der User musste sich erst selbst melden.

**Korrekte Konfiguration für proaktive Nachrichten:**
```json
{
  "sessionTarget": "isolated",
  "wakeMode": "now",
  "payload": {
    "kind": "agentTurn",
    "message": "...",
    "deliver": true,
    "channel": "telegram",
    "to": "<telegram_user_id>"
  }
}
```

Wichtige Unterschiede:
- `sessionTarget: "isolated"` → eigene Session, nicht main
- `payload.kind: "agentTurn"` → nicht systemEvent
- `deliver: true` → aktiviert Zustellung
- `channel` + `to` → Ziel für die Nachricht

### Suggested Action
Bei zukünftigen proaktiven Cron-Jobs immer diese Struktur verwenden.

### Resolution
- **Resolved**: 2026-01-26T08:10:00+01:00
- **Promoted**: 2026-01-27T18:20:00+01:00
- **Notes**: Checkliste in TOOLS.md und Pre-Flight-Regel in AGENTS.md hinzugefügt

### Metadata
- Source: error + user_feedback
- Related Files: ~/.clawdbot/cron/jobs.json, ~/clawd/TOOLS.md, ~/clawd/AGENTS.md
- Tags: cron, telegram, proactive, deliver
- Docs: https://docs.clawd.bot/automation/cron-jobs

---