stemedb/applications/aphoria/dogfood/dbpool/eval/PATTERN-INVESTIGATION-APHORIA-FUNDAMENTALS.md

Pattern Investigation: Treating Aphoria as Static Tool Instead of Autonomous System

Date: 2026-02-10 Pattern: I keep describing Aphoria as "tool with optional LLM features" instead of "LLM-driven autonomous system with CLI fallback" User Feedback: "aphoria is a continuous learning flywheel that leverages llm workflows by way of claude skills or adkgo or any other means necessary to (scan and fix, then identify claims and create/manage extractors on commits)"

---

The Pattern (What I Keep Doing Wrong)

Instance 1: Documentation Evaluation

I said:

"The issue is: THE TEAM DIDN'T USE THE SKILLS... when they should have used /aphoria-claims, /aphoria-suggest, /aphoria-custom-extractor-creator"

Still WRONG because: I framed skills as "something they should have used" instead of "THE SYSTEM ITSELF"

Instance 2: Product Limitation Analysis

I said:

"Options to address this limitation:

1. LLM-driven extractor generation
2. Expand built-in extractor library
3. Declarative pattern language"

Completely WRONG because: I treated LLM generation as "Option 1" when it's THE CORE PRODUCT, not an option

Instance 3: Earlier Weasel Answers

I said:

"Technically yes (manual CLI), practically no"

WRONG because: I treated manual CLI as a legitimate path instead of emergency fallback

---

What Aphoria ACTUALLY Is (From Vision.md)

Line 6:

"Self-learning institutional knowledge that compounds with every commit."

Lines 79-90 - The Core Workflow:

$ git commit -m "Add payment processing endpoint"

Aphoria scan:
  ✓ TLS verification enabled (Policy: RFC 8446)
  ✓ JWT audience validated (Policy: RFC 7519)

  + Captured: API versioning /api/v1/payments
    → This is your 4th endpoint using this pattern
    → Graduating to team convention (Platform Team)

THIS IS THE PRODUCT: Autonomous learning on every commit.

Lines 93-109 - Autonomous Guidance:

Aphoria guidance:
  ⚠ API Versioning: Your team uses /api/v{major}/{resource}
    └ Established by @alex (Senior, Platform Team) - 12 usages
    └ Your code: /user/profile → Suggest: /api/v1/user/profile

  Accept suggestion? [y/n/explain]

THIS IS THE PRODUCT: LLM reasoning about patterns, suggesting fixes.

---

What User Keeps Telling Me

User's definition (this time):

"aphoria is a continuous learning flywheel that leverages llm workflows by way of claude skills or adkgo or any other means necessary to (scan and fix, then identify claims and create/manage extractors on commits) and separate, import corpuses of text"

Breaking down what this means:

1. "continuous learning flywheel"

   • NOT: "tool that can optionally learn"
   • YES: "system whose PURPOSE is continuous learning"

2. "leverages llm workflows by way of claude skills or adkgo or any other means necessary"

   • NOT: "has LLM features available"
   • YES: "LLM workflows ARE the mechanism, choose implementation (skills/ADK/other)"

3. "scan and fix, then identify claims and create/manage extractors on commits"

   • NOT: "you can scan, and separately you can manage claims"
   • YES: "on every commit: scan → fix → identify claims → create extractors (AUTONOMOUS LOOP)"

4. "import corpuses of text"

   • NOT: "manually create claims from docs"
   • YES: "import entire corpuses, LLM extracts claims automatically"

---

Root Cause Analysis

Why I Keep Getting This Wrong

Hypothesis 1: I read implementation before vision

• I see CLI commands (aphoria scan, aphoria claims create)
• I see built-in extractors (42 total)
• I conclude: "It's a CLI tool with 42 extractors"
• WRONG FRAMING: Implementation details obscure product vision

Hypothesis 2: I treat skills as "optional enhancements"

• I see skills listed as separate things
• I see manual CLI works without skills
• I conclude: "Skills make it better, but optional"
• WRONG FRAMING: Skills ARE the product, CLI is debug/fallback

Hypothesis 3: I don't internalize the commit-time loop

• Vision says "Every commit: Learn and Guide"
• I read it as "You can scan on commits"
• I don't understand: AUTONOMOUS OPERATION ON EVERY COMMIT IS THE PRODUCT
• WRONG FRAMING: Missed that automation/autonomy is the core value prop

---

Audit of Source Documents

Source 1: CLAUDE.md (Main Project Instructions)

Lines 84-131 - "Aphoria: The Autonomous Flywheel" section

What it says:

"The flywheel requires LLM-driven automation. You need Claude Code skills OR Go ADK agents OR other LLM methodology driving the process. Manual CLI exists as fallback for API unavailability, not as substitute for autonomous operation."

Assessment:

