stemedb/applications/aphoria/dogfood/dbpool/eval/gap-analysis-skills-naming-2026-02-10.md

Documentation Gap Analysis: Skills & Naming Conventions

Date: 2026-02-10 Evaluator: Direct observation from user feedback Context: User identified critical gaps in dogfood documentation

---

Executive Summary

Critical Finding: Documentation fails to explain the two things that make the Aphoria flywheel actually work:

1. Claude Code skills that enforce consistency and productivity
2. Naming conventions that enable tail-path matching (the matching algorithm)

Impact: Without this knowledge:

• Users manually create 25-30 claims with inconsistent naming → Violations go undetected (tail-path mismatch)
• Users spend hours manually crafting claims → Don't realize skills can analyze diffs and suggest claims
• Flywheel appears broken ("I created claims but scan finds nothing")

---

Gap 1: Claude Code Skills Not Documented

Evidence

User Question:

"we need claude skills to make claims and create extractors, right?"

What I found:

grep -r "aphoria-claims\|aphoria-suggest" dogfood/dbpool/
# Result: 0 matches

The docs show only manual CLI:

aphoria corpus create \
  --subject "dbpool/max_connections" \
  --predicate "required" \
  ...

But NEVER mention that skills exist to:

• Analyze diffs and identify claimable patterns (/aphoria-claims)
• Suggest new claims from unclaimed observations (/aphoria-suggest)
• Enforce naming consistency automatically

Root Cause

Documentation was written assuming manual CLI workflow only. Skills were developed later (Phase A5.3-A5.4) but dogfood docs never updated.

Impact

• Time Lost: Team spends 3-4 hours manually creating 27 claims instead of 1-2 hours using skills
• Consistency: Manual claims have inconsistent naming (some use MaxConnections, some max_connections)
• Frustration: "Why is this so tedious?" when skills would make it fast
• Missed Learning: Doesn't demonstrate the actual production workflow (skills analyzing code)

Recommendation

Where: CHECKLIST.md Day 1, Step 3 (before creating claims) What to add:

### 🤖 Install Claude Code Skills (Productivity Accelerator)

**Optional but HIGHLY recommended:** Claude Code skills automate claim creation and enforce consistency.

- [ ] **Install skills in Claude Code**
  ```bash
  # In Claude Code terminal, run:
  /aphoria-claims     # Analyze diffs, suggest claims from code changes
  /aphoria-suggest    # Suggest claims from unclaimed observations

• Verify skills loaded

  Skills should appear in Claude Code's skill list.
  Type "/aphoria" and autocomplete should show both skills.
  

What these skills do:

• aphoria-claims: Analyze git diffs or code changes, identify claimable patterns, suggest claims with proper naming
• aphoria-suggest: Analyze scan results, find unclaimed observations, suggest corpus claims to add

Can you do this manually? Yes, using aphoria corpus create CLI commands directly. Should you? No - manual claim creation is error-prone (naming inconsistency) and 2-3x slower.

For dogfooding: Using skills demonstrates the real production workflow (skills + CLI together).

**Priority:** HIGH - Affects productivity and demonstrates wrong workflow

---

## Gap 2: Naming Conventions Not Explained

### Evidence

**User Question:**
> "making claims its really important to be strict and create the naming consistent, right?"

**What I found:**
```bash
grep -r "naming.*convention\|tail.path\|lowercase" dogfood/dbpool/
# Result: 0 matches explaining WHY naming matters

The docs show examples:

--subject "dbpool/max_connections"   # Correct

But NEVER explain:

• Format rules: lowercase, slash-separated, no special chars (_ becomes /)
• Why it matters: Tail-path matching uses last 2 segments
• What breaks: dbpool/MaxConnections won't match dbpool/max_connections (case-sensitive)

Root Cause

Documentation assumes developers understand tail-path matching from reading Aphoria source code. But dogfood users don't read source - they follow guides.

Impact

Scenario: Team creates claims with inconsistent naming:

# Claim 1: vendor://dbpool/max_connections
# Claim 2: vendor://dbpool/MaxConnections  (wrong - different case)
# Claim 3: vendor://dbpool/connection_timeout
# Claim 4: vendor://dbpool/connectionTimeout  (wrong - camelCase)

Result: Scan extracts observations like:

Observation: dbpool/max_connections = Option<usize>
Corpus claim: dbpool/MaxConnections must be required

