learning-capturer

Purpose

The same wall, twice. An error the user spent ninety minutes on in March shows up again in August and they start from zero, because the fix lived in a terminal scrollback that closed months ago.

Littlebird watched the whole first fight. This skill reads that capture, finds the moments where something broke and then stopped being broken, and turns each one into an entry in a personal knowledge base keyed on the thing the user will actually search for next time, which is the literal error text.

Two facts shape the design. Error message explanations are among the most frequent things developers search the web for [references/research/distilled-personal-knowledge-capture.md section 1], and search behavior has not declined despite AI assistants arriving [references/research/distilled-personal-knowledge-capture.md section 1]. So the retrieval key is the error string, and building a local searchable artifact is not fighting a dying habit.

The founding premise, that people re-debug problems they already solved, is a premise. No source in this skill's archive measures a re-finding rate [references/research/distilled-personal-knowledge-capture.md section 8]. Do not present it to the user as a research finding.

Mode: weekly routine that proposes, plus on-demand after a hard session. The routine never writes. The user confirms every entry.

---

Littlebird MCP calls used

Real tool names, verified 2026-08-17. List the tools available in this session and use what is actually there.

Tool	Used for
search_user_context	Every retrieval sweep. Error surfaces, the grind, resumption, message threads, activity summaries, and the historical recurrence check.
LB_INTERNAL_SEARCH_MEETINGS	A wall solved during a call or a pairing session, looked up BY TOPIC.
LB_INTERNAL_LIST_MEETINGS	A wall solved in a specific known meeting, looked up BY NAME.
LB_INTERNAL_GET_MEETING	The structured summary, for who supplied the fix. Attribution comes from Decisions and Action Items, never from raw transcript.
LB_INTERNAL_GET_MEETING_TRANSCRIPT	Only when the exact wording of a spoken fix is needed.
LB_INTERNAL_GET_ROUTINE_REPORTS	Reading past sweep reports so a rejected candidate stays rejected.
LB_INTERNAL_GET_ROUTINE_CONFIG	Before any routine update, because prompt replaces the whole prompt.
LB_INTERNAL_CREATE_ROUTINE	Offering to create the weekly sweep.
LB_INTERNAL_UPDATE_ROUTINE	Adding a permanently rejected fingerprint to the routine's do-not-propose list.
LB_INTERNAL_GET_SUBSCRIPTION_STATUS	Checking the plan gate and whether another routine can be created.

There is no Littlebird tool that searches past Littlebird chat conversations. Where this skill needs prior context it uses search_user_context.

---

Trigger

Fires on: "capture what I learned", "log this fix", "add that to my knowledge base", "what did I figure out this week", "I have solved this before", "stop re-debugging this", "write up how I fixed that", "did I hit this error before", "what have I been getting stuck on".

Also fires when the weekly sweep report lands and the user opens Cowork to work it.

Does not fire for: documenting a procedure that worked first time, which is sop-forge, or for general note-taking.

---

Capability gate

This skill requires the Littlebird MCP on a Power or Pro plan. Before anything else:

1. List the tools actually available in this session. Use the real names you find. The table above is verified as of 2026-08-17 and is a starting point, not a contract.
2. If no Littlebird tools are present, stop. Say the skill needs the Littlebird MCP connected and that it cannot reconstruct a solve from the user describing it, because the whole point is the detail they no longer remember.
3. If the plan gate is in doubt, check subscription status before promising a sweep.
4. If the user asks for the weekly routine, check the plan's routine limit first.

There is no degraded mode.

---

Do this first, every time

Read these two before you touch retrieval:

1. references/evidence-standards.md - the receipt format, the observed / inferred / external / unknown split, the attribution guardrail, the confirmation gates.
2. references/littlebird-mcp-reference.md - tool parameters, return shapes, and the limitations to design around.

Then references/solve-detection.md, which governs stages 2 and 3. The other guides load at the stage that needs them.

---

Routine cadence

