knowledge-management

Knowledge Management

This skill guides proper knowledge capture in the PM Dashboard knowledge system.

Core Principle

Only capture what's hard-won, not what's routine.

Knowledge items are for future you and your team to avoid repeating painful debugging sessions or trial-and-error.

When to Capture Knowledge

✅ DO Capture

Trial-and-Error Solutions (took multiple attempts):

upsert_knowledge(
    title="PostgreSQL FTS GIN Index Required (Not BTREE)",
    content="Problem: Search slow (2000ms). Tried: 1) BTREE index (no help), 2) Increased work_mem (no help), 3) Finally: GIN index required for FTS. Command: CREATE INDEX USING gin(to_tsvector('english', content)). Result: 50ms search time.",
    category="database_gotchas",
    tags='["postgresql", "fts", "performance", "indexing"]',
    task_id="current_task_id"
)

Non-Obvious Gotchas:

upsert_knowledge(
    title="GitHub OAuth Requires User-Agent Header",
    content="Gotcha: GitHub OAuth API returns 403 without User-Agent header. Not prominently documented. Required: User-Agent: YourAppName/1.0",
    category="integration_gotchas",
    tags='["github", "oauth", "http_headers", "403"]',
    task_id="current_task_id"
)

User Corrections (what NOT to do):

upsert_knowledge(
    title="FastMCP Parameters Must Be Strings",
    content="Critical: FastMCP only accepts string parameters. Passing task_id=123 (int) fails silently. Must use task_id='123' (string). Applies to ALL MCP parameters.",
    category="user_corrections",
    tags='["fastmcp", "parameters", "types", "gotcha"]',
    task_id="current_task_id"
)

Integration Challenges (required research/debugging):

upsert_knowledge(
    title="WebSocket Connection Requires CORS Headers",
    content="Problem: WebSocket connections failed from frontend. Tried: 1) Different ports (failed), 2) Finally discovered: Need CORS headers for WebSocket handshake. Solution: Add Access-Control-Allow-Origin to WebSocket endpoint.",
    category="integration_gotchas",
    tags='["websocket", "cors", "frontend", "connection"]',
    task_id="current_task_id"
)