maintain-knowledge-base

Best practices for editing Knowledge Base markdown files

Maintain Knowledge Base Workflow

1. Required Frontmatter

All KB markdown files MUST have YAML frontmatter:
---
last_updated: YYYY-MM-DD
status: active  # or: superseded | deprecated
title: "Optional - auto-generated from filename if missing"
---

2. When Editing KB Files

// turbo-all

Step 1: Update Timestamp

When modifying ANY KB file, update last_updated to today's date:
last_updated: 2026-01-21  # Update to current date

Step 2: Verify Frontmatter

Ensure the file has valid YAML frontmatter with all required fields.

3. Creating New KB Files

  1. Add complete frontmatter (see above)
  2. Place in appropriate directory:
    • mechanics/ - Game mechanics (combat, skills, systems)
    • monetization/ - MTX, pricing, economy
    • quests/ - Quest documentation
    • lore/ - NPCs, locations, story
    • items/ - Item documentation
    • guides/ - Player guides
    • planning/ - Tasks, roadmaps, analysis
    • architecture/ - Backend/infra docs

4. Marking Docs as Superseded

When a doc is replaced by a newer version:
  1. Set status: superseded in frontmatter
  2. Add superseded_by: path/to/new/doc.md field
  3. Add a note at the top of the content:
> [!WARNING]
> This document is superseded by [New Doc](file:///path/to/new/doc.md)

5. Stale Detection

Files not updated in 90+ days should be reviewed for accuracy. Use MCP kb_stale_files tool to identify stale docs.

6. Verification

After KB edits, optionally run the linter:
cd loh-mcp-server
npm run lint-kb