Weekly. Friday 16:30 local, so the week is done and the report is waiting on Monday.

The routine observes and proposes. It does not write files, does not ask questions, and does not append to the knowledge base. Routines cannot do approvals or produce file deliverables (references/littlebird-mcp-reference.md, "Do not ask a routine to do work it cannot finish unattended in one pass"). The user opens Cowork and this skill does the rest.

The on-demand mode runs the same pipeline against a window the user names, usually "today" or "yesterday afternoon", right after a session that hurt.

---

Process

Stage	Guide	Output
1. Fix the window and load the base	this file, references/kb-structure-and-dedupe.md section 1	Window, existing entries, rejected.md, staleness flags
2. Six sweeps	Retrieval brief below, references/solve-detection.md sections 1 to 2	Raw retrieval, timestamp-sorted
3. Classify each candidate	references/solve-detection.md sections 3 to 5	Solved / abandoned / other-solved / ai-solved, with confidence
4. Scrub	references/secret-scrubbing.md	Scrubbed strings, typed placeholders, rotation flags
5. Dedupe	references/kb-structure-and-dedupe.md sections 3 to 5, scripts/kb_index.py --check	New / update / rejected-already, plus recurrence escalations
6. Draft	references/entry-schema.md	Draft entries and draft updates, nothing written
7. Confirm	AskUserQuestion	Approved, edited, or rejected, one by one
8. Write and index	references/kb-structure-and-dedupe.md sections 4, 6, 7	Files appended, rejected.md updated, INDEX.md rebuilt

Stage 4 runs before stage 5, so no unscrubbed string reaches a comparison or a report. Stage 4 never gets skipped, not on-demand, not when the user says the session was harmless.

Stage 7 never gets skipped either. See the guardrail.

---

Retrieval brief

The exact queries. Default window for the weekly routine: the last 7 days. For on-demand, the window the user names. Split anything longer than about two hours into sub-windows, because a single broad sweep exceeds the tool result limit and gets dumped to a file instead (references/littlebird-mcp-reference.md, "Oversized results"). Prefer several narrow parallel queries over one broad one (references/littlebird-mcp-reference.md, retrieval pattern 1).

Sweep A. Shape of the week. search_user_context, filters: {"data_source": "summaries"}, window fixed. Queries: ["troubleshooting or debugging session", "blocked on an error", "spent a long time on one problem"]. Cheapest compressed view of the period and it names the apps for Sweep B (references/littlebird-mcp-reference.md, retrieval pattern 3).

Sweep B. Error surfaces. filters: {"data_source": "snapshots"}, same window. Five narrow queries:

1. "terminal output with an error message or stack trace"
2. "red error banner or failed build output"
3. "exception or traceback in the editor"
4. "HTTP 4xx or 5xx response in browser devtools"
5. "database error, migration failure, or connection refused"

Sweep C. The grind. filters: {"data_source": "snapshots"}, same window:

1. "search engine results page for an error message"
2. "Stack Overflow question or GitHub issue page"
3. "documentation page for a library or framework"
4. "AI assistant chat panel containing code"
5. "config file, environment file, or lockfile being edited"

Query 4 is not optional. It is how the AI-assisted solve gets detected, which is the highest-value entry type this skill produces (references/solve-detection.md section 4).

Sweep D. Resumption. filters: {"data_source": "snapshots"}, window extended 24 hours past the sweep window, because a fix late on Friday shows its success state on Saturday:

1. "build succeeded or tests passing"
2. "deployment succeeded or server started listening"
3. "commit message or pull request describing a fix"

Sweep E. Human help. search_queries_messages with filters: {"data_source": "messages"}, same window: ["someone helping debug an error", "sharing a stack trace in a thread", "asking about an error message"]. Feeds the solved-by-someone-else branch.

Sweep F. Historical recurrence, one call per surviving candidate. standalone_query set to the scrubbed literal error string, date_range ending where the sweep window begins and starting as far back as capture goes. This finds occurrences that predate the knowledge base and is what makes the occurrence log honest (references/solve-detection.md section 5).

