Epistemic Beliefs

Create formal beliefs that capture project decisions with evidence and reasoning.

Proactive Belief Detection

Do not wait for the user to say "create a belief". Watch for:

When you notice these patterns, ask the user:

"This sounds like a belief worth capturing: '{statement}'. Should I create it?"

If user confirms, proceed with belief creation. If user declines, move on.

When to Create Beliefs

• User explicitly requests: "create a belief", "add this as a belief"
• You notice a design decision or principle (proactive)
• A pattern is repeated multiple times (proactive)
• Distilling session learnings into persistent knowledge
• Capturing architectural decisions with justification
• Recording design principles that guide future work

Belief Creation Process

Step 1: Gather Information

Before creating a belief, ensure you have:

• Statement: One clear sentence expressing the belief
• Evidence: At least one source — use [[wikilinks]] for verifiable references. The script auto-prepends the active session ID (e.g., [[session-20260131-150141]]:) so every evidence line traces to the conversation where it was articulated
• Persona: Usually "architect" for project-level decisions

Do NOT guess a confidence score. Confidence is computed by patina scrape from real data:

• Use metrics: How many other beliefs cite this? How many sessions reference it?
• Truth metrics: How many evidence links? Do they resolve to real files? Defeated attacks?

Step 2: Use the Creation Script

Execute the belief creation script with required fields:

.claude/skills/epistemic-beliefs/scripts/create-belief.sh \
  --id "belief-id-here" \
  --statement "One sentence belief statement" \
  --persona "architect" \
  --evidence "[[session-YYYYMMDD-HHMMSS]] - description (weight: 0.9)" \
  --facets "domain1,domain2"

The script will:

1. Validate all required fields
2. Generate proper YAML frontmatter (no fake confidence scores)
3. Create the belief file in layer/surface/epistemic/beliefs/
4. Report success or validation errors

Step 3: Enrich the Belief

After creation, edit the file to add:

• Additional evidence links — use [[wikilinks]] so patina scrape can verify them
• Supports relationships — beliefs this supports (e.g., [[measure-first]])
• Attacks relationships — beliefs this defeats
• Attacked-By relationships — known challenges to this belief
• Applied-In examples — concrete code/architecture where this belief was applied

The more connections you add, the higher the computed use/truth metrics will be.

Step 4: Run Scrape

After creating and enriching, run patina scrape to compute metrics. The belief will show up in patina scry with real numbers.

Belief Format Reference

See references/belief-example.md for the complete format.

Key fields:

• id: Lowercase, hyphenated identifier (e.g., sync-first)
• persona: Epistemic agent (usually architect)
• facets: Domain tags (e.g., rust, architecture)
• entrenchment: low, medium, high, or very-high
• status: active, scoped, defeated, or archived
• endorsed: true if user explicitly created or confirmed

How Metrics Work (E4)

Metrics are computed by patina scrape, not guessed by the LLM:

A strong belief has high use (many citations) AND high truth (verified evidence). A weak belief has low use and unverified evidence — it's an assertion, not yet tested.

Verification Queries

Structural beliefs can include a ## Verification section with deterministic queries that prove the claim against the project's knowledge database. Queries run automatically during patina scrape.

Query Format

````markdown

Verification

```verify type="sql" label="No async functions" expect="= 0" SELECT COUNT(*) FROM functionfacts WHERE isasync = 1

```verify type="assay" label="insert_event is infrastructure" expect=">= 5"
callers --pattern "insert_event" | count(distinct file)

```verify type="temporal" label="Commit count" expect=">= 100" derive-moments | summary.total_commits

````

### Query Types

| Type | Syntax | When to use |
|------|--------|-------------|
| `sql` | Standard SELECT query | Counts, aggregates, existence checks |
| `assay` | `<command> --pattern "<pat>"` with optional `\| count(distinct <field>)` | Architecture claims (callers, importers) |
| `temporal` | `derive-moments \| summary.<field>` | Commit patterns (total_commits, rewrite, migration) |

### Assay Commands

| Command | What it queries | Distinct fields |
|---------|----------------|-----------------|
| `callers` | call_graph WHERE callee matches | file, caller, callee, call_type |
| `callees` | call_graph WHERE caller matches | file, caller, callee, call_type |
| `functions` | function_facts WHERE name matches | file |
| `imports` | import_facts WHERE import_path matches | file |
| `importers` | import_facts WHERE file matches | file |

### Expectation Operators

`= N`, `> N`, `>= N`, `< N`, `<= N` — compared against the single numeric result.

### When NOT to Add Verification

Process beliefs (methodology, workflow, evaluation principles) correctly have no structural
proof — testimony is the right evidence type. Examples: spec-first, measure-first,
read-code-before-write. Don't force SQL queries onto process beliefs; they produce noise.

### Available Tables

See `references/verification-schema.md` for the full schema reference.

## Validation Rules

The creation script enforces:
- ID must be lowercase with hyphens only
- Statement must be non-empty
- At least one evidence source required
- Persona must be specified
- `--confidence` is accepted but ignored (deprecated)