Xp update

xp-update

Write directly, then show the marker snippet. No exploring. Session knowledge only.

Precondition

.xp/db.jsonl must exist. If not → call /xp-index first.

Purpose

The XP-System is a semantic blueprint of the codebase. Each entry describes a labeled symbol so that a new agent, after one grep, understands within 30 seconds what it is, what it's connected to, and what isn't in the code.

Not exception knowledge. Baseline knowledge.

Process

1. What gets entered?

Every symbol that was tagged with an @xp marker in this session, or already carries one whose note is outdated or incomplete.

An entry answers three questions:

Question	What belongs in it
What is it?	Semantic role, not syntax — what the symbol means in the system
What does it connect to?	Direct dependencies, consumers, related concepts in the system
What isn't in the code?	Implicit contracts, naming discrepancies, edge cases, traps

2. Filter

Check	Result
Already in db.jsonl? (grep "slug" .xp/db.jsonl)	Upsert — old line gets replaced
Entry outdated / irrelevant?	Actively delete the line (upsert without appending) or omit it
Would the note add nothing beyond the readable code?	Add it anyway — semantic role + connections still count

3. Write the entry (upsert)

Format:

{"id": "domain:slug", "keywords": ["natural-language", "search", "terms"], "note": "Semantic role. Connections + why. Traps or implicit contracts.", "files": ["src/relevant.ts"], "file_hash": "abc123", "updated": "YYYY-MM-DD"}

keywords — natural-language terms from how the task was described, not code symbols. Goal: grep -i "ordering" hits the entry sequencer:resolve-chain. At least 3, at most 8 keywords per entry.

Determine the file hash:

git hash-object src/relevant.ts

Upsert — replace existing id, append new ones:

python3 -c "
import json, sys
new = json.loads(sys.argv[1])
lines = [l for l in open('.xp/db.jsonl') if json.loads(l)['id'] != new['id']]
lines.append(json.dumps(new, ensure_ascii=False) + '\n')
open('.xp/db.jsonl', 'w').writelines(lines)
" '<JSON>'

No appending without checking first. No status: obsolete. No duplicates.

The note — density over completeness:

Everything in one or two sentences. Three aspects, no filler.

❌ "Shape is an interface in types.ts" — syntax, not semantics ❌ "Refactored Shape today" — session diary ✅ "Central canvas data structure — stored in the DB as canvas_object (naming discrepancy). ShapeNormalizer must run before every render call, or it crashes. Consumers: RenderEngine, ExportService." — role + connections + trap ✅ "Single entry point for all API errors — handling elsewhere is not caught. Connects to Logger and ResponseBuilder. Naming convention: E_USER_ prefix for user-facing errors." — semantics + topology + contract

4. Split vs. merge

One entry = one precise hit. Cramming multiple facts into one note creates exactly the noise the XP-System is meant to avoid: someone searching for _frameAssignments would otherwise also get name-migration context along with it.

Split when:

• the facts can become true/done independently of each other (one can be finished while the others aren't)
• a user would plausibly search for only one of the facts, not all of them

Merge when:

• the facts are inseparable — neither makes sense without the other
• one fact without the other would be misleading

Cluster term: when several slugs belong to the same effort, add a shared term to all their keyword arrays (e.g. "frame-labels-rollout"). A broad search then hits all of them; a precise search hits only one. No depends_on field needed — the domain prefix in the id (frame-labels:) acts as an implicit cluster when grepping.

5. Display

Show all new or changed entries.