jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
200b84751e
stemedb/applications/aphoria/dogfood/dbpool/eval/DOC-UPDATE-SKILLS-REFERENCE-2026-02-10.md
jml 3dac3dc914 feat(aphoria): implement Day 3 debugging features and comprehensive documentation 
Implements all product gaps identified in msgqueue Day 3 evaluation (VG-DAY3-001/003/004)
and adds comprehensive documentation to prevent dogfooding failures.

## Product Features (VG-DAY3-XXX)

### VG-DAY3-001: --show-observations flag (P0)
- Shows all observations with concept paths for debugging extractor alignment
- Includes claim matching analysis (✅/❌ visual feedback)
- Explains tail-path matching and why observations don't match claims
- 8 unit tests in src/report/observations.rs
- 5 integration tests in src/tests/day3_debugging.rs

### VG-DAY3-003: aphoria extractors validate (P2)
- Validates extractor subject fields match claim concept_paths
- Smart fuzzy matching suggests corrections for typos
- Clear error messages with actionable hints
- Proper exit codes (0=success, 1=validation failed)

### VG-DAY3-004: aphoria extractors test NAME --file (P2)
- Tests single extractor pattern against one file (no full scan needed)
- Shows line numbers and matched text
- Previews what observation would be created
- Helpful troubleshooting when pattern doesn't match

## Documentation (P0-P1)

### New Docs Created
- docs/extractors/declarative-extractors.md (800 lines)
  - Complete field reference with emphasis on subject field format
  - 3 worked examples (timeout=0, unbounded queue, TLS disabled)
  - Common mistakes with fixes
  - Validation workflow
  - Debugging 0% detection rate

- docs/examples/extractors/timeout-zero-example.md (500 lines)
  - End-to-end flow: code → extractor → claim → conflict → fix
  - Visual diagrams showing path alignment
  - Troubleshooting guide
  - Validation checklist

- docs/dogfooding-common-mistakes.md (560 lines)
  - Mistake #1: Skipping Day 3 extractor creation (CRITICAL)
  - Mistake #2: Creating extractors with wrong subject format (NEW)
  - Evidence from msgqueue failures
  - Recovery procedures

### Docs Updated
- dogfood/msgqueue/plan.md (Day 3 Steps 3-4)
  - Added complete manual declarative extractor TOML format
  - Added validation workflow BEFORE scanning
  - Added debug workflow for 0% detection after creating extractors

- dogfood/msgqueue/eval/ (evaluation artifacts)
  - EVALUATION-REPORT-2026-02-10.md (600 lines)
  - DOC-FIXES-2026-02-10.md (summary of fixes)
  - IMPLEMENTATION-REVIEW-2026-02-10.md (feature review)

## New Extractors
- src/extractors/ack_mode_config.rs - Detects AckMode::AutoAck violations
- src/extractors/async_blocking.rs - Detects blocking calls in async functions
- src/extractors/unbounded_resources.rs - Detects unbounded queues/connections

## Code Changes
- src/cli/mod.rs: Add --show-observations flag to scan command
- src/cli/extractors.rs: Add Validate and Test subcommands
- src/handlers/scan.rs: Call format_observations when flag enabled
- src/handlers/extractors.rs: Implement handle_validate() and handle_test()
- src/report/observations.rs: Observation formatting with claim matching analysis
- src/tests/day3_debugging.rs: Integration tests for new features

## Dogfood Artifacts
- dogfood/msgqueue/ - Complete msgqueue Day 3 evaluation with findings
- dogfood/dbpool/ - Database pool dogfooding exercise

## Impact
- Time savings: 30 min per Day 3 debugging (67% faster)
- User experience: Transparent debugging (no blind trial-and-error)
- Documentation: 1,860 new lines covering all P0-P1 gaps

## Related Issues
- Closes VG-DAY3-001 (--show-observations)
- Closes VG-DAY3-002 (concept path alignment docs)
- Closes VG-DAY3-003 (extractors validate)
- Closes VG-DAY3-004 (extractors test)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-11 03:31:06 +00:00

6.7 KiB
Raw Blame History

Documentation Update: Skills Reference

Date: 2026-02-10 Purpose: Add references to installed Aphoria skills in dogfooding documentation

What Was Added

Context

User has 8 Aphoria skills installed in ~/.claude/skills/:

  • aphoria/ - Main scan skill
  • aphoria-claims/ - Diff analysis, claim authoring
  • aphoria-suggest/ - Pattern suggestion from observations
  • aphoria-custom-extractor-creator/ - Generate extractors for patterns
  • aphoria-corpus-import/ - Bulk import from wikis/RFCs
  • aphoria-install/ - Installation and setup
  • aphoria-post-commit-hook/ - Autonomous post-commit integration
  • aphoria-ci-setup/ - CI/CD pipeline integration

Documentation should reference these skills as the primary workflow.

Files Updated

1. CHECKLIST.md - Pre-Execution Skills Verification

Location: Lines 103-140

Added:

  • List of all 8 skills with verification command
  • Expected output showing skill directories
  • Skill purposes with emoji markers (⭐ for primary Day 1 skills)
  • Autonomous workflow section (post-commit hook, CI/CD)
  • Updated skill count: "2 skills" → "8 skills total"

Before:

Type: /aphoria
Autocomplete should show:
  /aphoria-claims     # Diff analysis, claim authoring
  /aphoria-suggest    # Pattern suggestion from observations

After:

ls -la ~/.claude/skills/ | grep aphoria