Tail-paths don't match (max_connections ≠ MaxConnections) → CONFLICT NOT DETECTED

Team sees: "Aphoria found 0 violations" when 7 violations exist.

Cost:

• 2-3 hours debugging "why isn't Aphoria finding violations?"
• Frustration: "The tool is broken"
• False conclusion: "Aphoria doesn't work for Rust struct fields"

Technical Detail (From MEMORY.md)

// Tail-path matching (last 2 segments)
// Corpus claim: "vendor://dbpool/config/max_connections"
// → tail_path = "config/max_connections"

// Observation: "dbpool/config/max_connections"
// → tail_path = "config/max_connections"
// MATCH ✓

// Observation: "dbpool/config/MaxConnections"
// → tail_path = "config/MaxConnections"
// NO MATCH ✗ (case-sensitive comparison)

Recommendation

Where: CHECKLIST.md Day 1, Step 3 (before first claim creation) What to add:

### ⚠️ Naming Convention Rules (CRITICAL)

**Why this matters:** Aphoria uses tail-path matching (last 2 path segments) to compare observations against corpus claims. Inconsistent naming breaks matching → violations go undetected.

#### Format Rules

✅ **Correct:**
- Lowercase only: `max_connections` (not `MaxConnections`)
- Slash-separated: `dbpool/max_connections` (not `dbpool::max_connections`)
- Underscores for spaces: `connection_timeout` (not `connection-timeout` or `connectionTimeout`)
- Hierarchical: `dbpool/config/max_connections` (component → subcategory → property)

❌ **Wrong (will break matching):**
- `dbpool/MaxConnections` - Case mismatch
- `dbpool::max_connections` - Wrong separator
- `dbpool/connectionTimeout` - CamelCase
- `dbpool-max-connections` - Hyphens instead of slashes

#### Examples

```bash
# Safety claims
--subject "dbpool/max_connections"              # ✓
--subject "dbpool/min_connections"              # ✓
--subject "dbpool/connection_timeout"           # ✓

# Security claims
--subject "dbpool/connection_string/password"   # ✓ (hierarchical)
--subject "dbpool/tls/enabled"                  # ✓

# WRONG - Don't do this:
--subject "dbpool/MaxConnections"               # ✗ Case mismatch
--subject "dbpool::max_connections"             # ✗ Wrong separator
--subject "dbpool/max-connections"              # ✗ Hyphens

How Tail-Path Matching Works

Corpus Claim: vendor://dbpool/config/max_connections
              → tail_path: "config/max_connections" (last 2 segments)

Observation:  dbpool/config/max_connections
              → tail_path: "config/max_connections"
              → MATCH ✓ (conflict detected)

Observation:  dbpool/config/MaxConnections
              → tail_path: "config/MaxConnections"
              → NO MATCH ✗ (violation missed!)

Verification

After creating each claim, verify the subject format:

# Query your newly created claim
curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=vendor' | \
  jq '.items[] | select(.subject | contains("dbpool")) | .subject'

# Should show:
# "vendor://dbpool/max_connections"  ✓
# "vendor://dbpool/min_connections"  ✓

# NOT:
# "vendor://dbpool/MaxConnections"   ✗

Pro Tip: Use aphoria-claims skill to enforce naming automatically.

**Priority:** CRITICAL - Without this, the entire flywheel breaks

---

## Gap 3: Skills Installation Process Missing

### Evidence

**User Question:**
> "our docs should instruct how to install the claude skills that are required to use the aphoria flywheel, correct?"

**Answer:** YES - but this is completely missing from dogfood docs.

**What's missing:**
1. Where to find the skills (they're in `.claude/skills/` in the parent repo)
2. How to load them in Claude Code
3. What each skill does
4. When to use which skill

### Root Cause

Skills are documented in StemeDB parent repo (`CLAUDE.md` lists them) but dogfood docs assume you already know about them.

### Recommendation

**Where:** `CHECKLIST.md` Pre-Execution Requirements (before Day 1)
**What to add:**

```markdown
### ✅ Claude Code Skills (Optional but Recommended)

The Aphoria flywheel works best with Claude Code skills that automate claim creation and analysis.

