Update KB Docs from Codebase

Synchronize knowledge base documentation with current codebase implementation.

Prerequisites

ALWAYS run /pmc:kb first to understand KB structure and document formats.

Audit Types

Full Audit Procedure

Step 0: Record Anchor Point

git rev-parse HEAD
git log -1 --format="%H %s (%ai)"

Create audit notes file: .pmc/docs/6-references/audit-{date}.md

# Code Audit Notes - {date}

**Anchor Commit:** `{hash}` - "{message}" ({date})
**Status:** In Progress

## Files Read
(track as you go)

## Features Discovered
(update incrementally)

Decision: Always record anchor for future incremental audits.

Step 1: Inventory All Source Files

Glob: src/**/*.py  (or appropriate pattern for your codebase)

Group by area (example for Python):

• Core (engine, models, parser, context, config)
• Executors/Handlers
• Storage/Database
• API/CLI
• UI/Dashboard

Step 2: Read ALL Files (Full Audit)

Critical: For full audit, read every file. Do not sample or infer.

Read in parallel where possible. Update audit notes incrementally:

### {Area} ({n}/{total} read)

| File | Lines | Features Identified |
|------|-------|---------------------|
| file.py | 123 | Feature1, Feature2 |

Decision: Reading is non-negotiable for full audit. Sampling leads to gaps.

Step 3: Compile Feature List

After reading all files, create comprehensive feature list organized by functional area.

Step 4: Determine Code Maps Needed

Glob: .pmc/docs/5-code-maps/*.md

For each feature area, decide:

• Update existing code map if it exists but is outdated
• Create new code map if area is undocumented
• Skip if trivial or internal-only

Decision: Feature-based approach (not file-based) ensures user-relevant documentation.

Step 5: Create/Update Code Maps

For each code map:

1. Read existing (if updating)
2. Write comprehensive documentation
3. Include: files, line numbers, key functions, data flow
4. Mark audit date in file

Format: See kb/references/codemap-format.md

Step 6: Update Audit Notes

Mark audit as complete:

• Change status to "Complete"
• Add recommendations section
• Note any issues found

Phase 2: PRD & Pattern Consistency

After code maps are current, verify other docs match reality.

Step 1: Audit PRDs

Glob: .pmc/docs/1-prd/*.md

For each PRD:

1. Read the PRD
2. Compare features listed vs code maps
3. Mark as: current, outdated, or deprecated
4. Update PRD if features are implemented - don't just note discrepancies

Step 2: Audit Patterns

Glob: .pmc/docs/4-patterns/*.md

For each pattern:

1. Check Status: open patterns - still valid?
2. Check Status: resolved patterns - solution still applies?
3. Ensure all patterns have explicit Status: open | resolved
4. Look for new patterns from code (workarounds, edge cases)

Phase 3: User-Facing Docs

Step 1: Update 8-users/

Source: CLI help, README, code map features

• personas.md - Who uses this?
• use-cases.md - Common scenarios
• faq.md - Questions answered in sessions

Step 2: Review SOPs

Glob: .pmc/docs/2-sop/*.md

For each SOP:

1. Verify commands still exist (check against code maps)
2. Update paths/options if changed
3. Update historical status if resolved (e.g., "tracked for Phase X" → "Fixed in Phase Y")
4. Add new SOPs for undocumented workflows

Incremental Audit Procedure

Step 1: Find Changes Since Last Anchor

git log --oneline {last-anchor}..HEAD
git diff --name-only {last-anchor}..HEAD -- src/

Step 2: Read Changed Files Only

Focus on files that changed. Update affected code maps.

Step 3: Record New Anchor

Update audit notes with new anchor commit.

Key Learnings

1. Commit anchor is mandatory - enables incremental audits
2. Audit notes go in 6-references/ - permanent record
3. Full audit = read ALL files - no sampling
4. Feature-based code map organization - not file-based
5. Update docs immediately - don't just note discrepancies
6. Check Glob paths carefully - they can fail silently
7. PRDs should match implemented features - not aspirational ones
8. All patterns need explicit Status - open or resolved
9. Verify command references - against code maps
10. Update historical status - when issues are resolved

Checklist

• Record anchor commit
• Create audit notes file
• Read all source files (full) or changed files (incremental)
• Update/create code maps
• Audit PRDs against code maps
• Audit patterns (ensure Status field)
• Update user docs (8-users/)
• Review SOPs for outdated commands
• Mark audit complete
• Commit changes