playbooks

home / skills / commontoolsinc / labs / knowledge-base

knowledge-base skill

/.claude/skills/knowledge-base

This skill establishes and enforces a source hierarchy guiding conflict resolution among specs, code, and documentation for Oracle and Corrector agents.

npx playbooks add skill commontoolsinc/labs --skill knowledge-base

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.8 KB
---
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:

1. **`docs/glossary.md`** - Terminology (Cell, Charm, Space, Spell, etc.)
2. **`docs/specs/recipe-construction/overview.md`** - Authoritative system design
3. **`AGENTS.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 engine
- `packages/runner/src/builder/` - Compilation
- `packages/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

1. Check specs first (`docs/specs/`)
2. Look at working code (tests, patterns)
3. Read runtime implementation
4. Use docs/common as learning guide only
5. If still unclear, surface the conflict explicitly

Overview

This skill is a shared knowledge-base foundation for Oracle and Corrector agents that defines the authoritative source hierarchy for resolving conflicts between documentation, code, and specs. Load this skill first when investigating how the system works so agents apply a consistent priority order and surface unresolved contradictions.

How this skill works

The skill inspects available specifications, tests/patterns, runtime code, and plain-text docs to determine which source should be trusted for a given question. It enforces the rule that concrete artifacts outrank abstract guidance and provides a step-by-step decision flow so agents can justify their conclusions. When ambiguity remains, the skill marks the conflict for human review.

When to use it

  • Investigating system behavior when documentation, tests, or code disagree
  • Determining which source to follow when implementing or refactoring features
  • Triaging bug reports that reference contradicting guides or specs
  • Reviewing design decisions where intent and implementation diverge
  • Preparing authoritative responses from Oracle or validating Corrector fixes

Best practices

  • Always check docs/specs first for unambiguous intent before consulting other sources
  • Use tests and pattern examples to confirm how the system actually behaves
  • Treat runtime code as the source of truth for current behavior and edge cases
  • Use plain-text docs only as learning material and validate any operational claims
  • When conflict remains, explicitly surface the discrepancy and recommend human verification

Example use cases

  • A user reports behavior that differs from a tutorial: verify tests and runtime code before updating the tutorial
  • A spec describes a new API but runtime code hasn’t been updated: follow the spec for design discussions and note the implementation gap
  • A pattern example demonstrates a workaround not present in the spec: prefer the test-proven approach for immediate fixes
  • Automated agent producing a remediation: base changes on tests and runtime code, then adjust docs to match

FAQ

What if specs are missing or incomplete?

Fallback to working code and tests for concrete behavior. Flag the missing spec as an action item.

Which has higher authority: tests or runtime code?

Tests demonstrate intended behavior; runtime code shows actual behavior. Use tests to interpret intent, but trust runtime code for what the system currently does.