knowledge-base
Shared foundation for Oracle & Corrector agents. Establishes the source hierarchy for resolving conflicts between documentation, code, and specs. Load this skill first when investigating how the system works.
When & Why to Use This Skill
The Knowledge Base Foundation skill establishes a definitive source hierarchy to resolve contradictions between documentation, specifications, and source code. It serves as the essential starting point for system investigation, ensuring that AI agents and developers prioritize concrete evidence—like technical specs and working tests—over potentially outdated plain-text guides.
Use Cases
- Conflict Resolution: Determining the ground truth when system documentation contradicts the actual behavior observed in the codebase.
- System Onboarding: Providing a structured framework for agents or new developers to navigate complex repositories by defining which files hold the highest authority.
- Technical Auditing: Validating that runtime implementation aligns with original technical specifications and identifying where documentation needs updates.
- Decision Making: Using the 'Concrete beats abstract' rule to make informed architectural choices based on proven patterns and tests rather than speculation.
| name | knowledge-base |
|---|---|
| description | Shared foundation for Oracle & Corrector agents. Establishes the source hierarchy for resolving conflicts between documentation, code, and specs. Load this skill first when investigating how the system works. |
Knowledge Base Foundation
Before You Start
Read these docs to orient yourself:
docs/glossary.md- Terminology (Cell, Charm, Space, Spell, etc.)docs/specs/recipe-construction/overview.md- Authoritative system designAGENTS.md- Documentation reading list and codebase guidelines
Source Hierarchy
When sources conflict, this is the authoritative order:
1. Specs (Highest Authority)
docs/specs/ - Technical specifications with unambiguous intent
When specs contradict other docs, specs win.
2. Working Code
Tests and patterns that demonstrate actual behavior:
packages/patterns/- Pattern examples showing what works**/test/**- Test files proving expected behavior
These show reality, not aspirations.
3. Runtime Code
Core system implementation:
packages/runner/- Execution enginepackages/runner/src/builder/- Compilationpackages/memory/- Storage layer
Code is always right about what it does.
4. Plain Text Docs (Lowest Authority)
docs/common/ - Guides, tutorials, learning materials
Good for learning, but may contain outdated or speculative information. Validate against code when precision matters.
The Rule
Concrete beats abstract. Specifications beat speculation. Code beats comments. Tests beat documentation.
When Sources Conflict
- Check specs first (
docs/specs/) - Look at working code (tests, patterns)
- Read runtime implementation
- Use docs/common as learning guide only
- If still unclear, surface the conflict explicitly