- [ ] **Verify you're using Claude Code**
  ```bash
  # In your terminal, check if Claude Code is available
  which claude
  # Or check if you're in a Claude Code session

• Load Aphoria skills

  Skills location: /home/jml/Workspace/stemedb/.claude/skills/

  Available skills:

  • aphoria-claims - Analyze diffs, author claims from code changes
  • aphoria-suggest - Suggest claims from unclaimed observations
  • aphoria-custom-extractor-creator - Build declarative extractors

  How to load: In Claude Code, the skills should auto-load from the parent project. Verify with:

  Type: /aphoria
  Autocomplete should show: /aphoria-claims, /aphoria-suggest
  

• When to use each skill

  Skill	When to use	Example
  aphoria-claims	Day 1 claim creation, Day 4 diff review	"Review this diff for claimable patterns"
  aphoria-suggest	Day 3 after scan	"What claims should I add based on this scan?"
  aphoria-custom-extractor-creator	Day 3 custom extractors	"Build extractor for struct field validation"

Can you do this without skills? Yes - use aphoria corpus create manually. But:

• ⏱️ 2-3x slower (no diff analysis)
• ⚠️ Error-prone (manual naming, no consistency checks)
• 📚 Misses the production workflow demonstration

For dogfooding: Skills are the intended workflow. Manual CLI is the fallback.

**Priority:** HIGH - Demonstrates wrong workflow without this

---

## Summary of Fixes Needed

| Gap | File | Section | Priority | Effort |
|-----|------|---------|----------|--------|
| Skills not mentioned | CHECKLIST.md | Day 1 Step 3 | HIGH | 30 min |
| Skills installation | CHECKLIST.md | Pre-Execution | HIGH | 20 min |
| Naming conventions | CHECKLIST.md | Day 1 Step 3 | CRITICAL | 45 min |
| Naming rationale | CHECKLIST.md | Day 1 Step 3 | CRITICAL | 30 min |

**Total effort:** ~2 hours
**Impact:** Prevents 3-4 hours of debugging + demonstrates correct workflow

---

## Proposed Section Order (CHECKLIST.md Day 1)

```markdown
## Day 1: Create 25-30 Corpus Claims

### Step 1: Read Claim Extraction Example (15-20 min)
[existing content]

### Step 2: Fetch Authority Source Documents (30 min)
[existing content]

### Step 3: Prepare for Claim Creation

#### 🤖 Install Claude Code Skills (RECOMMENDED)
[NEW - Gap 3 fix]

#### ⚠️ Naming Convention Rules (CRITICAL)
[NEW - Gap 2 fix]

#### ✅ Create Claims via CLI or Skills
[EXISTING - but now references skills as primary workflow]

---

Evidence Chain

User observation:

"we need claude skills to make claims and create extractors, right?"

What docs currently say:

aphoria corpus create \
  --subject "dbpool/max_connections" \
  ...

(No mention of skills anywhere)

What docs SHOULD say:

**Primary workflow:** Use /aphoria-claims skill to analyze diffs and suggest claims
**Fallback workflow:** Manual `aphoria corpus create` commands (slower, error-prone)

Gap confirmed: Skills are the intended workflow but not documented.

---

Next Steps

1. Immediate (before next dogfood run):

   • Add naming convention rules to CHECKLIST.md Day 1
   • Add skills installation to Pre-Execution Requirements
   • Update Day 1 workflow to show skills as primary, CLI as fallback

2. Short-term (this week):

   • Add naming verification step after each claim creation
   • Add troubleshooting section: "Why scan finds 0 violations despite claims existing"

3. Long-term (next month):

   • Create video demo showing skills workflow
   • Add naming linter to pre-commit hooks (catch inconsistencies early)

---

Cost of NOT Fixing

Scenario: Next team uses dogfood docs without these fixes

1. Hour 0-4: Manually create 27 claims (no skills mentioned)
2. Hour 4: Run scan → finds 0 violations (naming inconsistency)
3. Hour 4-6: Debug "why isn't Aphoria working?"
4. Hour 6: Discover naming mismatch, delete all claims, start over
5. Hour 6-8: Recreate claims with consistent naming
6. Hour 8: Finally see violations detected

Total wasted time: 4-6 hours Frustration level: HIGH ("This tool is broken") False conclusion: "Aphoria doesn't work for Rust code"

With fixes:

1. Hour 0: Load skills (5 min)
2. Hour 0-2: Use skills to create 27 claims with enforced naming
3. Hour 2: Run scan → finds 7 violations ✓
4. Hour 2: Success!

Time saved: 4-6 hours Frustration: LOW Conclusion: "Aphoria is amazing"