# 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:**
```bash
grep -r "aphoria-claims\|aphoria-suggest" dogfood/dbpool/
# Result: 0 matches
```

The docs show only manual CLI:
```bash
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:**

```markdown
### 🤖 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:
```bash
--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:
```bash
# 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)

```rust
// 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:**

```markdown
### ⚠️ 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:

```bash
# 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:**
```bash
aphoria corpus create \
  --subject "dbpool/max_connections" \
  ...
```
(No mention of skills anywhere)

**What docs SHOULD say:**
```markdown
**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"