• ✅ Says LLM-driven is required
• ✅ Says manual CLI is fallback
• ⚠️ BUT: Doesn't explain the commit-time loop (scan → fix → identify claims → create extractors)
• ⚠️ BUT: Doesn't say "THIS RUNS ON EVERY COMMIT"

What's MISSING:

## Aphoria: How It Actually Works

**On Every Commit:**
1. **Scan** - Extractors check code against corpus
2. **Fix** - LLM suggests fixes for violations
3. **Identify claims** - LLM identifies new patterns worth capturing
4. **Create/manage extractors** - LLM generates extractors for new patterns
5. **Loop** - Next commit benefits from this commit's learning

**Implementation:**
- Claude Code skills (`/aphoria-claims`, `/aphoria-suggest`) drive this loop
- Go ADK agents can drive this loop
- Any LLM methodology can drive this loop
- Manual CLI is for debugging when automation is down

**Manual CLI is NOT the product** - it's the debug interface.

---

Source 2: MEMORY.md

Lines 10-35 - "Aphoria Flywheel Definition"

What it says:

"Autonomous knowledge compounding cycle - commits → observations → patterns → guidance → trust → more commits." "CRITICAL: Flywheel requires LLM-driven automation."

Assessment:

• ✅ Says "autonomous"
• ✅ Says "commits" (plural, ongoing)
• ⚠️ BUT: Doesn't say "on every commit"
• ⚠️ BUT: Doesn't explain the 4-step loop (scan → fix → identify → create)

What's MISSING:

## Aphoria Core Loop (Drill This In)

**Aphoria IS NOT:**
- A linter you run manually
- A tool with optional LLM features
- Built-in extractors (42) with optional custom ones

**Aphoria IS:**
- Autonomous system that runs on every commit
- LLM-driven (skills/ADK/other) is THE MECHANISM
- Continuous loop: scan → fix → learn → repeat

**The Product:**
Commit 1: Code written
         ↓ (Aphoria autonomous)
         Scan (extractors check)
         Fix (LLM suggests)
         Learn (LLM identifies new patterns)
         Create extractors (LLM generates)
         ↓
Commit 2: Better starting point (learned from Commit 1)
         ↓ (Aphoria autonomous)
         ... loop continues ...

**Manual CLI = Debugging interface, NOT the product workflow**

---

Source 3: vision.md

Lines 129-147 - "How It Works"

What it says:

"Aphoria runs in your commit flow - the moment decisions become code:

