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>
724 lines
23 KiB
Markdown
724 lines
23 KiB
Markdown
# 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.
|