Sweep G, only when a call was involved. Lookup by NAME uses LB_INTERNAL_LIST_MEETINGS with name. Lookup by TOPIC uses LB_INTERNAL_SEARCH_MEETINGS with query. Using the wrong one is the most common retrieval mistake against this server (references/littlebird-mcp-reference.md, retrieval pattern 6).

Then sort by timestamp. Retrieval is relevance-ordered, not chronological (references/littlebird-mcp-reference.md, known limitations), and the entire detection method is a time-ordered shape, so an unsorted sweep detects nothing.

---

Detecting a solve

Full method in references/solve-detection.md. The shape, in one table:

Phase	What it is
A. Surface	An error string or a failure state appears in capture.
B. Grind	The error recurs across snapshots while the context churns: searches, docs, issue pages, an assistant panel, config edits, repeated command runs.
C. Cessation and resumption	The error stops appearing, AND the original work advances without it.

Both halves of C are required. Cessation alone is what abandonment looks like too, and that single discrimination carries most of the skill's accuracy.

The four outcomes, each filed differently:

Outcome	Filed as
Solved	A full entry.
Abandoned	One line in open-walls.md. Never a fix entry.
Solved by someone else	A full entry, solved-by: other, attribution taken from meeting summaries rather than raw transcript.
Solved by an assistant, not understood	A full entry, solved-by: ai-assistant, understood: no, Root cause usually honestly empty.

That last row is the most valuable capture in the skill. 59% of developers report using AI-generated code they do not fully understand, from a survey of 800 professionals [references/research/distilled-personal-knowledge-capture.md section 6], and separately stated trust in AI tools fell from 40% in 2023 to 29% in 2025 against 84% adoption [references/research/distilled-personal-knowledge-capture.md section 6]. Those measure different things and are not merged. The consequence is the point: a fix accepted without understanding is the one entry the user cannot reconstruct from memory, because no memory was formed.

Ambiguous means abandoned. A missing entry costs one re-debug. A wrong entry costs a re-debug plus the time spent trusting it.

Detection is a design decision in full. The archive contains no source on detecting a solve from observational data [references/research/distilled-personal-knowledge-capture.md section 8]. Say so if the user asks how it works.

---

Evidence standards

Apply references/evidence-standards.md in full. The four that bite hardest here:

• Receipts on everything (rule 1), in the form [Tuesday, August 11, 2026 23:40 EDT | chrome]. In this skill the receipt is also a navigation aid: the user opens that timestamp in the Littlebird app to see the original screen. Say so once, in the provenance block.
• Observed, inferred, external, unknown stay visibly different (rule 2). An error string read cleanly off a snapshot is observed. A repaired OCR string is inferred. A root cause concluded from the shape of the fix is inferred and says so. "Understood: no" is always an inference.
• Rate what the user will act on (rule 3). A Low-confidence fix that touches production, deletes data, or changes billing carries a stop marker telling the reader to verify before running it.
• Attribution guardrail (rule 4). Capture shows what was viewed, not what was written. A screen share is someone else's machine. A pasted block from an assistant is not the user's reasoning. Every solved-by value is an attribution claim and gets the same scrutiny.

---

Secret scrubbing is mandatory and is this skill's top risk

Debugging capture is denser with credentials than any other kind, because credentials are exactly what you look at when something is broken. A failing API call shows the bearer token. A refused database connection shows the connection string with the password in it. A 401 shows the client secret. A failed deploy prints environment variables into the build log.

Worse, the secret is often inside the error message, which is the one field this skill preserves verbatim and makes greppable. The SEARCH: line is the highest-risk line in the artifact.

references/secret-scrubbing.md is mandatory reading and the pass is mandatory execution. The method itself is inherited by reference from the redaction-pass guide that ships inside the sop-forge skill in this marketplace, which carries the category taxonomy, the three-sweep scan, and the evidence behind them. It is not rebuilt here and it is not re-evidenced here.