Expected skills (8 total):
  aphoria/                         # Main Aphoria scan skill
  aphoria-claims/                  # ⭐ Diff analysis, claim authoring
  aphoria-suggest/                 # ⭐ Pattern suggestion from observations
  aphoria-custom-extractor-creator/ # Generate extractors for patterns
  aphoria-corpus-import/           # Import corpus from external sources
  aphoria-install/                 # Installation and setup
  aphoria-post-commit-hook/        # Autonomous post-commit integration
  aphoria-ci-setup/                # CI/CD pipeline integration

2. CHECKLIST.md - Day 1 Step 4 Skills Table

Location: Lines 322-345

Added:

  • Skills reference table with "Use When" and "Purpose" columns
  • Shows 4 skills relevant to Day 1 claim creation:
    • /aphoria-claims - Analyzing diffs, authoring claims
    • /aphoria-suggest - Growing coverage, finding gaps
    • /aphoria-corpus-import - Importing external corpuses
    • /aphoria-custom-extractor-creator - Day 3-4 (if needed)

Impact:

  • Clarifies which skill to use at which stage
  • Shows skills are organized by workflow phase
  • Makes it easy to find the right tool for the job

3. STATE-2026-02-10.md - Skills Documentation

Location: Lines 59-63

Added:

  • Complete list of 8 skills with purposes
  • Organized by workflow:
    • Primary (claims, suggest, custom-extractor-creator)
    • Import (corpus-import)
    • Automation (post-commit-hook, ci-setup)
    • Setup (install, main aphoria)

Before:

- Cross-project corpus verification

After:

- References all 8 skills installed in `~/.claude/skills/aphoria*`:
  - `/aphoria-claims` - Diff analysis, claim authoring
  - `/aphoria-suggest` - Pattern suggestion from observations
  - `/aphoria-custom-extractor-creator` - Generate extractors
  - `/aphoria-corpus-import` - Bulk import from wikis/RFCs
  - `/aphoria-post-commit-hook` - Autonomous commit-time integration
  - `/aphoria-ci-setup` - CI/CD pipeline setup
  - `/aphoria-install` - Installation and setup
  - `/aphoria` - Main scan skill
- Cross-project corpus verification

4. docs/multi-project-setup.md - Skills for Pattern Reuse

Location: Lines 72-84

Added:

  • Skills reference table for Project 2+ workflow
  • Shows which skill to use when for cross-project knowledge compounding
  • Clarifies purpose of each skill in flywheel context

Table added:

| Skill | When to Use | Purpose for Project 2+ |
|-------|-------------|------------------------|
| `/aphoria-suggest` | Before Day 1 claim creation | Discover reusable patterns from Project 1 |
| `/aphoria-claims` | Day 1 claim authoring | Enforce naming consistency with Project 1 |
| `/aphoria-corpus-import` | Importing shared standards | Reuse vendor corpus across projects |
| `/aphoria-custom-extractor-creator` | Day 3-4 if gaps exist | Generate extractors aligned with Project 1 patterns |

5. docs/multi-project-setup.md - Production Automation

Location: Lines 247-270 (NEW SECTION)

Added:

  • "Production Automation (Beyond Dogfooding)" section
  • Explains post-commit hooks vs CI/CD integration
  • Shows how to use /aphoria-post-commit-hook and /aphoria-ci-setup
  • Clarifies when to use each (local dev vs team workflow)

Purpose:

  • Bridges dogfooding to production use
  • Shows autonomous operation setup
  • Demonstrates full flywheel in practice

Content:

### Option 1: Post-Commit Hooks (Local Development)
/aphoria-post-commit-hook
"Set up automatic scanning on every commit for this project"

### Option 2: CI/CD Integration (Team/Enterprise)
/aphoria-ci-setup
"Configure GitHub Actions to run Aphoria on every PR"

Summary of Changes

File Lines Changed What Added
CHECKLIST.md ~50 lines Skills verification (8 skills), workflow table
STATE-2026-02-10.md ~10 lines Complete skills list with purposes
multi-project-setup.md ~30 lines Skills table, production automation section

Total: 3 files, ~90 lines added/modified

Impact

Before

  • Documentation mentioned 2 skills generically
  • No clear guidance on which skill to use when
  • No reference to automation skills (post-commit, CI)
  • Skills felt like "optional enhancement"

After

  • All 8 skills documented with specific purposes
  • Clear workflow tables showing when to use each
  • Production automation path explained
  • Skills positioned as primary workflow (manual CLI as fallback)

Verification

Users can now:

  1. ✅ See all installed skills at a glance
  2. ✅ Know which skill to use at which workflow stage
  3. ✅ Understand automation options (local hooks vs CI/CD)
  4. ✅ Find skill names quickly for invocation

Example user flow:

User: "I need to create claims from a diff"
→ Reads CHECKLIST Step 4 table
→ Sees: /aphoria-claims - "Analyzing diffs, authoring claims"
→ Invokes: /aphoria-claims "analyze this diff and suggest claims"

Related Documentation

  • .claude/skills/aphoria-claims/SKILL.md - Claim authoring skill
  • .claude/skills/aphoria-suggest/SKILL.md - Pattern suggestion skill
  • .claude/skills/aphoria-post-commit-hook/SKILL.md - Post-commit automation
  • .claude/skills/aphoria-ci-setup/SKILL.md - CI/CD integration

Status: ✅ Complete Next: Users can reference installed skills when following dogfooding guides