wiki-maintain - SKILL.md Agent Skill

name: wiki-maintain description: Maintain the Babylon project wiki following the Karpathy LLM Wiki pattern. Use when ingesting new knowledge, updating cross-references, linting for contradictions, or keeping agent documentation current with code changes.

Wiki Maintenance Skill

Purpose

Maintain a persistent, compounding knowledge base for the Babylon project. The wiki lives in docs/agents/, ai-docs/, and .specify/. This skill ensures knowledge accumulates rather than being re-derived every session.

Architecture (Karpathy Pattern)

Three layers:

Raw Sources (immutable) — Code, specs, constitution, data catalog
Wiki (LLM-maintained) — docs/agents/*.md, ai-docs/*.yaml, .specify/plans/, .specify/specs/
Schema (this skill + AGENTS.md) — Tells the LLM how to structure and maintain the wiki

Operations

1. Ingest

When new information enters the project, integrate it into the wiki.

Trigger: After completing any significant work — new code, ratified specs, architectural decisions, data source additions.

Procedure:

Identify what changed — New/modified files, new concepts, new dependencies
Update relevant wiki pages — Read existing pages, update them with new information
Create new pages if needed — When a concept lacks its own page
Update cross-references — Link new pages to related existing pages
Update the index — Regenerate docs/agents/index.md
Append to the log — Record the ingest in docs/agents/log.md

Babylon-specific pages to maintain:

Page	When to Update
`docs/agents/architecture.md`	New systems, API changes, formula additions
`docs/agents/coding-standards.md`	New patterns, tool changes, convention updates
`docs/agents/testing.md`	New test patterns, fixture changes, marker additions
`docs/agents/commands.md`	New mise tasks, changed CLI interfaces
`docs/agents/gotchas.md`	New debugging lessons, common pitfalls discovered
`docs/agents/governance.md`	Workflow changes, branch policy updates
`ai-docs/decisions.yaml`	New ADRs ratified
`ai-docs/state.yaml`	Test counts, component status changes
`.specify/memory/constitution.md`	Only via `specification-govern` skill — never directly

Ingest Log Format (docs/agents/log.md):

## [YYYY-MM-DD] ingest | Brief Description

**Source**: What changed (PR, commit, spec ratification)
**Pages Updated**: List of wiki pages modified
**Pages Created**: List of new wiki pages
**Cross-references Added**: What now links to what
**Open Questions**: Anything unresolved

2. Query

Answer questions by reading the wiki, not by re-deriving from code.

Trigger: When asked about project structure, patterns, history, or "how does X work?"

Procedure:

Read the index — docs/agents/index.md to find relevant pages
Read relevant pages — Load 2-5 most relevant wiki files
Synthesize with citations — Quote specific files, don't hallucinate
If answer is incomplete — Flag gaps in the wiki for future ingest

Never answer from memory when the wiki contains the authoritative information.

3. Lint

Health-check the wiki for consistency.

Trigger: When explicitly asked, or when a page hasn't been updated in 30+ days.

Procedure:

Read the index — docs/agents/index.md
Check for contradictions — Scan pages for conflicting claims
Find orphan pages — Pages with no inbound links from other wiki pages
Identify stale claims — Claims that newer code/sources have superseded
Find missing cross-references — Concepts mentioned but not linked
Check index completeness — Every wiki page listed in index?
Report findings — List issues with recommended fixes

Lint Report Format:

## Wiki Lint Report — YYYY-MM-DD

### Contradictions
- [ ] Page A claims X, Page B claims not-X (lines N, M)

### Orphan Pages
- [ ] `docs/agents/foo.md` — no inbound links

### Stale Claims
- [ ] `docs/agents/bar.md` says System Y does Z, but code shows it does W

### Missing Cross-references
- [ ] Page C mentions "Dialectic Primitive" but doesn't link to constitution

### Recommended Actions
1. Fix contradiction by...
2. Link orphan page from...

Index Maintenance

docs/agents/index.md is the content-oriented catalog. Regenerate it after every ingest.

Format:

# Babylon Wiki Index

## Architecture
- [Architecture Overview](architecture.md) — Trinity, engine systems, formulas
- [Coding Standards](coding-standards.md) — Pydantic, TDD, commits, docstrings

## Operations
- [Testing](testing.md) — Test constants, factories, fixtures, markers
- [Commands](commands.md) — mise tasks reference
- [Gotchas](gotchas.md) — Common pitfalls and debugging lessons

## Governance
- [Governance](governance.md) — Git workflow, session continuity

## Specifications
- Plans: `.specify/plans/`
- Specs: `.specify/specs/`
- Constitution: `.specify/memory/constitution.md`
- Data Catalog: `.specify/memory/data-catalog.yaml`

## AI State
- Decisions: `ai-docs/decisions.yaml`
- Roadmap: `ai-docs/roadmap.md`
- State: `ai-docs/state.yaml`

Rules

Never modify the constitution (.specify/memory/constitution.md) through this skill. Use specification-govern for constitutional changes.
Never delete wiki pages without user approval. Orphan pages should be linked, not removed.
Always update the index after creating or significantly modifying any wiki page.
Always append to the log after every ingest operation.
Prefer updating existing pages over creating new ones. The wiki should be dense, not sprawling.
Cross-reference aggressively — Every concept should link to its authoritative definition.