DOMAIN:KNOWLEDGE_MANAGEMENT:WIKI_BRAIN_ARCHITECTURE¶

OWNER: annegreet
UPDATED: 2026-03-24
SCOPE: wiki brain structure, JIT injection, knowledge lifecycle, learning loop
AGENTS: annegreet (primary), eltjo (monitoring/patterns), mira (escalation)

WIKI_BRAIN:OVERVIEW¶

WHAT: the wiki IS the brain — MkDocs-based knowledge system that stores all institutional knowledge
WHERE: ge-ops/wiki/docs/ — three-layer structure
ACCESSIBLE: http://wiki.ge-wiki.svc.cluster.local (k8s internal), NodePort 30080 (LAN)
PRINCIPLE: if it is not in the wiki, it does not exist for GE
PRINCIPLE: knowledge must be findable, injectable, and expirable

PURPOSE:
- agents read wiki pages via JIT injection before starting tasks
- learnings from sessions feed back into wiki pages
- discussions that reach consensus become precedent pages
- the wiki replaces hallucination with verified institutional knowledge

WIKI_BRAIN:THREE_LAYER_STRUCTURE¶

LAYER_1: CLIENTS¶

PATH: docs/clients/
CONTENT: per-client, per-project data
EXAMPLES: client preferences, project history, technical decisions, meeting notes
ACCESS: restricted to agents working on that client
LIFECYCLE: created at onboarding, updated throughout engagement, archived post-delivery

LAYER_2: DEVELOPMENT¶

PATH: docs/development/
CONTENT: how GE builds — infrastructure, agents, standards, contracts, pitfalls, learnings
EXAMPLES: coding standards, API contracts, infrastructure pitfalls, handoff notes
ACCESS: all development agents
LIFECYCLE: created when pattern discovered, updated on refinement, deprecated when superseded

SUBPATHS:
- development/pitfalls/ — things that went wrong and how to avoid them
- development/standards/ — coding conventions, file structure rules
- development/contracts/ — API schemas, interface agreements between agents
- development/handoff.md — current session state (always up to date)
- development/evolution/pending/ — improvement ideas not yet acted on

LAYER_3: COMPANY¶

PATH: docs/company/
CONTENT: what GE is — identity, brand, strategy, rules, workflows
EXAMPLES: constitution, brand guidelines, client lifecycle, agent profiles
ACCESS: all agents
LIFECYCLE: changes require dirk-jan approval

SUBPATHS:
- company/identity/ — mission, organogram, swimlanes
- company/brand/ — tone, guidelines
- company/rules/ — constitution (10 principles)
- company/strategy/ — roadmap, philosophy
- company/workflows/ — TDD pipeline, client lifecycle
- company/sessions/ — verbatim session transcripts

WIKI_BRAIN:PAGE_STRUCTURE_CONVENTIONS¶

FRONTMATTER¶

OPTIONAL: YAML frontmatter for rich metadata

---
title: "Page Title"
layer: development          # company | development | clients
domain: pitfalls            # subdomain
tags: [networking, k3s, dns]
relevance:
  agents: [sandro, victoria, mira]
  human: false
  scope: infrastructure
last_updated: 2026-03-24
status: current             # current | draft | deprecated
priority: high              # high | medium | low
---

AGENTIC_FORMAT¶

PRINCIPLE: write for machine consumption, not human reading
FORMAT: structured key-value pairs, not prose paragraphs

GOOD:

PITFALL: using ClusterIP from inside pods on k3s
IMPACT: connection refused, 10.43.0.1:443 unreachable
FIX: use host cron with hostPath-mounted kubectl

BAD:

One issue we have encountered is that when trying to use ClusterIP
addresses from within pods on our k3s cluster, the connection is
refused because the API server at 10.43.0.1:443 is unreachable.
The recommended fix is to use a host-level cron job that mounts
kubectl via hostPath volumes.

STRUCTURAL_ELEMENTS¶

