Skip to main content

Knowledge > Runbooks > Agent Ops > Keep Knowledge Docs Current

Keep Knowledge Docs Current

Ensure that the C:\dev\knowledge\ system stays accurate whenever code, pricing, features, or policies change.

Why This Matters​

The knowledge/ system is the canonical truth for everything Claude agents and the voice agent / chatbot read at runtime. Stale knowledge = agents giving customers wrong information about pricing, features, or how to do things. This is a real-time product failure, not just a documentation problem.

The Rule​

When you change code that is referenced by a knowledge doc, you MUST update the knowledge doc in the same commit.

Steps​

1. Identify Which Knowledge Docs Reference Changed Code​

Search for code file references in knowledge/ documents:

  • Check the code-files field in document frontmatter (if present)
  • Search C:\dev\knowledge\ for the file name you changed
  • Check knowledge/INDEX.md for the changed component
grep -r "chatbot/stream" /c/dev/knowledge/
grep -r "pricing.ts" /c/dev/knowledge/

2. Determine What Type of Change Requires Knowledge Updates​

Change TypeRequired Knowledge Update
Pricing changedknowledge/data/pricing.yaml → run pnpm derive
New feature added or removedknowledge/data/features.yaml → run pnpm derive
Product name or URL changedknowledge/data/products.yaml → run pnpm derive
Policy changed (cancellation, trial, etc.)knowledge/data/policies.yaml → run pnpm derive
Checkout flow changedproduct_knowledge table + relevant knowledge doc
Admin flow changedproduct_knowledge table + relevant knowledge doc
Onboarding flow changedproduct_knowledge table
Voice agent prompt/behavior changedproduct_knowledge table + knowledge/products/voice-agent/
Chatbot behavior changedproduct_knowledge table + knowledge/products/chatbot/
Integration added/changedknowledge/integrations/
API endpoint added/changedRelevant architecture doc in knowledge/

3. Update YAML Sources and Run Derive​

For pricing, features, products, and policies — ALWAYS update the YAML source, never the downstream files directly:

# Edit the canonical source
code /c/dev/knowledge/data/pricing.yaml
# or features.yaml, products.yaml, policies.yaml

# Then propagate to all downstream targets
cd /c/dev/knowledge
pnpm derive

Derive targets include: pricing.ts, PRICING.md, product_knowledge table, marketing page verification files.

Run pnpm derive --check before pushing to verify no drift between sources and targets:

cd /c/dev/knowledge
pnpm derive --check

Run write modes (bare, --dry-run, --commit, --all) only from the main C:\dev\knowledge checkout, and only when no other agent is active there. They resolve every target by absolute path, so they can silently write into a sibling checkout another agent is mid-edit in (C:\dev\churchwiseai-web, C:\dev\pewsearch, even C:\dev\knowledge itself if run from a worktree). derive now refuses to do that on its own: it aborts if invoked from a knowledge worktree, and aborts if any target repo has uncommitted changes or isn't on its deploy branch — see the "Write-mode guardrails" section of Knowledge Derivation Pipeline. --check is unaffected — it's read-only and safe from any checkout.

4. Update product_knowledge Directly for Flow/UX Changes​

When checkout flows, admin flows, onboarding steps, or troubleshooting procedures change, update product_knowledge directly (this is not covered by the derive pipeline):

-- Update an existing entry
UPDATE product_knowledge
SET answer = 'Updated answer...', updated_at = now()
WHERE question = 'How do I access my admin dashboard?';

-- Add a new entry
INSERT INTO product_knowledge (category, question, answer, keywords, priority)
VALUES (
  'churchwiseai',
  'How do I do X?',
  'Updated step-by-step: 1. Go to... 2. Click...',
  ARRAY['keyword1', 'keyword2'],
  7
);

Categories: pewsearch | churchwiseai | billing | account | troubleshooting | getting_started | integrations | policies

5. Archive Content That Is No Longer Accurate​

When a feature is removed or a process changes completely:

  • Add ⚠️ ARCHIVED — [date] — [reason] at the top of the outdated doc
  • Move to knowledge/archive/ if the entire doc is obsolete
  • Do NOT delete — archived docs preserve institutional knowledge

6. Create New Knowledge Docs for New Products or Integrations​

When adding a completely new product, integration, or feature area:

  • Create the doc in the appropriate knowledge/ subdirectory
  • Add it to knowledge/INDEX.md
  • Add the code-files frontmatter field pointing to the relevant code files
  • Run pnpm derive to register it in the manifest if applicable

7. Verify in the Same Commit​

Commit the knowledge update in the same git commit as the code change:

git add src/app/api/chatbot/stream/route.ts
git add knowledge/products/chatbot/architecture.md
git commit -m "feat: update chatbot routing — update knowledge doc"

Verification​

  • pnpm derive --check from C:\dev\knowledge\ passes with no drift errors
  • product_knowledge table reflects current flows, pricing, and features
  • Any knowledge doc that references changed code files has been updated

See Also​