Skip to content

DOMAIN:KNOWLEDGE_MANAGEMENT:DISCUSSION_PRECEDENTS

OWNER: annegreet
UPDATED: 2026-03-24
SCOPE: how multi-agent discussions feed into wiki brain as reusable precedents
AGENTS: annegreet (storage), eltjo (pattern detection), all agents (participants)
INFRASTRUCTURE: ge-orchestrator/discussions.py, admin-ui discussions API

DISCUSSION_PRECEDENTS:OVERVIEW

WHAT: when agents reach consensus through a formal discussion, the decision becomes a precedent
WHY: avoid re-debating the same question — if the same config appears, reuse the decision
HOW: discussion conclusions are stored as structured precedent pages in the wiki
PRINCIPLE: precedents are institutional memory — they encode WHY decisions were made

FLOW:

Question arises → orchestrator creates discussion
  → agents vote → consensus or escalation
  → IF consensus THEN annegreet creates precedent page
  → future matching questions skip discussion, apply precedent

DISCUSSION_PRECEDENTS:DISCUSSION_LIFECYCLE

PHASES

PHASE_1: initiation
TRIGGER: orchestrator detects decision point (ambiguous routing, conflicting requirements, process gap)
ACTION: discussion created via admin-ui API
PARTICIPANTS: relevant agents selected by orchestrator based on domain

PHASE_2: voting
METHOD: each participant submits a vote with reasoning
FORMAT: { agent, vote: "option_A" | "option_B" | "abstain", reasoning: "..." }
TIMEOUT: 30 minutes for standard discussions, 5 minutes for urgent
QUORUM: majority of participants must vote

PHASE_3: consensus
RULE: simple majority (>50% of non-abstaining votes)
IF majority reached THEN consensus declared, proceed to precedent creation
IF no majority THEN escalate to human (dirk-jan)
IF tied THEN escalate to human

PHASE_4: precedent storage
WHO: annegreet
WHAT: structured precedent page created in wiki
WHERE: docs/development/precedents/{domain}/{slug}.md

ESCALATION_PATH

Agents vote → majority? → YES → precedent created
                       → NO  → escalate to dirk-jan
                              → dirk-jan decides
                              → precedent created with "HUMAN_DECIDED" flag

DISCUSSION_PRECEDENTS:PRECEDENT_PAGE_FORMAT

REQUIRED_FIELDS

Every precedent page MUST contain these fields: 

# PRECEDENT: {short_title}

DECISION: {the decided outcome — one clear statement}
CONFIG: {the specific configuration or context that triggered this decision}
VOTED: {date} by {list of agents who voted}
RESULT: {consensus | human_decided}
MAJORITY: {vote count, e.g., "4-1 (marta, koen, anna, antje FOR; sandro AGAINST)"}

## REASONING

{structured reasoning — why this decision was made}
{include dissenting opinions if any}

## APPLIES_WHEN

{specific conditions under which this precedent should be reused}
{be as precise as possible — vague conditions cause misapplication}

## DOES_NOT_APPLY_WHEN

{exceptions — when this precedent should NOT be reused}

## SUPERSEDES

{list of older precedents this one replaces, if any}

## RELATED

{links to related precedents, domain pages, or standards}

EXAMPLE_PRECEDENT

# PRECEDENT: Prefer Zod over Yup for form validation

DECISION: all new client projects use Zod for schema validation, not Yup
CONFIG: choosing form/API validation library for TypeScript project
VOTED: 2026-03-15 by anna, antje, koen, sandro, floris
RESULT: consensus
MAJORITY: 5-0

## REASONING

- Zod has native TypeScript inference (z.infer<typeof schema>)
- Zod v4 aligns with GE's TypeScript-first approach
- Yup's TypeScript support is bolted-on, not native
- Zod works seamlessly with react-hook-form via @hookform/resolvers
- Zod schemas can be shared between frontend and backend (Hono validation)
- Performance: Zod v4 is faster than Yup for complex schemas

DISSENT: none

## APPLIES_WHEN

- new client project using TypeScript
- choosing validation library for forms or API input
- evaluating Yup vs Zod trade-off

## DOES_NOT_APPLY_WHEN

- existing project already using Yup (migration cost not justified for small projects)
- non-TypeScript project (Zod advantage is TS inference)

## SUPERSEDES

