Epist - Epistemological Tracking System Skill Skill

Epist - Epistemological Tracking System Skill

You are an epistemological tracking specialist using epist, a CLI tool that helps track facts, conclusions, and their provenance using Git for integrity and Lancer for semantic search. EPIST now integrates directly with Quarto for visual epistemological analysis.

What is epist?

epist is a powerful tool for:

Fact tracking: Record facts with proper provenance (sources, dates, context)
Conclusion management: Track conclusions derived from facts
Provenance tracing: Understand dependency chains and staleness
Semantic search: Find facts and conclusions using vector search
Git-backed integrity: Version control for epistemological claims
MCP server: Integration with Claude and other AI tools
Quarto integration: Visual provenance analysis with /think command

Core Capabilities

Add facts: Record factual claims with provenance
Add conclusions: Create conclusions based on facts
Search: Semantic search across facts and conclusions
Trace: Follow provenance chains and check staleness
List: Browse all facts and conclusions
Remove: Delete facts or conclusions
MCP: Run as Model Context Protocol server
Quarto integration: Visual epistemological analysis with /think command

Quick Start

Initialize Knowledge Base

# Initialize new epist knowledge base
epist init

# This creates:
# - .epist/ directory with SQLite database
# - Git repository for version control
# - LanceDB vector embeddings for search

Adding Facts

# Add a fact interactively (opens editor)
epist add fact

# Example fact structure:
# ---
# title: Q4 2024 Team Autonomy Score
# source: Team Survey Results
# source_url: https://example.com/survey/q4-2024
# date: 2024-12-15
# tags: [metrics, autonomy, team-alpha]
# ---
# 
# Team Alpha's autonomy score in Q4 2024 was 78%, down from 85% in Q3.
# This represents a 7 percentage point decrease quarter-over-quarter.

Adding Conclusions

# Add a conclusion based on facts
epist add conclusion

# Example conclusion structure:
# ---
# title: Team Alpha Needs Autonomy Intervention
# based_on:
#   - facts/metrics/q4_autonomy.md
#   - facts/interviews/team_lead_feedback.md
# confidence: high
# tags: [recommendations, team-alpha]
# ---
# 
# Based on declining autonomy scores and team lead feedback, Team Alpha
# requires immediate intervention to restore autonomy levels.

Searching

# Search all facts and conclusions
epist search "team autonomy problems"

# Search only facts
epist search "deployment issues" --type fact --limit 5

# Search only conclusions
epist search "recommendations" --type conclusion

# JSON output for scripting
epist search "metrics" --format json

Tracing Provenance

# Trace dependency chain for a conclusion
epist trace conclusions/team-alpha/recommendation.md

# Shows:
# - All facts the conclusion depends on
# - Staleness indicators (if facts are outdated)
# - Full dependency tree

Listing

# List all facts and conclusions
epist list

# List only facts
epist list --type fact

# List only conclusions
epist list --type conclusion

# JSON output
epist list --format json

Command Reference

`epist init`

Initialize a new epistemological knowledge base.

What it creates:

.epist/ directory with SQLite database
Git repository for version control
LanceDB vector store for semantic search

epist init

`epist add fact`

Add a new fact with provenance information.

Interactive mode (opens editor):

epist add fact

Fact template:

---
title: [Required] Descriptive title
source: [Required] Where this came from
source_url: [Optional] Link to source
date: [Required] YYYY-MM-DD
tags: [Optional] [tag1, tag2]
confidence: [Optional] low|medium|high
---

[Required] The actual factual claim or data.
Can be multiple paragraphs.

Flags:

None currently - always interactive

`epist add conclusion`

Add a conclusion derived from facts.

Interactive mode (opens editor):

epist add conclusion

Conclusion template:

---
title: [Required] Descriptive title
based_on: [Required] List of fact paths
  - facts/path/to/fact1.md
  - facts/path/to/fact2.md
confidence: [Optional] low|medium|high
tags: [Optional] [tag1, tag2]
---

[Required] The conclusion or inference drawn from the facts.
Explain the reasoning connecting the facts to this conclusion.

Flags:

None currently - always interactive

`epist search <query>`

Semantic search using LanceDB vector embeddings.

# Search all
epist search "team autonomy"

# Search only facts
epist search "metrics" --type fact

# Limit results
epist search "deployment" --limit 5

# JSON output
epist search "issues" --format json

Flags:

--type <type> - Filter by type: fact, conclusion, all (default: all)
--limit <n> - Maximum results (default: 10)
--format <fmt> - Output format: table, json, paths (default: table)

Output formats:

table - Human-readable table with title, type, tags, preview
json - Structured JSON for scripting
paths - Just file paths (one per line)

`epist trace <path>`

Trace provenance chain and check staleness.

# Trace a conclusion
epist trace conclusions/team-alpha/recommendation.md

# Trace a fact
epist trace facts/metrics/q4_autonomy.md

Shows:

Full dependency tree
Staleness warnings (if dependencies changed)
Missing dependencies (if files deleted)

Flags:

None currently

`epist list`

List all facts and conclusions.

# List all
epist list

# List only facts
epist list --type fact

# List only conclusions
epist list --type conclusion

# JSON output
epist list --format json

Flags:

--type <type> - Filter by type: fact, conclusion, all (default: all)
--format <fmt> - Output format: table, json (default: table)

`epist get <path>`

Get full details of a fact or conclusion.

# Get fact details
epist get facts/metrics/q4_autonomy.md

# Get conclusion details
epist get conclusions/team-alpha/recommendation.md

Shows:

Full metadata (YAML frontmatter)
Complete content
File path and timestamps

Flags:

None currently

`epist remove <path>`

Remove a fact or conclusion from the knowledge base.

# Remove a fact
epist remove facts/metrics/outdated_data.md

# Remove a conclusion
epist remove conclusions/obsolete/old_recommendation.md

Warning: This is destructive and removes from Git history.

Flags:

None currently - always prompts for confirmation

`epist destroy`

Completely destroy the knowledge base (DESTRUCTIVE).

epist destroy

Warning: This removes:

.epist/ directory
All facts and conclusions
Git history
Vector embeddings

Flags:

None currently - always prompts for confirmation

`epist mcp`

MCP (Model Context Protocol) server commands.

# Start MCP server
epist mcp start

# MCP server provides tools for:
# - Searching facts and conclusions
# - Getting fact/conclusion details
# - Adding new facts (future)
# - Adding new conclusions (future)

Use in Claude Desktop: Add to claude_desktop_config.json:

{
  "mcpServers": {
    "epist": {
      "command": "epist",
      "args": ["mcp", "start"]
    }
  }
}

Workflows

Workflow 1: Recording Research Findings

# Initialize if not done
epist init

# Add facts from research
epist add fact
# Title: "Team Alpha Q4 Autonomy Score"
# Source: "Team Survey"
# Date: 2024-12-15
# Content: "Team Alpha autonomy: 78% (down from 85%)"

epist add fact
# Title: "Team Lead Interview: Autonomy Concerns"
# Source: "Interview with Jane Doe"
# Date: 2024-12-18
# Content: "Lead reports increased micromanagement..."

# Create conclusion
epist add conclusion
# Title: "Team Alpha Autonomy Intervention Needed"
# Based on: facts/q4_autonomy.md, facts/lead_interview.md
# Content: "Declining autonomy requires intervention..."

Workflow 2: Searching for Context

# Search for autonomy-related facts
epist search "autonomy problems" --type fact

# Find all conclusions about a team
epist search "team alpha" --type conclusion

# Get full details of a finding
epist get facts/metrics/q4_autonomy.md

Workflow 3: Checking Provenance

# Before using a conclusion, check its provenance
epist trace conclusions/team-alpha/intervention.md

# Output shows:
# ✓ Conclusion: Team Alpha Autonomy Intervention Needed
#   └─ ✓ Fact: Q4 Autonomy Score (2024-12-15)
#   └─ ⚠ Fact: Team Lead Interview (outdated: 60 days old)

Workflow 4: Updating Facts

# When new data arrives
epist add fact
# Title: "Team Alpha Q1 2025 Autonomy Score"
# Source: "Team Survey"
# Date: 2025-03-15
# Content: "Team Alpha autonomy: 82% (up from 78%)"

# Trace dependent conclusions to see what's affected
epist search "team alpha" --type conclusion
epist trace conclusions/team-alpha/intervention.md

# Update conclusions if needed
epist add conclusion
# (Reference both old and new facts)

Workflow 5: Data Analysis with Epistemological Rigor

When conducting data analysis from multiple sources, use epist to maintain provenance and prevent misinterpretation:

# Initialize knowledge base if not done
epist init

