Update to Usable

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