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

Type	Scope	When to Use
Full	Read all source files, create/update all code maps	First time, major version, annual
Incremental	Compare git diff since last anchor, update affected docs	After feature work, monthly
Targeted	Focus on specific area (e.g., just CLI or just dashboard)	After focused changes

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