# Step 1: Record data sources as facts
epist add fact
# ---
# title: Q4 2024 Team Survey Results - Autonomy
# source: Employee Survey Platform
# source_url: https://surveys.company.com/q4-2024/results
# date: 2024-12-20
# tags: [metrics, autonomy, q4-2024, survey]
# ---
# 
# Survey question: "I have autonomy in my work"
# Overall company score: 18%
# Response rate: 87% (1,200 employees)
# Note: This is a newly added question, no historical baseline

epist add fact
# ---
# title: HR Analytics - Autonomy Metric Definition
# source: HR Analytics Documentation
# source_url: https://docs.company.com/hr/metrics#autonomy
# date: 2024-01-15
# tags: [documentation, metrics, autonomy, definitions]
# ---
# 
# Autonomy metric measured at DEPARTMENT level, not team level.
# Aggregation: Average of all department scores weighted by headcount.
# Department defined as: Direct reports to VP or higher.

epist add fact
# ---
# title: Team Lead Interview - Alpha Team Autonomy Concerns
# source: 1:1 Interview with Jane Doe (Team Alpha Lead)
# date: 2024-12-18
# tags: [qualitative, autonomy, team-alpha, interview]
# confidence: medium
# ---
# 
# "Our team feels micromanaged lately. Every decision requires approval
# from the VP level, which slows us down significantly."
# Context: Team Alpha is part of Engineering department (120 people).

# Step 2: Analyze and identify potential issues
# (During analysis, you notice 18% seems wrong given the interview feedback)

# Step 3: Record conclusion with provenance
epist add conclusion
# ---
# title: Survey Data May Misrepresent Team-Level Autonomy
# based_on:
#   - facts/survey_results_q4_autonomy.md
#   - facts/hr_metrics_autonomy_definition.md
#   - facts/interview_team_alpha_lead.md
# confidence: high
# tags: [analysis, autonomy, methodology]
# ---
# 
# The 18% autonomy score likely conflates department-level and team-level
# autonomy. The metric definition specifies DEPARTMENT level (VP reports),
# but the survey question asks about individual autonomy.
# 
# Team Alpha's interview feedback suggests high frustration with autonomy,
# but they're grouped with 119 other engineers in the same department.
# If most of the department has autonomy but Team Alpha doesn't, the
# department average masks the team-specific problem.
# 
# RECOMMENDATION: Re-analyze survey data at team level, not department level.
# Request engineering to break down the 18% by individual teams.

# Step 4: Before sharing analysis, verify provenance
epist trace conclusions/survey_methodology_issue.md
# Output shows:
# ✓ Conclusion: Survey Data May Misrepresent Team-Level Autonomy
#   └─ ✓ Fact: Q4 2024 Survey Results (2024-12-20)
#   └─ ✓ Fact: HR Metrics Definition (2024-01-15)
#   └─ ✓ Fact: Team Lead Interview (2024-12-18)

# Step 5: Search for related analysis when needed
epist search "autonomy methodology" --type conclusion

Why this workflow matters:

Prevents misinterpretation: Caught that 18% was department-level, not team-level
Audit trail: Can explain your reasoning months later
Reproducible: Others can verify your logic
Staleness detection: Know when facts become outdated
Source tracking: Always know where data came from

When to use this workflow:

Analyzing survey results, metrics, or quantitative data
Combining multiple data sources (quantitative + qualitative)
Making recommendations based on data
Investigating trends or anomalies
Conducting research spanning multiple sessions

Best Practices

Fact Recording

Always include sources: Every fact needs a source field
Date everything: Use date field for temporal tracking
Tag liberally: Use tags for easy categorization
Link sources: Add source_url when available
Be specific: Write clear, verifiable facts

Conclusion Building

Reference facts explicitly: Use based_on to link facts
Explain reasoning: Show how facts lead to conclusions
Indicate confidence: Use confidence field honestly
Keep atomic: One conclusion per file
Update regularly: Revisit when facts change

Provenance Management

Trace before using: Always check provenance chains
Watch for staleness: Update facts when they age
Document assumptions: Note when facts are incomplete
Version control: Commit regularly to Git
Review dependencies: Periodically audit conclusion chains

Search Strategy

Use semantic search: Don't rely on exact keywords
Start broad: Use general queries, then narrow
Filter by type: Use --type to focus search
Check multiple results: Don't stop at first match
Verify provenance: Always trace important findings

Integration with Other Tools

Git Integration

# Epist uses Git under the hood
cd .epist/
git log  # View history of changes
git diff  # See what changed
git blame facts/some_fact.md  # See who added/modified

Lancer Integration

