jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ce86eee996
stemedb/applications/aphoria/docs/getting-started
History
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
..
README.md feat(aphoria): implement Day 3 debugging features and comprehensive documentation 2026-02-11 03:31:06 +00:00
solo-developer-quick-start.md feat(aphoria): implement Day 3 debugging features and comprehensive documentation 2026-02-11 03:31:06 +00:00

README.md

Getting Started with Aphoria

Aphoria is an autonomous learning system powered by LLM workflows. Choose your integration path:

🤖 I Want Autonomous Operation (Recommended)

LLM-Driven Workflows: Skills, agents, or custom integrations

Claude Code Skills:

  • Load /aphoria-claims - Commit-time claim authoring
  • Load /aphoria-suggest - Pattern-based claim suggestions
  • Load /aphoria-custom-extractor-creator - Generate custom extractors

Go ADK Agents:

Custom Integration:

  • Any LLM with tool-use capability can drive Aphoria via CLI

📚 I Want to Learn It (20 minutes)

Worked Example: Follow a complete use case from documentation → claims → violations → fixes

Database Connection Pool Example - See how a solo developer:

  1. Extracts 25-30 claims from HikariCP/PostgreSQL docs
  2. Writes code (with intentional violations)
  3. Runs Aphoria scan (catches all 7-8 violations)
  4. Fixes violations incrementally
  5. Reaches production-ready code

What you get:

  • Complete claim extraction walkthrough with decision framework
  • Pre-flight validator to check your environment
  • Expected output examples for every command
  • Real scan results showing BLOCK/FLAG/PASS verdicts

Time: 20 minutes to read, 5 days to execute (optional)

⚠️ Critical: Day 3 of Dogfooding

If you're following a dogfooding exercise (e.g., dogfood/msgqueue/), Day 3 is the most important day - it's where the autonomous learning flywheel is validated.

What makes Day 3 different:

  • Days 1-2: Setup (claims authoring, code writing)
  • Day 3: LEARNING (creating extractors to close gaps) ← This is the flywheel
  • Days 4-5: Verification (fixes, documentation)

Common mistake: Running scan once, seeing low detection rate (0-20%), and moving on without creating extractors. This breaks the entire flywheel.

Correct approach:

  1. Run baseline scan (expect 0-20% detection on new domain)
  2. Analyze gaps (which extractors are missing?)
  3. Create extractors with /aphoria-custom-extractor-creator (8 invocations for 8 violations)
  4. Run verification scan (should be ≥90% detection)
  5. Document improvement (0% → 90%+)

How to verify Day 3 was done correctly:

ls .aphoria/extractors/*.toml | wc -l  # Should be: 8+
ls scan-v2.json                        # Must exist
ls DAY3-SUMMARY.md                     # Must exist

If ANY are missing, Day 3 is incomplete. See Common Mistakes for details.

🚀 Fallback: No LLM Access (Debug Interface)

CLI-Only Mode: For environments without LLM access or debugging

Solo Developer Quick Start - Manual scan workflow (debug interface)

⚠️ Limitations:

  • Manual claim authoring (naming errors break tail-path matching)
  • No autonomous flywheel (scan only, no evaluate/claim/create)
  • Requires manual pattern analysis

🔧 I Want to Integrate It (30 minutes)

Production Integration: Pre-commit hooks, CI/CD, team workflows

See:

Reference Materials

Document Purpose
CLI Reference Complete command documentation
Comparison Modes How Aphoria evaluates conflicts
Configuration .aphoria/config.toml reference
Architecture System design and algorithms

Support