stemedb/applications/aphoria/dogfood/msgqueue/DAY3-READY.md

# Day 3 Ready - Fresh Start with New Documentation

**Date:** 2026-02-11
**Status:** Ready for Day 3 validation test
**Purpose:** Test new documentation fixes for extractor creation

---

## Pre-Day 3 State

✅ **Day 1 Complete:** 22 claims authored in `.aphoria/claims.toml`
✅ **Day 2 Complete:** 8 violations embedded in `src/` with inline markers
✅ **Day 3 Reset:** All previous Day 3 attempts removed (clean slate)

---

## What Was Reset

**Removed:**
- All scan results (scan-v1.json, scan-v2.json, etc.)
- All scan reports (SCAN-v1.md, etc.)
- Previous DAY3-SUMMARY.md (from failed attempts)
- Previous DAY3-READY.md
- `.aphoria/extractors/` directory
- All declarative extractors from `.aphoria/config.toml`

**Kept:**
- `.aphoria/claims.toml` (22 claims from Day 1)
- `src/` code with 8 violations (Day 2)
- `DAY1-SUMMARY.md` and `DAY2-SUMMARY.md`
- Claims template and documentation

---

## Day 3 Task: Validate New Documentation

**Goal:** Follow the new documentation to create extractors and achieve 100% detection rate.

**Target Time:** 30 minutes (vs 70 minutes in previous attempts)
**Target Detection Rate:** 100% (8/8 violations detected)
**Success Criteria:** Zero trial-and-error, all guidance from docs

---

## New Documentation to Use

### Primary References

1. **Declarative Extractors Reference**
   - File: `../../docs/extractors/declarative-extractors.md`
   - What it covers:
     - Complete field reference (name, pattern, languages, subject, predicate, value)
     - **CRITICAL:** `subject` field must EXACTLY match claim's `concept_path`
     - Validation workflow (check before scanning)
     - Debugging 0% detection (if it happens)
     - Common mistakes with fixes

2. **Worked Example**
   - File: `../../docs/examples/extractors/timeout-zero-example.md`
   - What it shows:
     - Complete flow: code → extractor → claim → conflict
     - Exact TOML format to copy
     - How path alignment works

3. **Updated Day 3 Plan**
   - File: `plan.md` (Day 3 section)
   - What's new:
     - Manual declarative extractor format (Step 3)
     - Validation workflow before scanning (Step 3)
     - Debug workflow for 0% detection (Step 4)

4. **Common Mistakes Guide**
   - File: `../../docs/dogfooding-common-mistakes.md`
   - What it covers:
     - Mistake #1: Skipping extractor creation entirely
     - Mistake #2: Creating extractors with wrong subject format (NEW)
     - How to verify correct execution

---

## Day 3 Workflow (Follow plan.md)

### Phase 1: Pre-Flight Check (5 min)

```bash
# Verify code compiles
cargo check

# Verify inline markers present
grep -r "@aphoria:claim" src/ | wc -l
# Expected: 8 markers
```

---

### Phase 2: Baseline Scan (15 min)

```bash
aphoria scan --format json > scan-v1.json
aphoria scan --format markdown > scan-v1.md
```

**Expected:** 0-20% detection rate (normal for new domain without extractors)

**Action:** Analyze which violations were missed.

---

### Phase 3: Create Extractors (30 min) **[CRITICAL]**

**Follow:** `plan.md` Day 3 Step 3 (updated with manual format)

**Key steps:**

1. **Read the reference docs:**
   - `../../docs/extractors/declarative-extractors.md` (field reference)
   - `../../docs/examples/extractors/timeout-zero-example.md` (example)

2. **For each violation, add extractor to `.aphoria/config.toml`:**

   ```toml
   [[extractors.declarative]]
   name = "descriptive_name"
   pattern = 'regex_matching_code'
   languages = ["rust"]

   [extractors.declarative.claim]
   subject = "FULL_CLAIM_CONCEPT_PATH"  # ← Copy from claim EXACTLY
   predicate = "claim_predicate"
   value = violation_value
   confidence = 0.95
   ```

3. **CRITICAL:** Find claim's `concept_path` and copy EXACTLY:

   ```bash
   # Find claim concept_path
   grep "id = \"msgqueue-015\"" -A 2 .aphoria/claims.toml
   # Output shows: concept_path = "msgqueue/queue/max_size"

   # Copy this EXACTLY into extractor subject
   subject = "msgqueue/queue/max_size"  # ✅ CORRECT
   ```

   **Common mistake:**
   ```toml
   subject = "queue/max_size"  # ❌ WRONG (missing msgqueue/ prefix)
   ```

4. **Validate BEFORE scanning:**

   ```bash
   # Check all subjects match claim concept_paths
   grep "subject =" .aphoria/config.toml
   grep "concept_path =" .aphoria/claims.toml
   # Subjects should be subset of concept_paths

   # Test patterns match code
   grep -rE 'max_queue_size:\s*None' src/
   # Should find the violation line
   ```

---

### Phase 4: Verification Scan (15 min)

