// Capture lessons from an incident or debugging session as a structured intel YAML under tools/lopi/intel/. Operator-triggered after a problem that was harder to resolve than it should have been.
| name | lopi-learn |
| description | Capture lessons from an incident or debugging session as a structured intel YAML under tools/lopi/intel/. Operator-triggered after a problem that was harder to resolve than it should have been. |
After resolving a problem, capture a durable lesson so the next agent (or human) hitting the same symptoms finds the answer in one search. Intel is consumed at recall time on a search hit, so every byte costs context — keep entries lean and recall-focused.
Before classifying anything, extract from the conversation:
Everything below is anchored in that scan. Don't ask the operator to re-explain — they triggered /lopi-learn because the session already has the signal.
Pick a type using the conversation signal column:
| Type | Description | Signal in the session |
|---|---|---|
missing-check | lopi should have surfaced this automatically | lopi troubleshoot returned all-clear but the problem existed |
blind-spot | lopi had no visibility into the component | Needed raw docker logs / journalctl / SSH to find the issue |
missing-command | Diagnosis required a sequence lopi doesn't wrap | Raw shell commands lopi doesn't expose were used to diagnose or fix |
wrong-diagnosis | lopi pointed at the wrong thing | Operator corrected lopi's output mid-session |
insufficient-context | lopi couldn't correlate clues across sources | Multiple back-and-forth attempts before the pattern was visible |
missing-env-knowledge | Host/runtime config was the issue | .env or host config was inspected manually after lopi env |
critical — data loss, safety risk, or complete system failurehigh — service down, mission-blocking, requires immediate manual interventionmedium — degraded functionality, workaround exists but wastes timelow — minor inconvenience, cosmetic, or rare edge caselopi intel search <keywords> --json --include-fixed. If a match exists, don't create a new file — append a sighting with lopi intel encounter <slug> --context "...". Stop here.
Answer from the session you just lived through — don't ask the operator. The operator's input comes at the review step below.
Could a check have caught this automatically? (lead with this — the win is making the gotcha auto-detectable, not just documented)
→ fills gap (prose, what was missing) and suggested_improvements (concrete proposals). Consider, in order of cheapness:
lopi troubleshoot check — should the tool catch this on its next run?Skip any axis that doesn't apply. Don't write filler. Name files/paths where the change should land when you can.
How would the agent recognize this next time?
→ fills symptoms (3–5 short bullet strings, the things you'd grep logs for) and trigger (one line: when does it occur).
What single check confirms it?
→ fills confirming_check (one command or short pipeline; the smoking gun).
What's the fix?
→ fills fix (prose, 1–3 sentences) and resolution_commands (the commands to run).
Is there a fix commit?
→ fills fix_commit (optional). Presence of a non-empty fix_commit is what marks intel as fixed — there is no separate status field. If a fix lands later, use lopi intel resolve <slug> --commit <sha>.
Target path: tools/lopi/intel/<slug>.yaml. Slug is lowercase-hyphenated and must match the filename.
slug: my-issue-slug
title: One-line summary
type: missing-check
severity: high
hit_count: 1
symptoms:
- "Service A logs 'connection refused' on startup"
- "docker compose ps shows B is restarting"
trigger: "Cold start when B not yet ready"
confirming_check: |
docker compose ps | grep service-b | grep -i restarting
fix: |
Restart with healthcheck dependency, or wait for B before A starts.
resolution_commands:
- "docker compose up -d --wait"
gap: |
No log identifies which dependency failed. Adding the target endpoint
to the connect-retry log would make this 30s to diagnose.
suggested_improvements:
- "Log retry target URL in connect-retry loop (src/client.rs)"
- "Add lopi troubleshoot dependencies check"
encounters:
- date: "YYYY-MM-DD"
context: "What was specific about this hit (env, version, host)."
Show the draft to the user.
Sanitize. Strip and replace:
<ip><redacted><hostname><url>the operator)Intel must be generic enough for anyone on the team.
Write the file.
Run lopi intel validate tools/lopi/intel/<slug>.yaml. Fix any reported errors and re-validate.
Tell the user to review the diff and commit. Never git commit yourself.
If the suggested_improvements point at concrete code changes (un-stubbing a module, adding a check, adding a log), surface them to the user as a separate suggestion — but don't implement in the same turn.