From beads-compound
Captures verified solutions to non-trivial coding problems as searchable JSONL entries in .beads/memory/knowledge.jsonl for auto-recall in future sessions. Auto-invokes after 'that worked' or similar.
npx claudepluginhub roberto-mello/lavraThis skill is limited to using the following tools:
**Purpose:** Capture solved problems as structured JSONL entries in `.beads/memory/knowledge.jsonl` and as bead comments, building a searchable knowledge base that auto-recall injects into future sessions.
Captures verified solutions to coding problems as JSONL knowledge entries in .lavra/memory for searchable auto-recall in future sessions. Triggers on phrases like 'that worked' or 'fixed'.
Extracts patterns, quirks, and decisions from conversations; persists to Markdown files in knowledge/learnings/. Use /learn for quick or /learn --deep for thorough analysis.
Captures patterns, decisions, gotchas, procedures, and feature knowledge from conversations into durable skills for on-demand reuse. Invoked via /learn or 'please remember'.
Share bugs, ideas, or general feedback.
Purpose: Capture solved problems as structured JSONL entries in .beads/memory/knowledge.jsonl and as bead comments, building a searchable knowledge base that auto-recall injects into future sessions.
This skill captures problem solutions immediately after confirmation, creating structured knowledge entries that:
.beads/memory/knowledge.jsonl for auto-recall searchOrganization: Append-only JSONL file. Each solved problem produces one or more knowledge entries. The auto-recall hook (auto-recall.sh) searches these entries by keyword and injects relevant ones at session start.
<critical_sequence name="knowledge-capture" enforce_order="strict">
Auto-invoke after phrases:
OR manual invocation.
Non-trivial problems only:
Skip for:
Extract from conversation history:
Required information:
BLOCKING REQUIREMENT: If critical context is missing (area, exact error, or resolution steps), ask user and WAIT for response before proceeding to Step 3:
I need a few details to document this properly:
1. Which area/module had this issue?
2. What was the exact error message or symptom?
3. What fixed it?
[Continue after user provides details]
### Step 3: Check Existing Knowledge
Search knowledge.jsonl for similar issues:
# Search by error message keywords
grep "exact error phrase" .beads/memory/knowledge.jsonl
# Search using recall script if available
.beads/memory/recall.sh "keyword1 keyword2"
IF similar knowledge found:
Present decision options:
Found similar knowledge entry:
[key]: [content summary]
What's next?
1. Create new entries anyway (recommended if different root cause)
2. Skip (this is a duplicate)
3. Create new entries with cross-reference
Choose (1-3): _
WAIT for user response.
ELSE (no similar knowledge found):
Proceed directly to Step 4.
### Step 4: Determine Knowledge TypeClassify the solution into one or more knowledge prefixes:
| Prefix | Use When | Example |
|---|---|---|
| LEARNED | Discovered something non-obvious through debugging | "LEARNED: OAuth redirect URI must match exactly including trailing slash" |
| DECISION | Made an architectural or implementation choice | "DECISION: Use connection pooling instead of per-request connections because..." |
| FACT | Confirmed a factual constraint or requirement | "FACT: PostgreSQL JSONB columns require explicit casting for array operations" |
| PATTERN | Identified a recurring pattern (good or bad) | "PATTERN: Always check for nil before accessing nested hash keys in API responses" |
| INVESTIGATION | Documented an investigation path for future reference | "INVESTIGATION: Debugged memory leak - profiler showed retained objects from..." |
Most solved problems produce 1-3 entries. A complex debugging session might produce:
CRITICAL: All knowledge entries must conform to the JSONL schema.
<validation_gate name="jsonl-schema" blocking="true">
Required fields for each entry:
{
"key": "lowercase-hyphen-separated-unique-key",
"type": "learned|decision|fact|pattern|investigation",
"content": "Clear, specific description of the knowledge",
"source": "user|agent|subagent",
"tags": ["tag1", "tag2"],
"ts": 1706918400,
"bead": "BD-001"
}
Validation rules:
learned-oauth-redirect-must-match-exactly)learned, decision, fact, pattern, investigationuser, agent, or subagentAuto-tagging: Extract keywords from content matching known domains:
BLOCK if validation fails:
JSONL validation failed:
Errors:
- key: must be lowercase-hyphen-separated, got "MyKey"
- type: must be one of [learned, decision, fact, pattern, investigation], got "bug"
- content: too vague - must be specific and searchable
Please provide corrected values.
GATE ENFORCEMENT: Do NOT proceed to Step 6 until all entries pass validation.
</validation_gate>
### Step 6: Write Knowledge EntriesAppend entries to knowledge.jsonl:
# Append each validated entry as a single JSON line
echo '{"key":"learned-oauth-redirect-must-match","type":"learned","content":"OAuth redirect URI must match exactly including trailing slash","source":"agent","tags":["auth","oauth","security"],"ts":1706918400,"bead":"BD-001"}' >> .beads/memory/knowledge.jsonl
Log as bead comments (if bead ID available):
For each knowledge entry, also log it as a bead comment using the appropriate prefix:
bd comments add BD-001 "LEARNED: OAuth redirect URI must match exactly including trailing slash"
bd comments add BD-001 "PATTERN: Always verify OAuth redirect URIs match exactly, including protocol and trailing slash"
Handle rotation: If knowledge.jsonl exceeds 1000 lines after appending:
knowledge.archive.jsonlknowledge.jsonlLINE_COUNT=$(wc -l < .beads/memory/knowledge.jsonl)
if [ "$LINE_COUNT" -gt 1000 ]; then
head -500 .beads/memory/knowledge.jsonl >> .beads/memory/knowledge.archive.jsonl
tail -n +501 .beads/memory/knowledge.jsonl > .beads/memory/knowledge.jsonl.tmp
mv .beads/memory/knowledge.jsonl.tmp .beads/memory/knowledge.jsonl
fi
### Step 7: Cross-Reference & Pattern Detection
If similar knowledge found in Step 3:
Add cross-reference tag:
Include the key of the related entry in the tags array (e.g., "tags": ["auth", "see-also:learned-oauth-token-expiry"]).
Detect recurring patterns:
If 3+ entries share the same tags or describe similar issues, suggest creating a PATTERN entry that synthesizes the recurring theme:
Detected recurring pattern: 3 entries related to "auth" + "redirect"
Suggest creating a PATTERN entry?
1. Yes - create synthesized pattern entry
2. No - entries are distinct enough
Choose (1-2): _
</critical_sequence>
<decision_gate name="post-capture" wait_for_user="true">
After successful knowledge capture, present options and WAIT for user response:
Knowledge captured successfully.
Entries added:
- [key1]: [content summary]
- [key2]: [content summary]
Bead comments logged: [Yes/No - BD-XXX]
What's next?
1. Continue workflow (recommended)
2. View captured entries
3. Search related knowledge
4. Add more entries for this solution
5. Other
Handle responses:
Option 1: Continue workflow
Option 2: View captured entries
Option 3: Search related knowledge
Option 4: Add more entries
Option 5: Other
</decision_gate>
<integration_protocol>
Invoked by:
/beads-work and /beads-review workflowsWorks with:
auto-recall.sh hook reads from knowledge.jsonl at session startmemory-capture.sh hook captures knowledge from bd comments add commandsrecall.sh script provides manual searchData flow:
.beads/memory/knowledge.jsonlbd comments add (which triggers memory-capture.sh)auto-recall.sh searches knowledge.jsonl and injects relevant entries</integration_protocol>
<success_criteria>
Knowledge capture is successful when ALL of the following are true:
.beads/memory/knowledge.jsonlbd comments add (if bead ID available)</success_criteria>
Missing context:
JSONL validation failure:
Missing bead ID:
bd comments add stepKnowledge.jsonl doesn't exist:
touch .beads/memory/knowledge.jsonlMUST do:
bd comments add with knowledge prefixes when bead ID is availableMUST NOT do:
Good knowledge entries have:
Avoid:
User: "That worked! The N+1 query is fixed."
Skill activates:
.includes(:items) on Order model{"key":"learned-n-plus-one-order-items-eager-load","type":"learned","content":"Order listing N+1 query fixed by adding .includes(:items) to Order model scope. Missing eager loading caused separate DB query per order item, taking >5 seconds for 100+ orders.","source":"agent","tags":["database","performance","n-plus-one","eager-loading"],"ts":1706918400,"bead":"BD-042"}
{"key":"pattern-always-check-eager-loading-on-associations","type":"pattern","content":"When listing parent records that display child data, always use .includes() for associations. Check with bullet gem or query logs. Without eager loading, N records = N+1 queries.","source":"agent","tags":["database","performance","n-plus-one","eager-loading","prevention"],"ts":1706918401,"bead":"BD-042"}
Valid..beads/memory/knowledge.jsonlbd comments add BD-042 "LEARNED: Order listing N+1 query fixed by adding .includes(:items). Missing eager loading caused separate DB query per order item."
bd comments add BD-042 "PATTERN: When listing parent records that display child data, always use .includes() for associations. Check with bullet gem or query logs."
Output:
Knowledge captured successfully.
Entries added:
- learned-n-plus-one-order-items-eager-load: Order listing N+1 query fixed by adding .includes(:items)...
- pattern-always-check-eager-loading-on-associations: When listing parent records...
Bead comments logged: Yes - BD-042
What's next?
1. Continue workflow (recommended)
2. View captured entries
3. Search related knowledge
4. Add more entries for this solution
5. Other