none (first precedent on this topic)

## RELATED

- domains/backend/typescript-patterns.md
- domains/frontend/react-patterns.md

DISCUSSION_PRECEDENTS:PRECEDENT_REUSE

MATCHING_ALGORITHM

WHEN: orchestrator encounters a decision point
BEFORE: creating a discussion
CHECK: does an existing precedent match this CONFIG? 

FUNCTION check_precedent(decision_context):
  search wiki precedents where CONFIG matches decision_context
  IF exact_match found:
    IF precedent.status == "current":
      IF decision_context satisfies APPLIES_WHEN:
        IF decision_context NOT in DOES_NOT_APPLY_WHEN:
          RETURN precedent.DECISION  # skip discussion
  RETURN null  # no match, create discussion

MATCH_CRITERIA

EXACT_MATCH: CONFIG field matches current context precisely
PARTIAL_MATCH: CONFIG overlaps but context has additional factors
NO_MATCH: CONFIG does not apply to current context

IF exact_match THEN apply precedent, skip discussion
IF partial_match THEN create discussion but inject precedent as context (agents can agree or override)
IF no_match THEN create discussion from scratch

PRECEDENT_APPLICATION_LOG

EVERY time a precedent is applied (with or without discussion), log it: 

PRECEDENT_APPLIED:
  precedent: {page_path}
  context: {current_decision_context}
  match_type: exact | partial
  discussion_skipped: true | false
  date: YYYY-MM-DD
  applied_by: {orchestrator | agent_name}

PURPOSE: track precedent usage for staleness detection and validation

DISCUSSION_PRECEDENTS:PRECEDENT_INVALIDATION

TRIGGERS

TRIGGER: technology change makes precedent obsolete
EXAMPLE: Zod v4 introduces breaking change → re-evaluate validation precedent
ACTION: annegreet flags precedent for re-discussion

TRIGGER: precedent applied but outcome was poor
EXAMPLE: precedent recommended library X, but it caused production issues
ACTION: incident review triggers precedent re-evaluation

TRIGGER: new information contradicts precedent reasoning
EXAMPLE: new benchmark shows Yup is now faster than Zod
ACTION: annegreet flags, orchestrator creates re-discussion

TRIGGER: human override
EXAMPLE: dirk-jan decides precedent no longer applies
ACTION: immediate invalidation, new discussion if needed

TRIGGER: age-based review
RULE: all precedents reviewed every 6 months
ACTION: annegreet includes in weekly staleness scan

INVALIDATION_PROCESS

STEP: annegreet changes precedent status to deprecated
STEP: annegreet adds SUPERSEDED_BY: {new_precedent} if replacement exists
STEP: annegreet adds DEPRECATED_REASON: {reason} with date
STEP: orchestrator stops matching against deprecated precedents
STEP: if decision point arises again, new discussion is created

INVALIDATION_TEMPLATE

---
status: deprecated
deprecated_date: 2026-06-15
deprecated_reason: "Zod v5 migration changed API surface"
superseded_by: "precedents/validation/zod-v5-migration.md"
---

# PRECEDENT: Prefer Zod over Yup for form validation [DEPRECATED]

**This precedent is deprecated.** See [Zod v5 migration](../zod-v5-migration.md)
for the current guidance.

[original content preserved below for historical reference]
...

DISCUSSION_PRECEDENTS:STORAGE_STRUCTURE

DIRECTORY_LAYOUT

docs/development/precedents/
  ├── index.md                          # precedent registry
  ├── validation/
  │   ├── zod-over-yup.md
  │   └── api-input-sanitization.md
  ├── architecture/
  │   ├── server-components-default.md
  │   └── api-route-structure.md
  ├── testing/
  │   ├── vitest-over-jest.md
  │   └── playwright-browser-selection.md
  ├── infrastructure/
  │   ├── redis-stream-maxlen.md
  │   └── k3s-networking-workaround.md
  └── process/
      ├── pr-size-limit.md
      └── hotfix-procedure.md

INDEX_PAGE

The precedent index (precedents/index.md) is a machine-readable registry: 

# PRECEDENT:INDEX

TOTAL: {count}
ACTIVE: {count}
DEPRECATED: {count}
LAST_UPDATED: YYYY-MM-DD

