stemedb/applications/aphoria/dogfood/msgqueue/plan.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

724 lines
23 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Dogfood Project: Message Queue Consumer Library
**Start Date:** 2026-02-10
**Hypothesis:** Async connection patterns + resource limits from httpclient/dbpool corpora transfer to message queue consumers with 50%+ pattern reuse, demonstrating cross-domain flywheel strength.
**Corpus Overlap:** httpclient + dbpool → **~50%** pattern reuse expected
**Target Metrics:**
- Time savings: **≥60%** vs manual (4 hrs manual → 1.5-2 hrs with flywheel)
- Pattern reuse: **≥50%** of claims (11+/22)
- Detection rate: **≥90%** of violations (8/8 or 7/8)
- Naming errors: **<2** (corpus conventions established)
---
## Why This Domain?
Message queue consumers combine:
- **Async patterns** from httpclient (timeout, retry, TLS, metrics)
- **Resource limits** from dbpool (max connections, lifecycle, cleanup)
- **New patterns** unique to messaging (backpressure, ack_timeout, queue_size)
This tests whether the flywheel **adapts across domains** - if patterns learned in HTTP/DB contexts transfer to async messaging, the knowledge compounding mechanism is working.
---
## Day 1: Claims Extraction (1-2 hours)
**Goal:** Author **22 claims** (11 reused from corpus, 11 new) using pattern discovery
**Skills:**
- `/aphoria-suggest --corpus httpclient,dbpool` - discover reusable patterns
- `/aphoria-claims` - author claims with full provenance
**Process:**
### Step 1: Pattern Discovery (30 min)
```bash
# Use skill to analyze both corpora
/aphoria-suggest --corpus httpclient,dbpool --domain msgqueue
# Expected reusable patterns:
# From httpclient: timeout, retry, tls, async, metrics
# From dbpool: max_connections, connection_lifecycle, cleanup
# New for msgqueue: backpressure, queue_size, ack_timeout
```
### Step 2: Authority Source Curation (30 min)
Fetch and extract key sections:
1. **AMQP 0-9-1 Protocol Spec** (Tier 1 - Standards)
- Connection lifecycle, acknowledgment modes, QoS
2. **RabbitMQ Best Practices** (Tier 2 - Vendor)
- Consumer prefetch, heartbeat, timeout recommendations
3. **lapin Library Docs** (Tier 3 - Community)
- Rust async patterns, connection pooling, error handling
### Step 3: Claim Authoring (30-60 min)
Use `/aphoria-claims` to create **22 claims**:
**Reused from Corpus (11 expected):**
1. `msgqueue/consumer/timeout` (from httpclient)
2. `msgqueue/tls/certificate_validation` (from httpclient)
3. `msgqueue/connection/max_connections` (from dbpool)
4. `msgqueue/connection/lifecycle` (from dbpool)
5. `msgqueue/metrics/enabled` (from httpclient)
6. `msgqueue/retry/max_attempts` (from httpclient)
7. `msgqueue/retry/backoff_strategy` (from httpclient)
8. `msgqueue/connection/cleanup` (from dbpool)
9. `msgqueue/async/runtime` (from httpclient)
10. `msgqueue/connection/idle_timeout` (from dbpool)
11. `msgqueue/tls/min_version` (from httpclient)
**New for Message Queue (11 expected):**
12. `msgqueue/consumer/prefetch_count` - QoS setting (1-100)
13. `msgqueue/consumer/ack_mode` - auto vs manual acknowledgment
14. `msgqueue/consumer/ack_timeout` - must ack within N seconds
15. `msgqueue/queue/max_size` - bounded queue prevents OOM
16. `msgqueue/consumer/backpressure_strategy` - pause vs drop vs error
17. `msgqueue/connection/heartbeat_interval` - keepalive (10-60s)
18. `msgqueue/consumer/requeue_limit` - max redeliveries (3-5)
19. `msgqueue/queue/durable` - persistence for crash recovery
20. `msgqueue/consumer/exclusive` - single consumer guarantee
21. `msgqueue/connection/recovery_strategy` - auto-reconnect logic
22. `msgqueue/consumer/dead_letter_queue` - failed message handling
### Step 4: Batch Import (Recommended)
```bash
# Import all 22 claims at once from TOML template
aphoria claims import claims-template.toml
# Or preview first with dry-run
aphoria claims import claims-template.toml --dry-run
# Or validate format without importing
aphoria claims import claims-template.toml --validate-only
```
**Target Output:**
- **22 claims** in `.aphoria/claims.toml`
- **11/22 (50%)** reused from httpclient/dbpool
- **0 naming errors** (follow corpus conventions: `/{domain}/{concept}/{property}`)
- **Daily summary:** `DAY1-SUMMARY.md`
**Success Criteria:**
- All claims have: provenance, invariant, consequence, authority tier
- Reuse rate 50%
- Time 2 hours (60%+ faster than 4-5 hr baseline)
---
## Day 2: Implementation (2-4 hours)
**Goal:** Build Rust message queue consumer library with **8 intentional violations**
**Tech Stack:**
- `lapin` (AMQP client for RabbitMQ)
- `tokio` (async runtime)
- `thiserror` (error handling)
**Violations (Intentional):**
### 1. **Zero Timeout** → Indefinite Blocking
```rust
// @aphoria:claim[safety] Consumer timeout MUST be >0 -- timeout=0 causes indefinite blocking under connection loss
pub timeout: Duration = Duration::from_secs(0); // ❌ VIOLATION
```
**Consequence:** Consumer hangs forever if broker is unresponsive
**Location:** `src/config.rs:15`
### 2. **Missing Backpressure** → OOM Under Load
```rust
// @aphoria:claim[safety] Consumer MUST implement backpressure -- unbounded queue causes OOM under sustained load
pub max_queue_size: Option<usize> = None; // ❌ VIOLATION (unbounded)
```
**Consequence:** Memory exhaustion when broker sends faster than consumer processes
**Location:** `src/config.rs:23`
### 3. **Unbounded Prefetch** → Resource Exhaustion
```rust
// @aphoria:claim[safety] Prefetch count MUST be bounded (1-100) -- unbounded prefetch exhausts memory
pub prefetch_count: u16 = u16::MAX; // ❌ VIOLATION
```
**Consequence:** Broker sends all messages at once, overwhelming consumer
**Location:** `src/config.rs:31`
### 4. **Auto-Ack Without Processing** → Data Loss
```rust
// @aphoria:claim[safety] Auto-ack MUST only be used with guaranteed processing -- auto-ack before processing causes data loss
pub ack_mode: AckMode = AckMode::AutoAck; // ❌ VIOLATION (no processing guarantee)
```
**Consequence:** Message acknowledged before processing lost on crash
**Location:** `src/consumer.rs:45`
### 5. **No Requeue Limit** → Infinite Retry Loops
```rust
// @aphoria:claim[safety] Requeue limit MUST be set (3-5) -- infinite requeues create poison message loops
pub max_requeues: Option<u32> = None; // ❌ VIOLATION (infinite)
```
**Consequence:** Failed messages requeue forever, blocking queue
**Location:** `src/consumer.rs:67`
### 6. **Missing TLS Validation** → MITM Attacks
```rust
// @aphoria:claim[security] TLS certificate validation MUST be enabled -- disabled validation allows MITM
pub verify_tls: bool = false; // ❌ VIOLATION
```
**Consequence:** Attacker intercepts message queue traffic
**Location:** `src/connection.rs:89`
### 7. **No Connection Pooling** → Resource Exhaustion
```rust
// @aphoria:claim[performance] Connection pool MUST be bounded (1-10) -- unbounded connections exhaust broker resources
pub max_connections: Option<usize> = None; // ❌ VIOLATION
```
**Consequence:** Spawns unlimited connections, DoS on broker
**Location:** `src/connection.rs:102`
### 8. **Synchronous Processing** → Throughput Collapse
```rust
// @aphoria:claim[performance] Message processing MUST be async -- synchronous processing blocks event loop
pub async fn process_message(&self, msg: Message) {
std::thread::sleep(Duration::from_secs(1)); // ❌ VIOLATION (blocking in async)
}
```
**Consequence:** Blocks tokio runtime, throughput drops to 1 msg/sec
**Location:** `src/processor.rs:34`
**Process:**
1. Create `src/` files: `config.rs`, `consumer.rs`, `connection.rs`, `processor.rs`, `lib.rs`
2. Implement happy path: connect subscribe consume ack
3. Embed 8 violations with inline markers
4. Add unit tests for non-violating code paths
5. Keep code realistic (not toy example)
**Target Output:**
- Working consumer library (basic pub/sub functionality)
- **8 embedded violations** with inline markers
- Daily summary: `DAY2-SUMMARY.md`
**Success Criteria:**
- All violations have inline markers
- Code compiles and runs
- Time 4 hours
---
## Day 3: Scanning (1-2 hours)
**Goal:** Detect **8/8 violations** via `aphoria scan` AND create extractors for gaps
** THIS IS THE CORE FLYWHEEL STEP** - Day 3 validates autonomous learning. Do NOT skip extractor creation.
**Prerequisites (Pre-Flight Check):**
```bash
# 1. Verify skill availability
/help | grep aphoria-custom-extractor-creator
# Expected: Skill should be listed
# 2. Verify inline markers present
grep -r "@aphoria:claim" src/ | wc -l
# Expected: 8 markers (one per violation)
# 3. Verify code compiles
cargo check
# Expected: Success
```
If any check fails, STOP and fix before proceeding.
---
**Process:**
### Step 1: Baseline Scan (15 min)
```bash
cd /path/to/dogfood/msgqueue
aphoria scan --format json > scan-results-v1.json
aphoria scan --format markdown > SCAN-REPORT-v1.md
```
**Expected on FIRST scan:** Low detection rate (0-20%) is NORMAL for new domains because extractors don't exist yet.
**This is NOT a failure** - it's the signal that Step 3 (extractor creation) is needed.
---
### Step 2: Gap Analysis (15 min) **[REQUIRED]**
Analyze `scan-results-v1.json`:
- Which claims show "MISSING" verdict? (no observations found)
- Which violations have inline markers but weren't detected?
- What patterns need extractors?
Create gap analysis table:
```markdown
| Violation | Location | Marker Present? | Observation Found? | Action |
|-----------|----------|----------------|-------------------|--------|
| timeout=0 | config.rs:20 | ✅ | ❌ | Create extractor |
| prefetch=MAX | config.rs:33 | ✅ | ❌ | Create extractor |
... (8 total)
```
---
### Step 3: Extractor Creation (30 min) **[REQUIRED - DO NOT SKIP]**
** CRITICAL:** This step is REQUIRED. Skipping this breaks the autonomous learning flywheel.
**For EACH missed violation (8 total), use skill to create extractor:**
```bash
# Load skill if not already loaded:
/aphoria-custom-extractor-creator
# Create extractors for each violation:
/aphoria-custom-extractor-creator --violation "timeout=0" --claim msgqueue-001
/aphoria-custom-extractor-creator --violation "prefetch_count=u16::MAX" --claim msgqueue-012
/aphoria-custom-extractor-creator --violation "verify_certificates=false" --claim msgqueue-002
/aphoria-custom-extractor-creator --violation "blocking in async fn" --claim msgqueue-009
/aphoria-custom-extractor-creator --violation "max_queue_size=None" --claim msgqueue-015
/aphoria-custom-extractor-creator --violation "ack_mode=AutoAck" --claim msgqueue-013
/aphoria-custom-extractor-creator --violation "max_requeue_count=None" --claim msgqueue-018
/aphoria-custom-extractor-creator --violation "max_connections=None" --claim msgqueue-003
# The skill will automatically:
# 1. Analyze the violation pattern
# 2. Generate regex extractor
# 3. Map to correct concept_path
# 4. Save to .aphoria/extractors/{name}.toml
# 5. Verify extractor loads correctly
```
**Verification:**
```bash
ls .aphoria/extractors/*.toml | wc -l
# Expected: 8 extractor files
# Verify directory was created:
ls .aphoria/extractors/
# Expected: timeout_zero.toml, prefetch_unbounded.toml, tls_disabled.toml, etc.
```
**If skill is unavailable:** You can manually create declarative extractors. Follow the format below:
**Manual Fallback (Declarative Extractor):**
Add to `.aphoria/config.toml` for EACH violation:
```toml
[[extractors.declarative]]
name = "descriptive_name"
pattern = 'regex_pattern_matching_code'
languages = ["rust"]
[extractors.declarative.claim]
subject = "FULL_CLAIM_CONCEPT_PATH" # ← Copy from claim's concept_path EXACTLY
predicate = "claim_predicate"
value = inverted_value # false if claim expects true, 0 if claim expects > 0
confidence = 0.95
```
** CRITICAL:** `subject` must EXACTLY match your claim's `concept_path`.
**Example:**
If claim has `concept_path = "msgqueue/queue/max_size"`,
Then extractor needs `subject = "msgqueue/queue/max_size"` (not just "queue/max_size")
**Complete Example (timeout=0):**
```toml
[[extractors.declarative]]
name = "timeout_zero_detector"
pattern = 'timeout:\s*Duration::from_secs\(0\)'
languages = ["rust"]
[extractors.declarative.claim]
subject = "msgqueue/config/timeout" # ← Matches claim concept_path exactly
predicate = "zero"
value = 0
confidence = 0.95
```
**Validation Before Scanning:**
```bash
# 1. Check subject matches claim concept_path
grep "subject =" .aphoria/config.toml
grep "concept_path =" .aphoria/claims.toml
# Subjects should match concept_paths EXACTLY
# 2. Test regex pattern matches code
grep -rE 'timeout:\s*Duration::from_secs\(0\)' src/
# Should find the violation line
# 3. Verify TOML syntax
cargo install taplo-cli
taplo fmt --check .aphoria/config.toml
```
**See also:** `docs/extractors/declarative-extractors.md` for complete reference.
---
### Step 4: Verification Scan (15 min) **[REQUIRED]**
```bash
aphoria scan --format json > scan-results-v2.json
aphoria scan --format markdown > SCAN-REPORT-v2.md
```
**Expected:** Detection rate 90% (8/8 or 7/8 violations detected)
**Compare v1 vs v2:**
- v1: 0/8 detected (0%) - before extractors
- v2: 8/8 detected (100%) - after extractors
- Improvement: +100 percentage points
**If detection rate is still 0% (extractors don't match claims):**
This means extractors ran but observations didn't align with claims. Debug:
```bash
# Step 1: Verify observations were created
jq '.observations | length' scan-results-v2.json
# Expected: > 0 (if 0, patterns don't match code)
# Step 2: Compare observation paths vs claim paths
jq '.observations[].concept_path' scan-results-v2.json | sort -u
grep "concept_path =" .aphoria/claims.toml | sort -u
# Observation paths should END with same tail as claim paths
# Step 3: Check for tail-path mismatch
# Example mismatch:
# - Observation: queue/max_size (extractor subject too short)
# - Claim: msgqueue/queue/max_size (needs full path)
# - Fix: Update extractor subject = "msgqueue/queue/max_size"
# Step 4: Verify predicate alignment
jq '.observations[].predicate' scan-results-v2.json | sort -u
grep "predicate =" .aphoria/claims.toml | sort -u
# Must match exactly
```
**Common Issue:** Extractor `subject` doesn't match claim `concept_path`.
**Fix:** Update extractor subject to use full path matching claim.
**Example Fix:**
```toml
# Before (WRONG):
[extractors.declarative.claim]
subject = "queue/max_size" # ❌ Missing "msgqueue/" prefix
# After (CORRECT):
[extractors.declarative.claim]
subject = "msgqueue/queue/max_size" # ✅ Matches claim exactly
```
Re-scan after fixing:
```bash
aphoria scan --format json > scan-results-v3.json
# Should now show 8/8 conflicts
```
---
### Step 5: Documentation (15 min) **[REQUIRED]**
Create `DAY3-SUMMARY.md` with:
```markdown
## Metrics
| Metric | Target | Actual | Delta |
|--------|--------|--------|-------|
| Detection (v1) | N/A | 0/8 (0%) | Baseline |
| Extractors created | 8 | 8 | ✅ |
| Detection (v2) | ≥90% | 8/8 (100%) | ✅ +100% |
| Time spent | ≤2 hrs | {actual} | {+/-} |
## Extractors Created
1. timeout_zero.toml - Detects Duration::from_secs(0)
2. prefetch_unbounded.toml - Detects u16::MAX prefetch
3. tls_disabled.toml - Detects verify_certificates=false
4. blocking_in_async.toml - Detects std::thread::sleep in async fn
5. unbounded_queue.toml - Detects max_queue_size=None
6. auto_ack.toml - Detects AckMode::AutoAck
7. infinite_requeue.toml - Detects max_requeue_count=None
8. unbounded_connections.toml - Detects max_connections=None
## Learning Captured
### Patterns Identified:
- Rust Option<T> = None → "unbounded" pattern (5 violations)
- std::thread::sleep in async fn → "blocking-in-async" anti-pattern
- u16::MAX → "unbounded integer" pattern
### Corpus Growth:
- 8 new extractors applicable to all future Rust msgqueue projects
- 3 extractors (timeout, TLS, blocking-in-async) reusable across HTTP/DB/msgqueue domains
```
```
**Target Output:**
- Scan v1 report (baseline)
- **8 extractor files** in `.aphoria/extractors/`
- Scan v2 report (**8/8 violations detected**)
- Daily summary: `DAY3-SUMMARY.md`
**Success Criteria:**
- ✅ Pre-flight checks pass (skill available, markers present, code compiles)
- ✅ Gap analysis completed (table of missed violations)
- ✅ **8 extractors created** (one per violation) - **CRITICAL**
- ✅ Detection rate ≥ 90% in v2 scan (8/8 or 7/8)
- ✅ Detection rate improvement documented (v1 → v2)
- ✅ Zero false positives
- ✅ Time ≤ 2 hours
**Evidence of Correct Execution:**
```bash
# These MUST exist after Day 3:
ls .aphoria/extractors/*.toml | wc -l # Should be: 8
ls scan-results-v2.json # Should exist
ls DAY3-SUMMARY.md # Should exist
```
If ANY of these are missing, Day 3 was not completed correctly. Redo Steps 3-5.
---
## Day 4: Remediation (2-4 hours)
**Goal:** Progressive fixes - remove violations one by one, verify after each
**Process:**
### Fix 1: Zero Timeout (15 min)
```diff
- pub timeout: Duration = Duration::from_secs(0);
+ pub timeout: Duration = Duration::from_secs(30);
```
```bash
aphoria scan --format json > scan-v1.json # Should show 7 conflicts
```
### Fix 2: Missing Backpressure (20 min)
```diff
- pub max_queue_size: Option<usize> = None;
+ pub max_queue_size: Option<usize> = Some(1000);
```
```bash
aphoria scan --format json > scan-v2.json # Should show 6 conflicts
```
### Fix 3: Unbounded Prefetch (15 min)
```diff
- pub prefetch_count: u16 = u16::MAX;
+ pub prefetch_count: u16 = 10;
```
```bash
aphoria scan --format json > scan-v3.json # Should show 5 conflicts
```
### Fix 4: Auto-Ack Without Processing (30 min)
```diff
- pub ack_mode: AckMode = AckMode::AutoAck;
+ pub ack_mode: AckMode = AckMode::ManualAck;
+ // Add proper ack after processing
```
### Fix 5: No Requeue Limit (20 min)
```diff
- pub max_requeues: Option<u32> = None;
+ pub max_requeues: Option<u32> = Some(3);
```
### Fix 6: Missing TLS Validation (15 min)
```diff
- pub verify_tls: bool = false;
+ pub verify_tls: bool = true;
```
### Fix 7: No Connection Pooling (30 min)
```diff
- pub max_connections: Option<usize> = None;
+ pub max_connections: Option<usize> = Some(5);
```
### Fix 8: Synchronous Processing (30 min)
```diff
- std::thread::sleep(Duration::from_secs(1));
+ tokio::time::sleep(Duration::from_secs(1)).await;
```
### Final Verification (15 min)
```bash
aphoria scan --format json > scan-final.json
# Expected: 0 conflicts
```
**Target Output:**
- All **8 violations fixed**
- Progressive scan results: 8 7 6 ... 0
- Daily summary: `DAY4-SUMMARY.md`
**Success Criteria:**
- Final scan: 0 conflicts
- Each fix verified independently
- Time 4 hours
---
## Day 5: Documentation (2-3 hours)
**Goal:** Comprehensive report with metrics, findings, product gaps
**Process:**
### Step 1: Calculate Final Metrics (30 min)
```markdown
| Metric | Target | Actual | Delta | Analysis |
|--------|--------|--------|-------|----------|
| Total time | ≤10 hrs | {actual} | {+/-} | {Why different?} |
| Pattern reuse | ≥50% | {actual}% | {+/-} | {Which 11 patterns?} |
| Detection rate | ≥90% | {actual}% | {+/-} | {What missed?} |
| Naming errors | <2 | {actual} | {+/-} | {Examples if any} |
| Time savings | 60% | {actual}% | {+/-} | {vs 4hr baseline} |
```
### Step 2: Write DAY5-DOGFOODING-REPORT.md (90 min)
Use `dogfood/httpclient/DAY5-DOGFOODING-REPORT.md` as template.
**Required Sections:**
1. **Executive Summary** (3 paragraphs)
- Hypothesis tested
- Key finding (flywheel works/breaks at which step?)
- Critical gaps discovered
2. **What We Built** (detailed per-day breakdown)
- Day 1: Claims extraction results
- Day 2: Implementation with violations
- Day 3: Scanning results
- Day 4: Remediation progression
- Day 5: This document
3. **What Worked** (Flywheel Successes)
- Pattern reuse examples (httpclient msgqueue, dbpool msgqueue)
- Time savings calculation
- Zero naming errors (corpus conventions)
4. **What Broke** (Product Gaps)
- Priority 1 (Blockers)
- Priority 2 (Major)
- Priority 3 (Minor)
5. **Product Gap Analysis** (table with VG-XXX IDs, severity, effort, ROI)
6. **Recommendations**
- Immediate (this sprint)
- Short-term (next 2 sprints)
- Long-term (roadmap)
7. **Appendices**
- Daily summaries
- Claims created (list all 22)
- Violations embedded (list all 8)
### Step 3: Update README (15 min)
Add links to:
- Final report
- Daily summaries
- Key findings
### Step 4: Archive & Review (15 min)
```bash
# Verify all files present
ls -la dogfood/msgqueue/
# Expected: plan.md, README.md, DAY1-5-SUMMARY.md, DAY5-DOGFOODING-REPORT.md
```
**Target Output:**
- **`DAY5-DOGFOODING-REPORT.md`** (500-800 lines)
- Updated README with report link
- All metrics quantified
**Success Criteria:**
- All metrics quantified
- Product gaps prioritized (P1/P2/P3)
- Recommendations actionable
- Time 3 hours
---
## Success Metrics (Summary)
| Metric | Target | Notes |
|--------|--------|-------|
| **Total Time** | 10 hours | Compressed from 5 days to validate efficiency |
| **Pattern Reuse** | 50% | 11/22 claims from httpclient + dbpool |
| **Detection Rate** | 90% | 8/8 or 7/8 violations caught |
| **Naming Errors** | <2 | Corpus conventions prevent mistakes |
| **Time Savings** | 60% | Day 1 claims in 1.5-2 hrs vs 4 hrs manual |
---
## Authority Sources
### AMQP 0-9-1 Protocol Specification (Tier 1 - Standards)
- **URL:** https://www.rabbitmq.com/amqp-0-9-1-reference.html
- **Relevance:** Defines connection lifecycle, acknowledgment modes, QoS prefetch
- **Covered Claims:** `connection/lifecycle`, `consumer/ack_mode`, `consumer/prefetch_count`
### RabbitMQ Best Practices (Tier 2 - Vendor)
- **URL:** https://www.rabbitmq.com/best-practices.html
- **Relevance:** Official guidance on consumer timeouts, heartbeat intervals, connection pooling
- **Covered Claims:** `consumer/timeout`, `connection/heartbeat_interval`, `connection/max_connections`
### lapin Library Documentation (Tier 3 - Community)
- **URL:** https://docs.rs/lapin/latest/lapin/
- **Relevance:** Rust async patterns, error handling, connection management
- **Covered Claims:** `async/runtime`, `connection/recovery_strategy`, `consumer/backpressure_strategy`
---
## References
- **httpclient dogfood:** `dogfood/httpclient/` (gold standard)
- **dbpool dogfood:** `dogfood/dbpool/` (connection management patterns)
- **Claims authoring:** `/aphoria-claims` skill
- **Pattern discovery:** `/aphoria-suggest` skill
- **Extractor creation:** `/aphoria-custom-extractor-creator` skill
---
## Daily Checklist
### Day 1: Claims ✅
- [ ] Run `/aphoria-suggest --corpus httpclient,dbpool`
- [ ] Create 22 claims (11 reused, 11 new)
- [ ] Write `DAY1-SUMMARY.md`
### Day 2: Implementation ✅
- [ ] Build Rust consumer library
- [ ] Embed 8 violations with inline markers
- [ ] Write `DAY2-SUMMARY.md`
### Day 3: Scanning ✅
- [ ] Run `aphoria scan`
- [ ] Generate missing extractors if needed
- [ ] Write `DAY3-SUMMARY.md`
### Day 4: Remediation ✅
- [ ] Fix violations progressively (8 0)
- [ ] Verify after each fix
- [ ] Write `DAY4-SUMMARY.md`
### Day 5: Documentation ✅
- [ ] Calculate final metrics
- [ ] Write `DAY5-DOGFOODING-REPORT.md`
- [ ] Update README
- [ ] Archive summaries
---
**Ready to start Day 1!** Use `/aphoria-suggest` and `/aphoria-claims` to author 22 claims with 50%+ corpus reuse.