```bash
aphoria scan --format json > scan-v2.json
aphoria scan --format markdown > scan-v2.md
```

**Expected:** ≥90% detection rate (8/8 or 7/8 violations detected)

**If still 0% detection:**

Follow debug workflow in `plan.md` Day 3 Step 4:

```bash
# Step 1: Check if observations were created
jq '.observations | length' scan-v2.json
# Expected: > 0

# Step 2: Compare observation paths vs claim paths
jq '.observations[].concept_path' scan-v2.json | sort -u
grep "concept_path =" .aphoria/claims.toml | cut -d'"' -f2 | sort -u
# Check for mismatches (missing prefix, etc.)
```

**Common issue:** Extractor `subject` doesn't match claim `concept_path`.
**Fix:** Update subject to use full path, re-scan.

---

### Phase 5: Documentation (15 min)

Create `DAY3-SUMMARY.md` with:

```markdown
## Metrics

| Metric | Target | Actual | Delta |
|--------|--------|--------|-------|
| Detection (v1) | N/A | X/8 (X%) | Baseline |
| Extractors created | 8 | 8 | ✅ |
| Detection (v2) | ≥90% | 8/8 (100%) | ✅ +100% |
| Time spent | ≤30 min | Y min | {+/-} |

## What Worked

- Declarative-extractors.md provided clear format reference
- Validation workflow caught subject mismatches before scanning
- Debug workflow helped fix 0% detection (if needed)
- Time saved: Z minutes vs 70 min in previous attempts

## What Broke

(None expected with new docs)

## Documentation Quality

- Declarative extractor reference: {rating}/5
- Worked example clarity: {rating}/5
- Validation workflow usefulness: {rating}/5
- Debug workflow usefulness: {rating}/5
```

---

## Success Criteria

After Day 3 completion, verify:

- [ ] 8 extractors created in `.aphoria/config.toml`
- [ ] All extractor subjects match claim concept_paths EXACTLY
- [ ] `scan-v2.json` shows ≥90% detection (8/8 or 7/8)
- [ ] `DAY3-SUMMARY.md` exists with metrics
- [ ] Time spent ≤30 minutes
- [ ] Zero trial-and-error (all guidance from docs)

**Evidence check:**

```bash
# Count extractors
grep -c "^\[\[extractors.declarative\]\]" .aphoria/config.toml
# Expected: 8

# Check detection improvement
jq '.summary.claims_conflict' scan-v1.json  # Should be low (0-2)
jq '.summary.claims_conflict' scan-v2.json  # Should be high (7-8)
```

---

## Expected Violations

These 8 violations should be detected after extractor creation:

1. **timeout=0** (src/config.rs:20)
   - Claim: msgqueue-001
   - Pattern: `timeout:\s*Duration::from_secs\(0\)`

2. **verify_certificates=false** (src/config.rs:68)
   - Claim: msgqueue-002
   - Pattern: `verify_certificates:\s*false`

3. **max_connections=None** (src/connection.rs:15)
   - Claim: msgqueue-003
   - Pattern: `max_connections:\s*None`

4. **blocking in async fn** (src/processor.rs:87)
   - Claim: msgqueue-009
   - Pattern: `std::thread::sleep`

5. **prefetch_count=u16::MAX** (src/consumer.rs:33)
   - Claim: msgqueue-012
   - Pattern: `prefetch_count:\s*u16::MAX`

6. **ack_mode=AutoAck** (src/consumer.rs:56)
   - Claim: msgqueue-013
   - Pattern: `ack_mode:\s*AckMode::AutoAck`

7. **max_queue_size=None** (src/config.rs:45)
   - Claim: msgqueue-015
   - Pattern: `max_queue_size:\s*None`

8. **max_requeue_count=None** (src/consumer.rs:65)
   - Claim: msgqueue-018
   - Pattern: `max_requeue_count:\s*None`

---

## Tips for Success

1. **Read the docs FIRST** - Don't skip declarative-extractors.md
2. **Copy concept_path EXACTLY** - This is the #1 mistake
3. **Validate before scanning** - Use grep to check alignment
4. **Test patterns with grep** - Verify regex works before adding to config
5. **Follow debug workflow if 0%** - plan.md Step 4 has solutions
6. **Track time** - Compare to 30 min target

---

## Previous Attempts (For Context)

**Attempt 1 (2026-02-10 AM):**
- Result: 0% detection
- Reason: Skipped Phase 4 entirely (didn't create extractors)
- Time: 20 minutes (incomplete)

**Attempt 2 (2026-02-10 PM):**
- Result: 0% detection
- Reason: Created 7 extractors but with wrong subject format (missing msgqueue/ prefix)
- Time: 70 minutes (trial-and-error)

**This Attempt (2026-02-11):**
- Expected: 100% detection
- Expected time: ≤30 minutes
- Using: New documentation fixes

---

## Ready to Start!

**Next command:**

```bash
cargo check  # Pre-flight: verify code compiles
```

Then follow `plan.md` Day 3 workflow step-by-step.

**Good luck! The docs should guide you to 100% detection without trial-and-error.**