| 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
- If no project slug provided, derive from git repo name.
- If
~/.ba-kit/projects/{slug}/learnings.jsonl doesn't exist, create it on first write.
- 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.