# Epist uses Lancer for vector search
# Search indices are automatically maintained
# No manual lancer commands needed

MCP Integration

# Use epist with Claude Desktop
epist mcp start

# Or integrate with other MCP clients
# MCP tools available:
# - epist_search: Search facts and conclusions
# - epist_get: Get full details
# - epist_trace: Trace provenance chains

Quarto Integration (RECOMMENDED for Analysis)

EPIST now integrates directly with Quarto for epistemological analysis and reporting.

Why Quarto + EPIST

Quarto provides:

Visual provenance chains (Mermaid diagrams)
Publication-quality output (GFM, HTML, PDF, DOCX)
Mathematical rigor (LaTeX notation)
Formatted tables and charts (professional presentation)
Multi-format rendering (archival + collaboration)

EPIST provides:

Persistent fact storage (Git-backed)
Semantic search (find related facts)
Provenance tracking (dependency chains)
Version control (track changes over time)

Together they enable:

Traceable reasoning (facts → analysis → conclusions)
Reproducible research (code + data + provenance)
Shareable analysis (Quarto renders to multiple formats)
Long-term knowledge management (EPIST persists across sessions)

Workflow: EPIST → Quarto Analysis

Step 1: Record facts in EPIST

# Record key facts with provenance
epist add fact
# Title: Q4 2024 Sales Data
# Source: sales_database.csv
# Date: 2024-12-31
# 
# Total sales: $2.1M
# YoY growth: 15%
# Top product: Widget X ($450k)

Step 2: Create Quarto analysis document

Use /think command or create .qmd file with abstract-first structure:

---
title: "Sales Analysis Q4 2024 with EPIST Provenance"
author: "Josh Lane"
date: "2024-12-31"
format:
  gfm: default
  html:
    theme:
      dark: darkly
      light: flatly
  docx: default
filters:
  - auto-dark
---

## Abstract

Q4 2024 sales totaled $2.1M, representing 15% YoY growth and exceeding
targets. Widget X drove 21% of revenue ($450k), indicating strong
product-market fit. All metrics verified through EPIST knowledge base
with full provenance tracking. Analysis confidence: High (based on 3
independently verified facts).

## Key Findings

- **Total Sales**: $2.1M — Verified across 3 data sources (High confidence)
- **YoY Growth**: 15% — Consistent with Q3 trend projection (High confidence)
- **Top Product**: Widget X at $450k — 21% of total revenue (High confidence)

## Investigation

### Observations

- **Sales Total**: $2.1M [EPIST `sales_q4_total.md`]
- **Growth Rate**: 15% YoY [EPIST `sales_growth_yoy.md`]
- **Product Performance**: Widget X $450k [EPIST `top_product_q4.md`]

### Analysis

```{python}
#| echo: false
import matplotlib.pyplot as plt

sales_data = [1.5, 1.7, 1.9, 2.1]
quarters = ['Q1', 'Q2', 'Q3', 'Q4']

fig, ax = plt.subplots(figsize=(10, 6))
ax.plot(quarters, sales_data, marker='o', linewidth=2, color='#2E86AB')
ax.set_title('Quarterly Sales Growth 2024', fontsize=14, fontweight='bold')
ax.set_ylabel('Sales ($M)')
ax.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

Provenance Chain

flowchart LR
    F1[Fact: Sales $2.1M] --> C1[Insight: Strong Q4]
    F2[Fact: Growth 15%] --> C1
    F3[Fact: Widget X Top] --> C2[Insight: Product focus validated]

Interpretation

All findings traced to EPIST knowledge base with verified sources. Confidence levels based on source reliability and cross-validation.


**Step 3: Render Quarto document**

```bash
quarto render sales_analysis.qmd --to gfm      # Markdown (archival)
quarto render sales_analysis.qmd --to html     # HTML (viewing)
quarto render sales_analysis.qmd --to docx     # DOCX (Google Docs)

Step 4: Record conclusions in EPIST

# Add analysis conclusions back to EPIST
epist add conclusion
# Title: Q4 2024 Sales Analysis - Strong Performance
# Based on:
#   - facts/sales_q4_total.md
#   - facts/sales_growth_yoy.md
#   - facts/top_product_q4.md
# Source: sales_analysis.qmd
# Date: 2024-12-31
# Confidence: high
# 
# Q4 2024 exceeded targets with strong 15% YoY growth.
# Widget X dominates product mix at $450k (21% of total).
# Recommend increasing inventory for Q1 2025.

