knowledge-save

knowledge-save

You are deciding whether a just-solved problem is worth preserving in the user's Knowledge Base, and if so, writing it.

The whole point of this skill: the next time this problem appears (in this session or a future one), knowledge-lookup finds it and prevents re-solving.

Rigid process — run these steps in order every time

Step 1: Walk the save checklist

Explicitly check EACH box against the task you just finished. Announce which boxes are triggered.

• A behavior surprised me (silent no-op, misleading error, counterintuitive default, docs said X but code did Y)
• A fix took >2 attempts or felt like "finally got it"
• I discovered a framework/tool quirk not obvious from docs
• I established a new reusable pattern (new module type, new deploy step, canonical setup for something)
• I had to read the source of a dependency to understand behavior

If NONE apply, announce:

Save skipped — no checklist item triggered. (Ran: surprise N, attempts N, quirk N, new pattern N, read source N.)

Then STOP. Do not write.

If ANY apply, continue to Step 2.

Step 2: Decide type

• Gotcha — documents something that went wrong. Prevents pain. Structure: Symptom → Root cause → Fix → Example incident → Prevention.
• Pattern — documents a reusable way to do something. Accelerates work. Structure: When to use → Steps → Example → Pitfalls.

Don't mash both into one doc. If the work is both ("we hit a gotcha AND established a pattern"), write two docs.

Step 3: Decide scope

• Cross-project — applies to any repo using this tool/framework. Goes in Resources/gotchas/ or Resources/patterns/.
• Project-specific — tied to this codebase's specific wiring, deploy, or data model. Goes in Projects/<slug>/gotchas/ or Projects/<slug>/patterns/.

Litmus test for cross-project: "Would this be useful in a completely different repo that uses the same tool?" If yes, cross-project.

Current project slug resolves the same way as in knowledge-lookup: CLAUDE.md frontmatter project_slug, then git repo basename, then give up and use cross only.

Step 4: Dedup check

Grep the MOC for overlapping keywords:

grep -i "<key-keyword>" ~/Documents/workspace/obsidian-vault/claude-code/Resources/MOC-Knowledge-Base.md

Try 2-3 distinctive keywords. If a line comes back that looks like it covers the same problem, UPDATE that existing doc rather than creating a new one. Append today's incident to its ## Example incident section. Update the MOC one-liner if wording needs refinement.

If no overlap, continue to Step 5.

Step 5: Write the full doc

Pick the path based on type + scope:

Type	Scope	Path
gotcha	cross	~/Documents/workspace/obsidian-vault/claude-code/Resources/gotchas/<slug>.md
gotcha	project	~/Documents/workspace/obsidian-vault/claude-code/Projects/<slug>/gotchas/<slug>.md
pattern	cross	~/Documents/workspace/obsidian-vault/claude-code/Resources/patterns/<slug>.md
pattern	project	~/Documents/workspace/obsidian-vault/claude-code/Projects/<slug>/patterns/<slug>.md

If the project-specific gotchas/patterns folder doesn't exist yet, create it.

<slug> is kebab-case, descriptive, ≤ 6 words. Examples: drizzle-migration-when-timestamp, nginx-alb-cookie-stripping, new-account-tab.

Gotcha template (reuse the canonical structure from Resources/gotchas/drizzle-migration-when-timestamp.md):

---
title: <title>
date: YYYY-MM-DD
tags:
  - type/gotcha
  - stack/<stack>
  - project/<project-or-cross>
---

# <title>

Back to: [[Resources/MOC-Knowledge-Base|MOC — Knowledge Base]]

## Symptom
<what you observed — commands run, output shown, user-visible effect>

## Root cause
<why it happens — the mechanism or library behavior that causes it>

## Fix
<steps to resolve — concrete commands or edits>

## Example incident
<concrete case: project, date (ISO), ticket ID, what happened, what fixed it, commit hash if known>

## Prevention
<how to avoid next time — a check, a lint, a doc update>

## Related
<wikilinks to related entries, MOCs, or code paths>

Pattern template:

---
title: <title>
date: YYYY-MM-DD
tags:
  - type/pattern
  - stack/<stack>
  - project/<project-or-cross>
---

# <title>

Back to: [[Resources/MOC-Knowledge-Base|MOC — Knowledge Base]]

## When to use
<trigger conditions — what situation makes this pattern the right choice>

## Steps
1. …
2. …
3. …

## Example
<concrete application — paste the code/commands/config from when you just applied it>

## Pitfalls
<what to watch out for — the places this pattern misleads>

## Related
<wikilinks>

Step 6: Update the MOC index

Prepend (NOT append) a one-line entry to the matching section of ~/Documents/workspace/obsidian-vault/claude-code/Resources/MOC-Knowledge-Base.md. Newest entries are on top within each section.

Format:

- [[<vault-path>|<title>]] — <scope> <keywords> <one-line hook>

• <vault-path>: e.g. Resources/gotchas/my-new-gotcha (no .md)
• <title>: the H1 title of the full doc
• <scope>: cross or project slug
• <keywords>: 2-5 lowercase topic words — stack, area, error type
• <hook>: terse description, ≤ 15 words

Example:

- [[Projects/c360/gotchas/nginx-alb-cookie-stripping|c360 nginx ALB cookie stripping]] — c360 nginx deploy alb ALB rewrites Set-Cookie domain on cross-origin requests

Step 7: Report and STOP

Announce to the user:

KB saved:
- Type: <gotcha | pattern>
- Scope: <cross | project>
- Doc: <full path>
- MOC updated: Resources/MOC-Knowledge-Base.md (prepended 1 line)

Vault changes are NOT committed — please review and commit manually.

Do NOT run git commit in the vault. The user wants to eyeball vault changes before they become permanent.

Edge cases

• Similar entry already exists (Step 4 found a match): update it instead. Append a new ## Example incident entry under the existing one (don't overwrite). Announce KB updated (existing entry enriched) instead of KB saved.
• No write permission to vault: announce KB save failed — could not write to <path>. Please check vault path. and stop.
• Multiple triggers in one task: write one doc per distinct problem, not one doc mashing them together. Each doc is its own Step 5 + Step 6 cycle.
• Uncertain whether it's gotcha or pattern: default to gotcha. Gotchas are easier to rewrite as patterns later than vice versa.