seed-lessons

name	seed-lessons
description	Seed ai/lessons/ from archive. Reads every BUG spec, understands the bug, writes structured lessons. Triggers on: seed lessons, засей уроки, заполни банк уроков, populate lessons bank.

Seed Lessons

Read every BUG spec from ai/archive/ (or ai/features/ if no archive), understand what went wrong, and write structured lessons to ai/lessons/.

You ARE the LLM. Read each file with understanding — not keyword matching.

---

Taxonomy (root_cause_class)

Class	When to use
money-precision	Wrong type/unit for money — float, rub instead of int kopecks
race-condition	Two concurrent writes hit the same row without locking
ssot-violation	Same data in two places that diverged
migration-drift	DB schema and code out of sync
atomicity	Multi-step operation left data half-written
idempotency	Retry/replay caused double write/charge
boolean-trap	bool field couldn't represent all states needed
fsm-deadlock	State machine stuck or made illegal transition
cross-layer-import	Import direction violated (domain→api, circular)
pydantic-coercion	Pydantic silently coerced wrong type
case-mismatch	snake_case vs camelCase mismatch between DB and code
null-safety	Missing None check crashed at runtime

If nothing fits → general.

---

Protocol

Step 1: Find files

ls ai/archive/*.md 2>/dev/null | grep -i "BUG-" | wc -l
# If 0: try ai/features/
ls ai/features/*.md 2>/dev/null | grep -i "BUG-" | wc -l

Report: "Found N BUG files in {dir}. Starting."

Step 2: For each BUG file — Read → Understand → Write

Read the full file. Title alone is not enough.

After reading, determine:

• domain — billing / campaigns / buyer / seller / llm / db / security / api / storage / general
• root_cause_class — from taxonomy above (read the WHOLE spec to decide)
• prevention_rule — one concrete sentence: what should be done differently. Extract from the spec's resolution/fix section if present, otherwise write from understanding.
• severity — critical (data loss, money, security) / high (user-facing breakage) / medium (edge case)
• keywords — 3-6 specific terms from this bug (not the taxonomy class name)

Next L-ID:

ls ai/lessons/{domain}/ 2>/dev/null | grep -oE "L-[0-9]+" | sort -t- -k2 -n | tail -1
# Increment + zero-pad to 3 digits

Write ai/lessons/{domain}/L-{NNN}.md:

---
id: L-{NNN}
domain: {domain}
root_cause_class: {root_cause_class}
severity: {severity}
created: {YYYY-MM-DD}
occurrence_count: 1
related: [{BUG-ID}]
---

# {root_cause_class}: {short title from spec}

## Prevention Rule
{one concrete sentence}

## Context
{2-3 sentences: what broke, why, what fixed it}

## Keywords
{term1, term2, term3}

Create domain directory if missing.

Append to ai/lessons/index.jsonl:

{"id":"L-NNN","domain":"...","root_cause_class":"...","prevention_rule":"...","keywords":[...],"severity":"...","related":["BUG-ID"],"created":"YYYY-MM-DD","occurrence_count":1}

Log each lesson: [DONE] L-001 billing/money-precision ← BUG-350

Step 3: Deduplication

Before writing each lesson — check if BUG-ID already in index.jsonl:

grep -c "BUG-ID" ai/lessons/index.jsonl 2>/dev/null

If already present → skip with [SKIP] BUG-ID already indexed.

Step 4: Summary

Seeded: N lessons across M domains
Skipped: K (already indexed)
Domains: billing(N), campaigns(N), ...

---

Rules

• Read the FULL spec before classifying — title is often misleading
• prevention_rule must be actionable: "Use X instead of Y", not "Be careful with money"
• Context must explain WHY it broke, not just what broke
• If archive is large (>50 files): process in batches of 20, commit after each batch
• Never overwrite existing lessons — only append
• Commit after completion: git add ai/lessons/ && git commit -m "chore: seed lessons from archive"