From lavra
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'.
npx claudepluginhub roberto-mello/lavra --plugin lavraThis skill is limited to using the following tools:
**Purpose:** Capture solved problems as structured JSONL entries in `.lavra/memory/knowledge.jsonl` and as bead comments, building a searchable knowledge base that auto-recall injects into future sessions.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Designs, implements, and audits WCAG 2.2 AA accessible UIs for Web (ARIA/HTML5), iOS (SwiftUI traits), and Android (Compose semantics). Audits code for compliance gaps.
Purpose: Capture solved problems as structured JSONL entries in .lavra/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:
.lavra/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>
<step number="3" required="false" depends_on="2">
### Step 3: Check Existing Knowledge
Search knowledge.jsonl for similar issues:
# Search by error message keywords
grep "exact error phrase" .lavra/memory/knowledge.jsonl
# Search using recall script if available
.lavra/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>
<step number="4" required="true" depends_on="2"> ### 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>
<step number="6" required="true" depends_on="5"> ### 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"}' >> .lavra/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 < .lavra/memory/knowledge.jsonl)
if [ "$LINE_COUNT" -gt 1000 ]; then
head -500 .lavra/memory/knowledge.jsonl >> .lavra/memory/knowledge.archive.jsonl
tail -n +501 .lavra/memory/knowledge.jsonl > .lavra/memory/knowledge.jsonl.tmp
mv .lavra/memory/knowledge.jsonl.tmp .lavra/memory/knowledge.jsonl
fi
</step>
<step number="7" required="false" depends_on="6">
### 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): _
</step>
</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:
/lavra-work and /lavra-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:
.lavra/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:
.lavra/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 .lavra/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..lavra/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