knowledge-base-update

name	knowledge-base-update
description	Use this skill whenever you learn something important during a conversation: a key architectural decision, a project-specific convention, a bug root-cause, a 3rd-party API quirk, or any fact that would help a future agent avoid re-doing the same research. Writes structured entries to the project's knowledge base so that context persists across conversations and agents.

Knowledge Base Update Skill

When to Trigger

Activate this skill when any of the following occur:

• An architectural or tech-stack decision is made (and the why matters)
• A non-obvious bug is fixed (root cause + fix documented)
• A 3rd-party service/API has a quirk, limit, or gotcha discovered
• A project convention is established (naming, folder structure, patterns)
• A research question is answered after significant investigation
• A "we tried X and it failed because Y" moment happens

Step-by-Step Process

1. Identify the Entry Type

Choose the category that best describes what was learned:

Type	When to Use
decision	Architecture, tech choices, trade-offs
convention	Naming rules, code patterns, folder structures
bug	Root cause + fix for a non-obvious problem
gotcha	3rd-party quirk, env issue, edge case trap
research	Answer to a question requiring significant investigation

2. Determine the File Path

Write to: .agent/knowledge/<slug>.md

• slug = kebab-case summary of the topic (e.g., auth-token-refresh-strategy)
• If an entry for this topic already exists, update it rather than creating a new file
• Group related topics under subfolders: .agent/knowledge/auth/, .agent/knowledge/infra/, etc.

3. Write the Entry

Use this exact template:

---
type: <decision|convention|bug|gotcha|research>
topic: <Short human-readable title>
date: <YYYY-MM-DD>
tags: [<tag1>, <tag2>]
---

## Summary
<One or two sentences — what was learned, bottom line up front>

## Context
<Why this came up. What problem were we solving?>

## Decision / Finding
<The actual content. Be specific. Include code snippets if helpful.>

## Rationale
<Why this choice over alternatives. What alternatives were rejected and why.>

## Consequences
<What does this affect going forward? What to watch out for?>

## References
- <File path, PR link, conversation snippet, or external URL>

4. Update the Index

After writing the entry, append a one-line summary to .agent/knowledge/INDEX.md:

| <date> | <type> | [<topic>](./<path>.md) | <one-line summary> |

If INDEX.md doesn't exist yet, create it with this header first:

# Project Knowledge Base

| Date | Type | Topic | Summary |
|------|------|-------|---------|

5. Confirm to User

After writing, report:

• What was saved and where
• The one-line summary that was added to the index

Rules

• Never summarize vaguely. "We decided to use X" is useless without why.
• Include the anti-pattern. If something was tried and rejected, document it — that's often the most valuable knowledge.
• Keep entries atomic. One topic per file. Don't bundle unrelated decisions.
• Date is mandatory. Future agents need to know how fresh this knowledge is.
• If in doubt, write it. The cost of a redundant entry is low. The cost of a missing one is re-doing the work.