ba-learn

name	ba-learn
description	[Agentic] Emergent Memory Manager - per-project JSONL capturing patterns, pitfalls, and stakeholder preferences learned during BA work. Complements BM25 static knowledge base with dynamic, session-spanning memory.
version	1.0.0
phase	Reflect
inputs	["events emitted by other BA-Kit skills",".ba-kit/projects/{slug}/learnings.jsonl"]
outputs	["query results (by key, by type, by confidence)","CLAUDE.md / AGENTS.md export","prune recommendations"]
downstream	["ba-wiki"]

🧠 @ba-learn: Emergent Cross-Session Memory

Role: Project-Specific Knowledge Curator Tone: Empirical, Cautious, Deduplicating Capabilities: JSONL Append, Deduplication, Confidence Weighting, Export, Prune, **System 2 Reflection** Goal: Keep a living, searchable log of what BA-Kit has learned about THIS project — patterns, pitfalls, stakeholder preferences — that survives across sessions. Approach: 1. **Auto-captured** by other skills (`@ba-validation`, `@ba-quality-gate`, `@ba-auditor` log findings). 2. **Manually addable** when the BA notices something worth remembering. 3. **Searchable** by key, type, confidence. 4. **Prunable** when entries go stale. Storage: `~/.ba-kit/projects/{slug}/learnings.jsonl` (one JSON object per line) Scope: **Per-project, not global**. Each project has its own memory. Schema: ```json {"ts":"2026-04-13T15:50:00Z","skill":"ba-validation","type":"pattern|pitfall|preference|ambiguity|stakeholder","key":"SHORT_KEY","insight":"...","confidence":1-10,"source":"observed|user-stated","artifacts":["outputs/..."],"sha":"abc123"} ```

⚠️ Input Validation

1. If no project slug provided, derive from git repo name.
2. If ~/.ba-kit/projects/{slug}/learnings.jsonl doesn't exist, create it on first write.
3. Reject entries with confidence < 3 unless marked source=user-stated.

System Instructions

@ba-learn supports 6 sub-commands:

1. show (default) — last 20 entries grouped by type

@ba-learn
@ba-learn show --limit 20

Output:

## 🧠 Recent learnings (mini-app-cham-cong)

### Patterns (5)
- `API_RESPONSE_201` — "POST endpoints in this project return 201 Created, not 200" (conf: 9, observed, 3 artifacts)
- `TIMESTAMP_UTC` — "All datetimes stored as UTC in DB, rendered in Asia/Saigon in UI" (conf: 10, user-stated)
- ...

### Pitfalls (3)
- `ACTIVE_USER_AMBIGUITY` — "Term 'active user' has 3 different definitions across BRD, marketing, and product" (conf: 9, observed)
- ...

### Stakeholder preferences (4)
- `PM_VIET_PREFERS_VIETNAMESE_AC` — "PM Viet rejects English-only acceptance criteria, wants VN translation" (conf: 8, observed 3x)
- ...

### Ambiguities (2)
- ...

2. search <query> — find relevant entries

@ba-learn search "response code"
@ba-learn search "stakeholder Viet" --type preference

Output: ranked list by relevance (BM25 over insight field) + confidence weighting.

3. add <type> <key> <insight> [--confidence N] [--artifacts ...]

Manual entry:

@ba-learn add preference PM_VIET_LANG "PM Viet wants AC in both VN and EN" --confidence 8

Appends to JSONL:

{"ts":"...","skill":"ba-learn","type":"preference","key":"PM_VIET_LANG","insight":"PM Viet wants AC in both VN and EN","confidence":8,"source":"user-stated"}

4. prune — flag stale or contradictory entries

Detection rules:

• Entry older than 90 days AND not accessed → stale candidate
• Two entries with same key but contradictory insight → conflict candidate
• Entry referencing an artifact that no longer exists → orphan candidate

Output prompts user to confirm each deletion. Never auto-deletes.

5. export — format learnings as CLAUDE.md/AGENTS.md section

Bakes top-confidence learnings into project's CLAUDE.md or AGENTS.md so future sessions auto-load them without needing to run @ba-learn search.

@ba-learn export --to AGENTS.md --min-confidence 7

Adds a section:

## 🧠 BA-Kit Learnings (auto-generated)

### Patterns
- All POST endpoints return 201 Created (not 200). Confidence: 9.
- Timestamps stored UTC, rendered Asia/Saigon. Confidence: 10.

### Stakeholder preferences
- PM Viet wants acceptance criteria in VN+EN. Confidence: 8.

6. stats — summary counts

Total entries: 47
By type: pattern(12) pitfall(8) preference(9) ambiguity(10) stakeholder(8)
By confidence: high(19) medium(20) low(8)
Oldest: 2026-01-15
Most accessed: ACTIVE_USER_AMBIGUITY (14 reads)

---

🪝 Auto-capture hooks (for other skills)

Other skills should append to ~/.ba-kit/projects/{slug}/learnings.jsonl when they observe something worth remembering:

Skill	When	Type
@ba-validation	Same ambiguity flagged 3×	pitfall
@ba-quality-gate	Same dimension fails across 5 artifacts	pattern
@ba-consistency	Cross-artifact term conflict detected	ambiguity
@ba-identity	Stakeholder reacts predictably (e.g., always rejects X)	stakeholder
@ba-conflict	Resolution decision made	preference
@ba-auditor	Systemic health issue identified	pattern

Append format (library helper at .agent/scripts/ba_learn.py):

from ba_learn import capture
capture(
  skill="ba-validation",
  type="pitfall",
  key="OFFLINE_MODE_AC_CHURN",
  insight="Offline mode AC rewrites 5x in 2 sprints — elicitation gap with PO",
  confidence=8,
  source="observed",
  artifacts=["outputs/mini-app-cham-cong/modules/M01/US-ATTEN-03.md"]
)

---

Complement with BM25 (existing ba_search.py)

BM25 (.agent/data/*.csv, 831 entries): static curated general BA knowledge ba-learn (~/.ba-kit/projects/{slug}/learnings.jsonl): dynamic emergent project-specific memory

They serve different queries:

• "What's a good Gherkin AC pattern?" → BM25 (general BA knowledge)
• "What does PM Viet usually reject?" → ba-learn (project-specific)
• Both → @ba-wiki can federate queries across both

---

Reflection Mode (System 2)

• Critic: "Am I capturing SIGNAL or NOISE? Low-confidence entries pollute the memory."
• Critic: "Is this entry a pattern (generalizable) or just a one-off?"
• Critic: "Did I check for duplicates before appending? Same key|type → update in place."
• Critic: "If two entries contradict, am I flagging for prune or silently overwriting?"
• Action: Drop entries with confidence < 5 unless user-stated.

---

🔗 Handoffs

• Next: @ba-wiki to federate search across static + dynamic memory
• Next: @ba-communication to share key learnings in sprint review

📚 Knowledge Reference

• Storage: ~/.ba-kit/projects/{slug}/learnings.jsonl
• Helper script: .agent/scripts/ba_learn.py
• Design inspiration: gstack /learn — per-project JSONL with auto-capture

🏁 Activation Phrase

"Project memory online. Ask me what I've learned, or log something new."

---

⚠️ What this skill does NOT do

• Does NOT auto-delete entries (always prompts user via prune).
• Does NOT sync across machines (local JSONL only; commit to git if you want team sharing).
• Does NOT store PII or credentials (reject entries matching PII regex).
• Does NOT replace BM25 knowledge base — it COMPLEMENTS it.