/organize-knowledge

Workflow: Organize Knowledge Base

Consolidates scattered investigation docs, notes, and findings into the correct knowledge files. Prevents knowledge sprawl and ensures ONE file per feature.

Trigger phrases: "organize knowledge", "consolidate docs", "clean up knowledge", /organize-knowledge

---

The Problem This Solves

Over time, investigations produce scattered files:

• INVESTIGATION_ORDER_BUG.md
• FIX_WALLET_ISSUE.md
• NOTES_ON_CACHE_PROBLEM.md
• Duplicate findings across multiple files

This workflow consolidates everything into the correct knowledge/[FEATURE].md file — one file per feature, not one file per ticket.

---

Step 1 — Find Scattered Docs

Search for investigation artifacts that should be consolidated:

*_INVESTIGATION.md
INVESTIGATION_*.md
*_FIX.md
*_NOTES.md
*_DEBUG.md
*_FINDINGS.md

Also check:

• knowledge/ for files that overlap in topic
• Root directory for stray markdown files
• .claude/knowledge/, .agent/knowledge/, or knowledge/ for orphaned docs

---

Step 2 — Map Each Doc to a Feature

For each scattered doc, determine which feature it belongs to:

Doc	Feature Area	Target File
INVESTIGATION_ORDER_BUG.md	Orders	knowledge/orders.md
FIX_WALLET_ISSUE.md	Wallet	knowledge/wallet.md
CACHE_NOTES.md	General	rules/anti-patterns.md or knowledge/caching.md

Rules:

• If a feature knowledge file already exists → merge into it
• If no file exists → create from knowledge/_TEMPLATE.md
• If the finding is a general rule (not feature-specific) → add to the appropriate rules/*.md file
• NEVER create two files for the same feature

---

Step 3 — Extract and Classify Findings

From each scattered doc, extract:

Finding Type	Goes Into
Root cause of a bug	Knowledge file → "Issues Found & Fixed"
Diagnostic query that was useful	Knowledge file → "Diagnostic Queries"
Lesson / pattern discovered	Knowledge file → "Key Lessons"
DB column type gotcha	Knowledge file → "DB Gotchas"
General coding rule	rules/code-quality.md or closest rule file
Anti-pattern with wrong/correct	rules/anti-patterns.md

Convert narrative to directive:

• ❌ "We found that the wallet balance was wrong because currency_id was missing"
• ✅ "When wallet balance is wrong → check if currency_id is included in the query. Missing currency_id causes the conversion trait to skip currency conversion silently."

---

Step 4 — Merge Into Target Files

For each target knowledge file:

1. Read the existing file
2. Check for duplicates (don't add what's already there)
3. Add findings to the correct section
4. Update "Last Updated" date

For new knowledge files:

1. Copy knowledge/_TEMPLATE.md → knowledge/[feature].md
2. Fill in "How It Works" section
3. Add all findings from scattered docs

---

Step 5 — Archive or Delete Scattered Docs

After merging:

• Delete the scattered investigation files (the knowledge is now in the right place)
• If unsure, move to a knowledge/_archived/ directory first

---

Step 6 — Report

Consolidated 4 scattered docs into knowledge files:

knowledge/orders.md (created):
  → Merged INVESTIGATION_ORDER_BUG.md (root cause + 2 queries)
  → Merged ORDER_NOTES.md (3 lessons)

knowledge/wallet.md (updated):
  → Merged FIX_WALLET_ISSUE.md (1 issue + 1 gotcha)

rules/anti-patterns.md (updated):
  → Added: NEVER skip currency_id in wallet queries

Deleted: INVESTIGATION_ORDER_BUG.md, ORDER_NOTES.md, FIX_WALLET_ISSUE.md

---

Anti-Patterns

❌ Multiple knowledge files for the same feature (orders_investigation.md AND orders_bugs.md) ❌ Keeping session-specific IDs in consolidated docs ❌ Narrative prose ("On Tuesday we found...") — use directives ❌ Creating a knowledge file when a rules/*.md file is the right home ❌ Leaving scattered docs after consolidating (creates confusion about which is authoritative)

✅ ONE file per feature area ✅ Directive format: "When X → check Y" ✅ Generic placeholders: ORDER_ID, USER_ID ✅ Delete originals after merging