# 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:**
```bash
$ 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:**
```bash
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:**
```markdown
## 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:**
```markdown
## 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:
> ```bash
> # 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:
```markdown
### 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**

```markdown
## 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.