ELEMENT: section headers
FORMAT: ## CATEGORY:SUBCATEGORY (all caps, colon-separated)

ELEMENT: key-value pairs
FORMAT: KEY: value (key in all caps)

ELEMENT: conditional logic
FORMAT: IF condition THEN action or USE_WHEN: condition

ELEMENT: templates
FORMAT: code blocks with placeholder syntax {variable_name}

ELEMENT: pitfalls
FORMAT: PITFALL: description / IMPACT: what goes wrong / FIX: how to fix

ELEMENT: rules
FORMAT: RULE: statement (absolute) or RECOMMENDATION: statement (preferred)

WIKI_BRAIN:JIT_INJECTION¶

WHAT_IS_JIT_INJECTION¶

DEFINITION: Just-In-Time knowledge loading — agents receive relevant wiki pages at task start
WHY: agents have finite context windows; inject only what is relevant to current task
HOW: executor loads agent identity + domain pages + pitfalls before executing task

INJECTION_LAYERS¶

LAYER: core_identity (always injected)
SIZE: ~1,200 tokens
CONTENT: agent name, role, team, constitution principles
SOURCE: AGENT-REGISTRY.json + constitution.md

LAYER: role_knowledge (always injected)
SIZE: ~2,500 tokens
CONTENT: agent-specific domain knowledge, behavioral rules
SOURCE: agent identity file + relevant domain index

LAYER: task_context (injected per task)
SIZE: variable (up to ~10,000 tokens)
CONTENT: relevant domain pages for the specific task
SOURCE: domain pages matched by work_type, tags, or explicit agent mapping

LAYER: pitfalls (injected per domain)
SIZE: ~500-1,500 tokens
CONTENT: known pitfalls for the task's domain
SOURCE: docs/development/pitfalls/{domain}.md

INJECTION_SELECTION¶

METHOD: match task metadata against wiki page metadata

TASK has work_type → map to domain
TASK has tags → match against page tags
AGENT has domain expertise → always inject that domain's index
TASK references client → inject client-specific pages

EXAMPLE:

Task: "Fix API endpoint returning 500"
Agent: sandro
Injected:
  - sandro core identity (~1.2k tokens)
  - sandro role knowledge (~2.5k tokens)
  - domains/backend/index.md (~2k tokens)
  - domains/backend/hono-framework.md (~3k tokens)
  - development/pitfalls/infrastructure.md (~1k tokens)
  - client/{project}/technical-decisions.md (~1k tokens)
Total: ~11k tokens

INJECTION_BUDGET¶

MAX_INJECTION: 15,000 tokens (leaves room for task description + conversation)
PRIORITY_ORDER: core identity > pitfalls > task-specific domain > general domain
IF over budget THEN truncate lowest-priority pages, log warning

WIKI_BRAIN:KNOWLEDGE_LIFECYCLE¶

STAGES¶

CREATE → VALIDATE → INJECT → MONITOR → UPDATE → DEPRECATE

STAGE: create
TRIGGER: session learning extracted, discussion concluded, pitfall discovered
WHO: any agent (via session_summarizer) or human (direct edit)
OUTPUT: new wiki page or section added to existing page

STAGE: validate
TRIGGER: new knowledge page created
WHO: annegreet reviews for accuracy, completeness, format compliance
CHECK: does not contradict existing knowledge
CHECK: follows agentic format conventions
CHECK: tagged with correct metadata
CHECK: cross-references existing related pages

STAGE: inject
TRIGGER: agent starts task with matching domain
WHO: executor (automated)
HOW: JIT injection as described above