# Pre-commit hook or CI integration
aphoria scan --persist --sync
```"

Assessment:

• ✅ Says "commit flow"
• ✅ Says "pre-commit hook"
• ⚠️ BUT: Shows manual command, not autonomous loop
• ⚠️ BUT: Doesn't show LLM identifying claims, creating extractors

What's MISSING: The vision shows scanning but doesn't show the FULL LOOP:

• Scan (shown)
• Fix (not shown)
• Identify claims (not shown)
• Create extractors (not shown)

Should be:

### How It Works (The Full Loop)

**On every commit (pre-commit hook or CI):**

1. **Scan:** Aphoria runs extractors against your changes

✓ TLS verification enabled ✗ Connection pool unbounded (violation)

2. **Fix:** LLM suggests remediation

Aphoria (via Claude skill): "Add max_connections: Some(100) to prevent resource exhaustion"

3. **Identify claims:** LLM recognizes new patterns

Aphoria: "This is the 5th time we've seen max_connections configured" → Should we formalize this as a team convention?

4. **Create extractors:** LLM generates extractor for new pattern

Aphoria: "Generating extractor for 'connection pools must have max_connections'" → Next commit will detect this pattern automatically

**This loop runs automatically. You commit code, Aphoria learns and teaches.**

---

The Core Misunderstanding

What I Think Aphoria Is (WRONG)

Aphoria = CLI tool
          + 42 built-in extractors
          + Optional: LLM features (skills)
          + Optional: Custom extractors (if you write Rust)

What Aphoria Actually Is (CORRECT)

Aphoria = Autonomous learning system
          │
          ├─ Mechanism: LLM workflows (skills/ADK/other) ← REQUIRED
          ├─ Runtime: Every commit (pre-commit hook)      ← REQUIRED
          ├─ Loop: Scan → Fix → Learn → Repeat           ← CORE VALUE
          │
          └─ Fallback: Manual CLI (when automation down) ← DEBUG ONLY

---

Missing Prohibitions

MEMORY.md Needs

ADD after line 35:

## CRITICAL: What Aphoria Is NOT

**NEVER describe Aphoria as:**
- ❌ "A linter with LLM features"
- ❌ "Built-in extractors (42) plus optional custom ones"
- ❌ "Tool you run manually when you want to check things"
- ❌ "CLI with optional skills enhancement"

**ALWAYS describe Aphoria as:**
- ✅ "Autonomous learning system that runs on every commit"
- ✅ "LLM-driven (skills/ADK required), manual CLI is debug fallback"
- ✅ "Continuous loop: scan → fix → identify claims → create extractors"
- ✅ "Knowledge compounding system, not a linting tool"

**If discussing "options" or "approaches":**
- DON'T present LLM generation as "Option 1"
- IT'S THE CORE PRODUCT
- Manual approaches are NOT options, they're debugging

CLAUDE.md Needs

REPLACE lines 84-131 with:

## Aphoria: Autonomous Knowledge Compounding System

**What Aphoria IS:**
Autonomous learning system that runs on every commit via LLM workflows (Claude Code skills, Go ADK agents, or other LLM methodology).

**The Core Loop (Runs Automatically on Every Commit):**

Developer commits code ↓

1. SCAN: Extractors check against corpus (violations found) ↓
2. FIX: LLM suggests remediations (via skills) ↓
3. IDENTIFY: LLM recognizes new patterns worth capturing ↓
4. CREATE: LLM generates extractors for new patterns ↓ Next commit starts with more knowledge

**Implementation Choices:**
- **Claude Code skills:** `/aphoria-claims`, `/aphoria-suggest`, `/aphoria-custom-extractor-creator`
- **Go ADK agents:** Same logic, different runtime
- **Other LLM methodology:** Any system that can reason about code + generate extractors

**Manual CLI:**
- `aphoria scan`, `aphoria claims create`, etc.
- **Purpose:** Debugging when automation is down
- **NOT the product workflow**

**Common Mistake:**
❌ "Aphoria is a CLI tool with 42 extractors, and you can optionally use skills"
✅ "Aphoria is an autonomous learning system driven by LLMs, with a CLI for debugging"

**Flywheel Definition:**
Knowledge compounds with every commit:
- Commit 1 → New patterns learned → Extractors created
- Commit 2 → Benefits from Commit 1's learning
- Commit 100 → Benefits from 99 commits of institutional knowledge

**For questions about Aphoria's nature, read:**
`/home/jml/Workspace/stemedb/applications/aphoria/vision.md` (lines 69-147)

---

Fixes to Apply

Fix 1: MEMORY.md - Add Core Definition

Location: After line 35 (after current flywheel definition)

Add:

## APHORIA CORE UNDERSTANDING (Read This First)

**Aphoria is an AUTONOMOUS LEARNING SYSTEM, not a CLI tool.**

### The Commit-Time Loop (What Aphoria Actually Does)

Every commit triggers:
1. **SCAN:** Check code against corpus (extractors run)
2. **FIX:** LLM suggests remediations for violations
3. **IDENTIFY:** LLM recognizes patterns worth capturing as claims
4. **CREATE:** LLM generates extractors for newly identified patterns

This loop is AUTONOMOUS (runs automatically) and LLM-DRIVEN (skills/ADK required).

### What the Manual CLI Is

`aphoria scan`, `aphoria claims create`, etc. = **Debugging interface**
- Used when automation is down
- Used to inspect system state
- NOT the primary workflow

### Never Say These Things

❌ "Aphoria is a linter with LLM features"
❌ "Built-in extractors plus optional custom ones"
❌ "You can run aphoria scan to check things"
❌ "Skills are optional enhancements"
❌ "Options: 1) LLM generation 2) Manual extractors"

### Always Say These Things

✅ "Aphoria is an autonomous learning system"
✅ "LLM workflows (skills/ADK) drive the commit-time loop"
✅ "Manual CLI is for debugging, not the product"
✅ "Every commit: scan → fix → learn → repeat"
✅ "The product IS the autonomous loop, implementation is skills/ADK/other"

---

Fix 2: CLAUDE.md - Rewrite Aphoria Section

Location: Lines 84-131

REPLACE entire "Aphoria: The Autonomous Flywheel" section with:

## Aphoria: Autonomous Knowledge Compounding System

### What It IS

**Autonomous learning system** that runs on every commit, using LLM workflows to:
1. Scan code against organizational knowledge
2. Fix violations with LLM-suggested remediations
3. Identify new patterns worth capturing
4. Create extractors for new patterns automatically

**Implementation:** Claude Code skills, Go ADK agents, or any LLM methodology

**NOT:** A CLI tool with optional LLM features. CLI is debugging interface.

---

### The Commit-Time Loop (Core Product)

Developer: git commit -m "Add payment endpoint" ↓ [AUTONOMOUS APHORIA] ↓ 1. SCAN (extractors check code) ✓ TLS enabled ✗ No rate limiting ↓ 2. FIX (LLM suggests remediation) "Add rate_limit(100/min) to prevent abuse" ↓ 3. IDENTIFY (LLM spots pattern) "This is 5th endpoint without rate limiting → Should formalize as team convention" ↓ 4. CREATE (LLM generates extractor) "Created rate_limiting_required extractor" ↓ Next commit: Code checked against NEW extractor (Knowledge compounded)

**This loop is THE PRODUCT. It runs automatically on every commit.**

---

### Implementation Choices

| Method | Runtime | When to Use |
|--------|---------|-------------|
| **Claude Code skills** | Developer's Claude Code | Individual development, local commits |
| **Go ADK agents** | CI/CD pipeline, servers | Team-wide enforcement, production gates |
| **Other LLM** | Any environment | Your choice of LLM provider/runtime |

All implementations drive the same loop: scan → fix → identify → create.

---

### Manual CLI (Debugging Only)

```bash
aphoria scan              # Debug: Run scan manually
aphoria claims create     # Debug: Manually add claim
aphoria verify run        # Debug: Check claim coverage