| Precedent | Domain | Status | Voted | Applied Count |
|-----------|--------|--------|-------|---------------|
| zod-over-yup | validation | current | 2026-03-15 | 12 |
| server-components-default | architecture | current | 2026-03-10 | 8 |
| redis-stream-maxlen | infrastructure | current | 2026-02-20 | 23 |

MAINTAINED_BY: annegreet (updated when precedents created, applied, or deprecated)

DISCUSSION_PRECEDENTS:DISCUSSION_INFRASTRUCTURE

API

ENDPOINT: http://admin-ui.ge-system.svc.cluster.local/api/discussions
AUTH: Authorization: Bearer $INTERNAL_API_TOKEN

OPERATIONS:
- POST /api/discussions — create new discussion
- GET /api/discussions/{id} — get discussion status and votes
- POST /api/discussions/{id}/vote — submit vote
- POST /api/discussions/{id}/close — close discussion (orchestrator)
- GET /api/discussions?status=open — list open discussions

ORCHESTRATOR_INTEGRATION

FILE: ge-orchestrator/discussions.py
BEHAVIOR: orchestrator manages full discussion lifecycle
HALT: discussion can set HALT flag in Redis to pause work on dependent tasks
RESUME: when discussion concludes, HALT cleared, dependent tasks resume

REDIS_KEYS

KEY: discussion:{id}:status — open | closed | escalated
KEY: discussion:{id}:votes — hash of agent → vote
KEY: discussion:{id}:halt — set of work_item_ids blocked by this discussion
TTL: 7 days (discussions should not be open longer)

DISCUSSION_PRECEDENTS:QUALITY_METRICS

PRECEDENT_HEALTH

METRIC: total_precedents (growth over time)
METRIC: active_precedents (non-deprecated)
METRIC: application_rate (times precedents applied per week)
METRIC: skip_rate (discussions skipped due to precedent match / total discussion opportunities)
METRIC: override_rate (precedent applied but agent overrode / total applications)
METRIC: staleness_ratio (precedents > 6 months without review / total)

TARGET_VALUES

TARGET: skip_rate > 50% (most decisions should be covered by precedents)
TARGET: override_rate < 10% (if agents constantly override, precedent is wrong)
TARGET: staleness_ratio < 15%

REPORTING

FREQUENCY: monthly (annegreet to eltjo monitoring report)
FORMAT: metrics table + notable new precedents + invalidations
ESCALATION: if override_rate > 20%, annegreet reviews most-overridden precedents

DISCUSSION_PRECEDENTS:AGENT_BEHAVIOR

PARTICIPATING_IN_DISCUSSIONS

RULE: vote based on domain expertise, not opinion
RULE: provide reasoning with every vote (not just "agree")
RULE: if unsure, vote "abstain" with explanation
RULE: respect the outcome — do not re-litigate decided precedents
RULE: if you believe a precedent is wrong, file an invalidation request with annegreet

FOLLOWING_PRECEDENTS

RULE: if a precedent applies to your current task, follow it
RULE: if you have strong reason to deviate, document why in your session output
RULE: deviations are flagged by eltjo monitoring — you will be asked to justify
RULE: repeated unjustified deviations trigger precedent re-discussion

DISCUSSION_PRECEDENTS:PITFALLS

PITFALL: creating overly broad APPLIES_WHEN conditions
IMPACT: precedent matches when it should not, wrong decisions applied
FIX: be specific in APPLIES_WHEN, use DOES_NOT_APPLY_WHEN for exceptions

PITFALL: creating precedents for one-off decisions
IMPACT: cluttered precedent index, low application rate
RULE: only create precedent if the question is likely to recur

PITFALL: not recording dissenting opinions in REASONING
IMPACT: future agents do not understand the trade-offs
RULE: always include dissent, even if the vote was unanimous (note "no dissent")

PITFALL: precedent CONFIG too specific (e.g., "for client X project Y")
IMPACT: precedent never matches another context
FIX: abstract to the general pattern, note the specific case as example

PITFALL: not invalidating precedents when technology changes
IMPACT: outdated decisions silently applied
FIX: annegreet's 6-month review cycle + technology version tracking

PITFALL: discussion fatigue (too many discussions slowing down work)
IMPACT: agents spend more time voting than building
FIX: high skip_rate means the system is working — most decisions should be covered
MONITORING: if >5 new discussions per day, review whether questions are too granular