The deltas that matter in this skill:

1. Scrub before you compare. Order is fixed: detect, scrub, compare, draft, confirm, write. An unscrubbed string must never reach the dedupe check, because the check prints what it matched.
2. Never print a matched secret into the transcript. Not the value, not a prefix, not a masked form, not "the key ending in 8f2c". Report a count, a category, and a location. Never ask the user to confirm whether a specific value is a real key.
3. Structure-preserving placeholders in error strings. Error: connect ECONNREFUSED postgres://[USER]:[PASSWORD]@[DB_HOST]:5432/[DATABASE] keeps ECONNREFUSED postgres and the port, which is what the user will grep for. Never [REDACTED]. An entry whose commands carry placeholders the reader cannot resolve is a named failure mode of operational documentation [references/research/distilled-personal-knowledge-capture.md section 3].
4. Where scrubbing destroys the search key, say so and lose the key. Never keep a secret to preserve searchability.
5. The rotation flag goes at the top of the sweep report, naming the field, the time, and the app. Never the value. Screen capture of a credential is exposure.
6. The entry persists, so the floor is higher than for a one-time document. Assume every entry will eventually be pasted into a chat, because the useful ones are exactly the ones the user will send to a colleague.

---

Deduplication, and why recurrence is the point

The same gotcha recurs. A second encounter updates the existing entry with a new occurrence row. It does not create a second entry. Full rules in references/kb-structure-and-dedupe.md section 3.

Run the deterministic first pass:

python3 scripts/kb_index.py knowledge-base --check "the scrubbed error string"

It normalizes away paths, ids, hashes, line numbers, and ports, keeps version numbers and error codes because those are the discriminators, scores against every SEARCH: line and title, and checks rejected.md in the same call. It matches text, not meaning, so judge symptom, cause, and fix by hand before merging. The thresholds are a design decision; the archive has no research on deduplicating personal knowledge base entries [references/research/distilled-personal-knowledge-capture.md section 8].

Recurrence escalates. The occurrence log is not bookkeeping. Google's postmortem practice runs automated trend analysis across many postmortems precisely so recurrence becomes visible [references/research/distilled-personal-knowledge-capture.md section 4]. The personal version:

Occurrences	Report behavior
2	Noted.
3	Flagged, with elapsed span and summed lower-bound time cost.
4 or more	Top of the report, above new candidates, with a specific structural fix proposed: a pinned version, a lint rule, a CI check, a removed dependency.

Keep it blameless. "You have hit this four times, here is the structural fix", never "you keep making the same mistake". A record that indicts the person reading it stops getting written [references/research/distilled-personal-knowledge-capture.md section 4]. The escalation is a proposal. This skill never changes the user's code or config.

---

Staleness

A fix from two majors ago is a wrong answer the user's own past self vouched for.

This is the best-evidenced risk in the skill. Of measured obsolete answers on a public platform, 58.4% were already obsolete when first posted and only 20.5% were ever updated, with an average 118-day lag between someone noticing and anyone acting [references/research/distilled-personal-knowledge-capture.md section 5]. Third-party libraries and language versions together account for roughly 63% of obsolescence [references/research/distilled-personal-knowledge-capture.md section 5]. The authors' recommendation to writers is exactly what this skill implements: include version and time information [references/research/distilled-personal-knowledge-capture.md section 5].

Every entry carries pinned versions, a review-after date, and a last-confirmed date. Every sweep runs:

python3 scripts/kb_index.py knowledge-base --stale

and surfaces at most four flagged entries, ordered by how much the user loses if the entry is wrong. A staleness list longer than the candidate list turns the report into a chore, and a chore gets muted.

Outcomes are reconfirm, revise, or retire. Retire, never delete: a retired entry still answers "did I already decide this does not apply", and deletion destroys the occurrence history that drives escalation. Full rules in references/staleness-and-versions.md.

---

Output

The artifact