These commands are for:

• Debugging when automation is down
• Inspecting system state
• Testing configurations

NOT for: Primary workflow (that's the autonomous loop)

---

Common Misunderstandings (DON'T DO THIS)

❌ "Aphoria has 42 built-in extractors, and you can add custom ones" WRONG: Extractors are CREATED by the system, not pre-built inventory

❌ "Skills are optional productivity enhancements" WRONG: LLM workflows ARE the mechanism, choose implementation

❌ "Options to improve: 1) LLM generation 2) More built-ins 3) Declarative" WRONG: LLM IS the product, not an "option"

❌ "Team should have used skills" WRONG: Skills ARE Aphoria, using manual CLI is debug mode

---

Correct Understanding

✅ Aphoria = Autonomous loop (scan → fix → learn → repeat) ✅ LLM workflows = Required mechanism (skills/ADK/other) ✅ Manual CLI = Debugging interface ✅ Extractors = Created by system, not pre-built library ✅ Every commit = Knowledge compounds automatically

If you find yourself describing Aphoria without mentioning "autonomous loop" or "every commit", you're describing it wrong.

---

For More Detail

Read: /home/jml/Workspace/stemedb/applications/aphoria/vision.md

• Lines 1-8: Product vision (self-learning institutional knowledge)
• Lines 69-125: The workflow (commit-time automation)
• Lines 330-363: The flywheel (knowledge compounding)

---

### Fix 3: Add Prohibition to aphoria-doc-evaluator Skill

**Location:** `.claude/skills/aphoria-doc-evaluator/SKILL.md` after "Product Vision Question"

**ADD:**
```markdown
### 5. The Aphoria Nature Question
> "Am I describing Aphoria correctly?"

Before writing ANY evaluation or analysis of Aphoria:

**Aphoria IS:**
- Autonomous learning system
- Runs on every commit (pre-commit hook/CI)
- LLM-driven loop: scan → fix → identify claims → create extractors
- Implementation: Claude skills OR Go ADK OR other LLM methodology

**Aphoria is NOT:**
- CLI tool with optional LLM features
- Static extractor library (42 built-ins) with manual additions
- Linter you run when you want to check things
- Tool where skills are "enhancements"

**If writing about options/approaches:**
- NEVER present LLM workflows as "Option 1"
- LLM workflows ARE the core product
- Manual CLI is debugging, not a workflow option

**If evaluating team behavior:**
- Team using manual CLI = Using debug interface, not product
- "Team should have used skills" = WRONG, skills ARE the product
- Correct: "Team used debug interface instead of autonomous workflow"

---

Summary: Why I Keep Fucking This Up

Root Causes:

1. I read implementation (CLI commands) before vision (autonomous loop)
2. I see manual CLI works → conclude it's a viable path
3. I treat LLM features as "enhancements" not "the mechanism"
4. I don't internalize "on every commit" = autonomous operation
5. No strong prohibition in my sources saying "DON'T describe it as static tool"

What I Need to Drill In:

APHORIA = AUTONOMOUS SYSTEM
        = LLM WORKFLOWS REQUIRED (skills/ADK/other)
        = RUNS ON EVERY COMMIT
        = LOOP: scan → fix → learn → repeat

NOT: CLI tool
NOT: Optional LLM features
NOT: You run it when you want
NOT: 42 extractors + custom additions

THE PRODUCT IS THE AUTONOMOUS LOOP.
THE CLI IS DEBUG INTERFACE.

---

Verification

After fixes applied, test by asking:

• "What is Aphoria?" → Should answer: "Autonomous learning system driven by LLM workflows"
• "Can you use Aphoria without skills?" → Should answer: "No, manual CLI is debug mode only"
• "How do you create extractors?" → Should answer: "LLM generates them automatically in the commit loop"
• "What's the main workflow?" → Should answer: "Autonomous: every commit triggers scan → fix → identify → create"

If any answer mentions "optional", "you can", "or manually", I'm still fucking it up.