--- name: usable-knowledge-capture description: Capture a verified outcome back into Usable so the next person or agent does not rediscover it. Use after fixing a non-obvious bug, making an architectural decision, finishing an incident investigation, or discovering a constraint that cost real time. Requires the outcome to be verified first, prefers updating an existing item over creating a duplicate, and always asks before writing. --- # Usable knowledge capture Knowledge that stays in a chat transcript is lost. This skill writes verified outcomes into Usable so the next person does not pay the same debugging cost twice. ## Preconditions Do not write anything until all four hold: 1. **The outcome is verified.** Tests passed, the behavior was observed, the fix is confirmed in reality — not predicted. An unverified guess written into durable knowledge is worse than no knowledge at all, because it will be trusted later. 2. **Write tooling is available and authorized.** If the Usable MCP server is missing or unauthenticated, say so and offer the content for the user to save manually. 3. **The user has confirmed.** Show what you intend to write and where, and wait for a yes. 4. **It is worth keeping.** See the bar below. ## What is worth capturing Capture when the answer was expensive to find and would be expensive to find again: - a bug whose root cause was not obvious from the symptom - an architectural decision, including the options rejected and why - a constraint discovered the hard way — an API limit, a schema quirk, an ordering requirement - an incident: what broke, why, how it was diagnosed, what fixed it - a repeatable procedure that took several attempts to get right - a hypothesis that measurement killed; negative results save the next person a day Do not capture: - routine changes obvious from the diff - restatements of public documentation - anything unverified - transient state ("the build is currently red") - content containing secrets, personal data, or customer data ## Update before you create Search for existing coverage first. Duplicates fragment the corpus and cause exactly the conflicting-guidance problem the retrieval workflow has to spend effort resolving. - Same topic, still accurate, new detail → update it. - Same topic, now wrong → update it and state what changed and when. - Genuinely new topic → create, and reference related items. Prefer one good item that gets maintained over three partial items that rot. ## What to include - **Title** — specific enough to recognize in a search result. "Badge print claim returns 500 because FOR UPDATE cannot be used with LEFT JOIN" beats "Fixed printing bug". - **Context** — the symptom as it was first observed, and where. - **Root cause** — the actual mechanism, not just the change made. - **Resolution** — what fixed it, and why that works. - **Verification** — how you know. Name the tests, commands, or observations. - **Metadata** — repository, branch, version, or release, when known. - **Residual risk** — what remains untested or uncertain. - **Tags** — repository and domain tags so the item is findable later. Write for a reader who has none of the current conversation's context. ## Before writing: redact Strip access tokens, API keys, passwords, connection strings with embedded credentials, internal-only URLs, personal data, customer data, and raw logs containing any of those. Describe the shape of a value instead of reproducing it. ## Confirmation Always show the plan and wait: > I'd like to record this as a solution titled "" in <workspace>, tagged > `<tags>`. It covers the root cause, the fix, and the verification steps. Save it? If write tooling is unavailable, say so and hand the content over instead: > I can't write to Usable — no authorized write tool is configured. Here is the content if > you'd like to save it yourself: ... Never write silently, and never treat an earlier "yes" in the conversation as blanket approval for later writes.