knowledge-base/
├── INDEX.md                 generated, never hand-edited
├── entries/
│   └── YYYY-MM-DD--kebab-slug.md
├── open-walls.md            abandoned problems, one line each
└── rejected.md              the rejection ledger

Flat entries/, one markdown file per entry, filename equal to the entry id. Location confirmed with the user on first run and recorded; default knowledge-base/ in the working directory.

Flat rather than topic folders because the retrieval path is a human running grep for an error string, and topic folders force a filing decision at write time about a category the user will not remember at read time. The archive's one concrete personal knowledge base layout uses topic folders and explicitly does not solve search [references/research/distilled-personal-knowledge-capture.md section 7]; the practitioner source that repaired a failing base did it by abandoning topic grouping for index-by-future-retrieval-context [references/research/distilled-personal-knowledge-capture.md section 2]. Flat plus tags plus a generated index is a design decision filling that gap.

The entry

Fixed schema, every field present, empty fields stated rather than dropped. Full template and worked example in references/entry-schema.md.

Field	Rule
Title	Names the symptom, not the cause and not the fix.
Symptom	A one-line SEARCH: holding the literal error text verbatim and unwrapped, the grep target, plus a concrete description and the query the user actually typed.
Context	Stack, exact pinned versions, environment. unknown, not captured where capture did not show it. Never "latest".
Root cause	Separate field. established, empirical, or unknown. Never invented. The published template omits cause when unknown rather than forcing a guess [references/research/distilled-personal-knowledge-capture.md section 3].
The fix	Actual commands, config, or code, verbatim and scrubbed, ordered most-likely-first, ending in an explicit expected outcome.
What did not work	Mandatory. Each line: what was tried, why it looked right, what happened instead. The middle part is what saves time.
Time cost	A bounded range with the snapshot count, never a single number, and "unbounded, ask the user" when the phases span an uncaptured gap.
Occurrences	Date, receipt, what was different. Drives the escalation ladder.
Tags	3 to 6, lowercase kebab, one greppable line.
Provenance	Receipts back to the source capture with timestamps the user can open in the Littlebird app, plus the redaction count and categories.

Title and Symptom carry the whole retrieval story, and that rule has the strongest support in the archive: two independent sources in different domains reach it [references/research/distilled-personal-knowledge-capture.md section 2]. The knowledge base literature states "Use the reader's language. Titles and symptom descriptions should use the exact error message text" [references/research/distilled-personal-knowledge-capture.md section 3]; the personal knowledge management practitioner reached the same rule by asking "in what context might I refer to this note in the future?" [references/research/distilled-personal-knowledge-capture.md section 2].

The weekly sweep report

Produced by the routine, read by this skill. Order: security notice if credentials were found, then recurrence escalations, then new candidates with their classification and confidence, then at most four staleness flags, then the carry-forward rejection block.

---

Confirm before anything is appended

Nothing is written to the knowledge base without the user approving that specific entry. Not the plan, the entry.

This is the encode gate (references/evidence-standards.md rule 6) and it is also the skill's answer to its own biggest risk. Automation makes collecting free, and the Collector's Fallacy is a reward loop attached to the act of collecting [references/research/distilled-personal-knowledge-capture.md section 2]. A skill that appends without engagement removes the only step the archive says produces knowledge, which is effortful engagement [references/research/distilled-personal-knowledge-capture.md section 2]. Unprocessed collections become liabilities that accumulate faster than they can be engaged and are then ignored entirely [references/research/distilled-personal-knowledge-capture.md section 2].

Use AskUserQuestion, one candidate at a time, showing the drafted entry. For each:

• Approve as drafted
• Approve with edits, and take the edits
• Reject, and record it in rejected.md with the date, the fingerprint, and the reason
• Defer to next week

Confirm specifically: the classification (solved versus abandoned versus assistant-solved), any Low-confidence reading, the root cause when it is marked established, and the redaction choices for the confirmable categories. Do not ask the user to confirm every High-confidence field individually, which is just asking them to write the entry themselves.