STAGE: monitor
TRIGGER: continuous (eltjo's monitoring loop)
WHO: eltjo tracks which pages are injected and whether agents follow the guidance
METRIC: injection frequency (how often is this page used?)
METRIC: override frequency (how often do agents deviate from the guidance?)

STAGE: update
TRIGGER: new learning contradicts or extends existing page
WHO: annegreet
RULE: always update in place, never create parallel page
RULE: add date stamp to updated sections

STAGE: deprecate
TRIGGER: knowledge no longer applicable (technology changed, process evolved)
WHO: annegreet
HOW: add status: deprecated to frontmatter + reason
RULE: deprecated pages are NOT deleted — moved to archive/ with redirect note
RULE: JIT injection skips deprecated pages

WIKI_BRAIN:CROSS_REFERENCING¶

INTERNAL_LINKS¶

FORMAT: relative wiki paths
EXAMPLE: See [pitfalls/networking](../../development/pitfalls/networking.md)

RULE: every page that references another domain MUST link to it
RULE: bidirectional links preferred (if A links to B, B should link to A)
RULE: broken links detected by MkDocs build — fix immediately

TAG_SYSTEM¶

PURPOSE: enable discovery beyond hierarchical structure
FORMAT: tags array in frontmatter
CONVENTION: lowercase, hyphenated, specific

GOOD_TAGS: [k3s-networking, redis-streams, jwt-auth]
BAD_TAGS: [infrastructure, important, see-also]

KNOWLEDGE_GRAPH¶

CONCEPT: wiki pages form a directed graph of knowledge dependencies
ANNEGREET_RESPONSIBILITY: maintain graph coherence (no orphan pages, no circular deps)
TOOL: MkDocs search index + custom script for orphan detection

# Find orphan pages (not linked from any other page)
find docs/ -name "*.md" | while read page; do
  basename=$(basename "$page")
  refs=$(grep -r "$basename" docs/ --include="*.md" -l | grep -v "$page" | wc -l)
  if [ "$refs" -eq 0 ] && [ "$basename" != "index.md" ]; then
    echo "ORPHAN: $page"
  fi
done

WIKI_BRAIN:SEARCH_OPTIMIZATION¶

SEARCH_TOOLS¶

TOOL: ge-ops/bin/wiki-search.sh <keyword>
PURPOSE: ranked keyword search across all wiki pages
RETURNS: page path + matching lines + relevance score

TOOL: MkDocs built-in search (lunr.js)
PURPOSE: full-text search via wiki web interface
ACCESSIBLE: http://wiki.ge-wiki.svc.cluster.local (port 8000/30080)

SEARCH_FRIENDLY_WRITING¶

RULE: use specific terms, not vague descriptions
GOOD: "k3s ClusterIP connection refused from pod"
BAD: "networking issue in container"

RULE: include common synonyms in page content
EXAMPLE: "Redis Streams (also: message queue, event bus, pub/sub)"

RULE: section headers should be searchable keywords
GOOD: ## REDIS:CONNECTION_POOLING
BAD: ## How We Connect

WIKI_BRAIN:STALENESS_DETECTION¶

WHAT_IS_STALENESS¶

DEFINITION: wiki content that is outdated, inaccurate, or no longer relevant
RISK: stale knowledge injected into agents causes incorrect behavior
SEVERITY: high — stale knowledge is worse than no knowledge (it actively misleads)

DETECTION_METHODS¶

METHOD: age-based (automated)
RULE: pages not updated in 90 days flagged for review
TOOL: script checks last_updated in frontmatter against current date
ACTION: annegreet reviews flagged pages

METHOD: contradiction-based (session learning)
TRIGGER: session learning contradicts injected wiki knowledge
DETECTION: session_summarizer flags contradiction
ACTION: annegreet investigates, updates or deprecates page

METHOD: usage-based (eltjo monitoring)
TRIGGER: page injected frequently but agents consistently override its guidance
DETECTION: eltjo correlates injection with agent output
ACTION: annegreet reviews — guidance may be wrong

METHOD: technology-based (version tracking)
TRIGGER: dependency update changes behavior (e.g., Next.js 14 → 15)
DETECTION: version numbers in page content compared against package.json
ACTION: annegreet flags pages referencing outdated versions

STALENESS_RESPONSE¶

IF stale AND easily fixable THEN annegreet updates immediately
IF stale AND needs research THEN annegreet creates evolution entry
IF stale AND domain-specific THEN annegreet notifies domain owner
IF stale AND contradicted by multiple sources THEN deprecate

WIKI_BRAIN:LEARNING_LOOP¶

THE_COMPLETE_LOOP¶

Dev session → PTY capture → session_summarizer → learnings
  → annegreet validates → wiki page created/updated
  → JIT injection into future sessions
  → future agents benefit from past learnings
  → new sessions refine or correct learnings
  → cycle continues

SESSION_SUMMARIZER¶

LOCATION: session_summarizer.py
MODEL: Claude Haiku (cost: ~$0.01-0.03 per session)
INPUT: PTY capture transcript from agent session
OUTPUT: structured learnings (what worked, what failed, new patterns)

OUTPUT_FORMAT:

{
  "session_id": "uuid",
  "agent": "agent_name",
  "learnings": [
    {
      "type": "pitfall",
      "domain": "infrastructure",
      "summary": "k3s ClusterIP unreachable from pods",
      "details": "Connection to 10.43.0.1:443 refused...",
      "confidence": 0.95
    }
  ],
  "contradictions": [],
  "confirmations": []
}

KNOWLEDGE_SYNTHESIZER¶

LOCATION: knowledge_synthesizer.py
FREQUENCY: every 6 hours
PURPOSE: detect cross-session patterns (same learning from multiple agents = high confidence)
OUTPUT: pattern records with confidence scores

IF pattern confidence >= 0.8 AND seen in 3+ sessions THEN promote to wiki page
IF pattern confidence < 0.5 THEN keep as tentative learning, do not inject
IF pattern contradicts existing wiki page THEN flag for annegreet review

FEEDBACK_TO_AGENTS¶

MECHANISM: LEARNINGS.md per agent (updated by annegreet)
CONTENT: recent learnings relevant to that agent
INJECTION: included in role_knowledge layer during JIT injection

WIKI_BRAIN:ANNEGREET_RESPONSIBILITIES¶

DAILY¶

TASK: review new session learnings from session_summarizer
TASK: validate and integrate confirmed learnings into wiki
TASK: respond to knowledge requests from other agents

WEEKLY¶

TASK: run staleness detection scan
TASK: review orphan page detection results
TASK: update cross-references for new pages
TASK: report knowledge health metrics to eltjo

ON_EVENT¶

TASK: process discussion precedent (see discussion-precedents.md)
TASK: handle formal spec storage (from Aimee, see TDD pipeline)
TASK: onboard new domain pages (from domain research sessions)

METRICS¶

METRIC: wiki page count (growth over time)
METRIC: injection frequency per page (usage)
METRIC: staleness ratio (stale pages / total pages)
METRIC: orphan count (should be 0)
METRIC: average confidence of learnings
TARGET: staleness ratio < 10%, orphan count = 0

WIKI_BRAIN:PITFALLS¶

PITFALL: creating duplicate pages for same topic
IMPACT: contradictory information, agents get different guidance depending on which page is injected
FIX: always search wiki before creating new page. Annegreet enforces uniqueness.

PITFALL: writing wiki pages in prose instead of agentic format
IMPACT: harder for JIT injection to extract relevant sections, higher token cost
FIX: follow agentic format conventions (KEY: value, IF/THEN, structured sections)

PITFALL: not deprecating outdated pages
IMPACT: stale knowledge actively misleads agents
FIX: staleness detection + annegreet weekly review

PITFALL: injecting too many pages (exceeding token budget)
IMPACT: important context crowded out, higher cost per task
FIX: respect 15,000 token injection budget, prioritize by relevance

PITFALL: session_summarizer hallucinating learnings
IMPACT: false knowledge enters wiki
FIX: annegreet validates every learning before wiki promotion. Confidence threshold.

PITFALL: wiki edits not triggering MkDocs rebuild
IMPACT: web interface shows stale content
FIX: MkDocs runs with --dirtyreload in development, full rebuild on deploy