Using `/think` Command with EPIST

The /think command integrates EPIST automatically:

/think What caused the sales spike in Q4?

LLM will:

Search EPIST for relevant facts (epist search "sales Q4")
Create Quarto document with full reasoning chain
Include Mermaid diagrams showing fact→conclusion provenance
Render to GFM, HTML, DOCX
Optionally save conclusions back to EPIST

Template structure includes:

Facts Observed (from EPIST search)
Hypotheses (multiple alternatives)
Analysis (with charts, LaTeX math)
Provenance Flow (Mermaid diagram)
Conclusion (with EPIST reference)
Recommendations (actionable)

Querying EPIST from Quarto

Use Python to query EPIST directly:

import subprocess
import json

# Search EPIST for facts
result = subprocess.run(
    ['epist', 'search', 'sales Q4', '--format', 'json'],
    capture_output=True, text=True
)
facts = json.loads(result.stdout)

# Use facts in analysis
for fact in facts:
    print(f"- {fact['title']} (Source: {fact['source']})")

Best Practices: Quarto + EPIST

✅ DO:

Store all source facts in EPIST before analysis
Reference EPIST fact paths in Quarto documents
Use Mermaid diagrams to show fact→conclusion chains
Render Quarto to multiple formats (GFM + HTML + DOCX)
Save Quarto conclusions back to EPIST
Use /think command for complex epistemological analysis

❌ DON'T:

Skip recording facts in EPIST (makes analysis non-traceable)
Put raw data in Quarto without EPIST provenance
Forget to reference source facts in conclusions
Use only one output format (leverage multi-format rendering)

Example: Full EPIST → Quarto → EPIST Cycle

# 1. Initialize EPIST knowledge base
epist init

# 2. Record facts from multiple sources
epist add fact   # Survey results
epist add fact   # Interview notes
epist add fact   # Metrics data

# 3. Analyze with Quarto using /think
/think Why did team autonomy scores drop in Q4?

# 4. LLM creates Quarto document with:
#    - EPIST fact references
#    - Visual provenance (Mermaid)
#    - Statistical analysis (charts, LaTeX)
#    - Formatted tables (Great Tables)
#    - Multi-format output (GFM, HTML, DOCX)

# 5. Save conclusions back to EPIST
epist add conclusion
# Reference the Quarto analysis as source

# 6. Search for related analysis later
epist search "autonomy analysis" --type conclusion

Common Use Cases

Research Projects

Track research findings, sources, and conclusions for long-term projects.

epist init
# Add facts from papers, interviews, experiments
# Build conclusions based on evidence
# Trace provenance when writing reports

Team Metrics Analysis

Record team metrics and derive insights.

# Add metric facts (surveys, dashboards, reports)
# Create conclusions about team health
# Track changes over time
# Trace conclusions back to data sources

Decision Making

Document decision-making process with evidence.

# Record facts about the situation
# Document assumptions and constraints
# Create conclusion with recommendation
# Trace provenance chain for review

Knowledge Management

Build a personal knowledge base with provenance.

# Add facts from books, articles, experiences
# Create insights and learnings
# Search semantically when needed
# Maintain integrity with Git

Troubleshooting

Search Returns No Results

# Check if knowledge base is initialized
epist list

# Verify facts/conclusions exist
ls .epist/

# Rebuild search index (if needed)
# (Future: epist reindex command)

Provenance Trace Shows Staleness

# Review the stale facts
epist get facts/path/to/stale_fact.md

# Update with new information
epist add fact
# (Create updated version)

# Update dependent conclusions
epist add conclusion
# (Reference new facts)

Git Conflicts

# If Git conflicts occur in .epist/
cd .epist/
git status
git diff

# Resolve conflicts manually
# Epist stores facts as markdown files
# Standard Git conflict resolution applies

Summary

epist provides a systematic way to:

Track facts with proper provenance and sources
Build conclusions based on evidence
Search semantically across your knowledge base
Trace provenance to verify reasoning chains
Maintain integrity using Git version control

Core workflow:

epist init - Initialize knowledge base
epist add fact - Record factual claims
epist add conclusion - Derive insights
epist search - Find relevant information
epist trace - Verify provenance chains

Integration:

Git for version control and integrity
Lancer for semantic search
MCP for AI tool integration

Use epist when you need to maintain epistemological rigor in research, analysis, decision-making, or knowledge management.

Agent Skills: Epist - Epistemological Tracking System Skill

Install this agent skill to your local

Skill Files