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