# WDMaker Operational Playbook - Common Scenarios & Responses

Quick reference guide for handling common situations during batch 001 execution and finalization.

---

## Scenario 1: Monitoring Agent Progress

### Situation
You want to check how many sites have been completed by the deployed agents.

### Response

**Quick Check** (1 minute):
```bash
tools/shared/list-sites.sh --batch 001 --status "I" | wc -l
# Output: Current count of completed sites (should increase over time)
```

**Detailed Check** (2 minutes):
```bash
# Current state
echo "Current I-status (completed): $(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l) / 572"
echo "Current O-status (waiting): $(tools/shared/list-sites.sh --batch 001 --status 'O' | wc -l)"
echo "Current i-status (processing): $(tools/shared/list-sites.sh --batch 001 --status 'i' | wc -l)"

# Progress percentage
I_COUNT=$(tools/shared/list-sites.sh --batch 001 --status 'I' | wc -l)
PERCENTAGE=$((I_COUNT * 100 / 572))
echo "Progress: $PERCENTAGE% ($I_COUNT / 572)"
```

**Expected Pattern**:
- Starts at 0 I-status
- Increases gradually (1-2 sites per minute during active wave execution)
- Accelerates during peak wave execution (25 agents per wave)
- Expected to reach 572 within 3-4 hours

**What to Do**:
- Check every 30 minutes during execution
- Rate of increase shows system health
- If no increase for 30 minutes, escalate to Scenario 3

---

## Scenario 2: Agent Execution Seems Slow

### Situation
You notice agents are completing fewer sites per minute than expected (~1-2 per minute expected).

### Response

**Investigate Slow Execution**:
```bash
# Check if some waves are delayed
echo "=== Sample Completed Sites ==="
tools/shared/list-sites.sh --batch 001 --status "I" | tail -20

# Check registry timestamps
echo "=== Recent Registry Updates ==="
grep "| I " .smbatcher/REGISTRY.md | tail -10 | cut -d'|' -f6
```

**Check System Resources**:
```bash
# Verify no O or i status sites (all should be either I or Q)
echo "Stuck in O: $(tools/shared/list-sites.sh --batch 001 --status 'O' | wc -l)"
echo "Stuck in i: $(tools/shared/list-sites.sh --batch 001 --status 'i' | wc -l)"
```

**Likely Causes & Solutions**:

| Cause | Indicator | Solution |
|-------|-----------|----------|
| Wave not deployed yet | O count = 572 | Wait for wave deployment |
| Agents still initializing | i count high | Wait 5-10 more minutes |
| One slow wave | I count plateaued | Check specific wave agents |
| System load | No file generation | Check site directories for incomplete writes |

**Expected After Checking**:
- If O count > 400: Most of wave still hasn't started
  - Wait 10 more minutes for wave deployment
- If i count > 100: Agents processing normally
  - Expect steady increases in I-status
- If i count < 50: No agents currently working
  - Check if wave deployment completed
  - If not, agents may be stuck or delayed

**Action**:
- If slow is temporary: Continue monitoring
- If slow persists >30 minutes: Escalate to Scenario 3

---

## Scenario 3: No Progress in 30+ Minutes

### Situation
I-status count hasn't increased for 30+ minutes. Expected: steady 1-2 sites/min.

### Response

**Diagnostic Steps**:

```bash
# Step 1: Verify registry still updates
echo "Last 10 registry updates:"
grep "| I " .smbatcher/REGISTRY.md | tail -10 | cut -d'|' -f6

# Step 2: Check for stuck agents
echo "Current O-status sites (should be 0):"
tools/shared/list-sites.sh --batch 001 --status "O" | wc -l

echo "Current i-status sites (should be 0):"
tools/shared/list-sites.sh --batch 001 --status "i" | wc -l

# Step 3: Sample file generation
for domain in $(tools/shared/list-sites.sh --batch 001 --status "I" | tail -5); do
  [ -f "sites/${domain}-v1/index.html" ] && echo "✓ $domain has files"
done

# Step 4: Check for error patterns
echo "=== Checking for errors in registry ==="
tail -100 .smbatcher/REGISTRY.md | grep -i "error"
```

**Likely Scenarios**:

### Scenario 3a: Registry Corruption
**Indicator**: grep shows no updates for 30+ minutes
**Solution**:
```bash
# Verify registry file integrity
wc -l .smbatcher/REGISTRY.md
# Should show ~575+ lines

# Check last modification time
stat .smbatcher/REGISTRY.md | grep Modify

# If corrupted, check backup or re-read from git
git log .smbatcher/REGISTRY.md | head -5
```

### Scenario 3b: All Sites Stuck at O
**Indicator**: O-status count = 572 (no agents started)
**Solution**:
```bash
# Check if waves deployed
# Review wave orchestrator IDs from DEPLOYMENT_LOG

# If waves show as deployed but not executing:
# 1. Verify site directory structure
ls -d sites/*-v1 | head -10
# Should have 572 directories

# 2. Verify DESIGN.md files exist
ls sites/*/DESIGN.md | head -10
# Should have all 572 files

# 3. If all present, wait 5-10 more minutes for agents to initialize
```

### Scenario 3c: Agent Execution Stuck
**Indicator**: i-status count high (agents processing) but I-status not advancing
**Solution**:
```bash
# Sample a few i-status sites to check file generation
for domain in $(tools/shared/list-sites.sh --batch 001 --status "i" | head -3); do
  echo "=== $domain ==="
  ls -la sites/${domain}-v1/ | grep -E "(index|styles|script|DESIGN)"
done

# If files exist but status not marked:
# - Agents may be stuck on verification
# - May need to manually mark completion (not recommended)
# - Wait additional 10 minutes

# If files don't exist:
# - Agents may have failed silently
# - May need to re-deploy agents for those sites
```

**Recommended Action**:
1. Verify no data corruption (check registry file size)
2. Wait additional 10 minutes (agents may be initializing)
3. If still stuck, consult AGENT_MONITORING_GUIDE.md Troubleshooting section
4. Last resort: Re-deploy agents for remaining sites

---

## Scenario 4: Batch 001 Approaches Completion (570+ I-Status)

### Situation
I-status count is 570+, very close to target of 572.

### Response

**Pre-Finalization Verification**:
```bash
# Confirm exactly 572 I-status sites
I_COUNT=$(tools/shared/list-sites.sh --batch 001 --status "I" | wc -l)
echo "Current I-status: $I_COUNT / 572"

# Check for any remaining O or i status sites
O_COUNT=$(tools/shared/list-sites.sh --batch 001 --status "O" | wc -l)
i_COUNT=$(tools/shared/list-sites.sh --batch 001 --status "i" | wc -l)
echo "Remaining O: $O_COUNT, Remaining i: $i_COUNT"

# If close but not exact 572:
if [ $I_COUNT -lt 572 ]; then
  echo "Waiting for final $((572 - I_COUNT)) sites to complete..."
  echo "Remaining sites:"
  REMAINING=$((572 - I_COUNT))

  # Show which sites are not yet at I
  tools/shared/list-sites.sh --batch 001 --status "O"
  tools/shared/list-sites.sh --batch 001 --status "i"

  echo "Estimated time: $(( REMAINING * 8 )) seconds"
fi
```

**When I-Status = 572**:
```bash
# Verify one more time
FINAL_COUNT=$(tools/shared/list-sites.sh --batch 001 --status "I" | wc -l)

if [ "$FINAL_COUNT" -eq 572 ]; then
  echo "✅ READY FOR FINALIZATION"

  # Execute finalization (reference BATCH_001_FINALIZATION_WORKFLOW.md)
  tools/implement/finish.sh --batch 001 --root .

  # Verify finalization succeeded
  Q_COUNT=$(tools/shared/list-sites.sh --batch 001 --status "Q" | wc -l)
  echo "Finalized sites: $Q_COUNT / 572"
else
  echo "⚠️ Still waiting for $((572 - FINAL_COUNT)) sites"
fi
```

---

## Scenario 5: Some Sites Missing Files

### Situation
You discover some I-status sites don't have generated files (index.html, styles.css, script.js).

### Response

**Identify Missing Files**:
```bash
# Check sample of I-status sites
echo "Checking I-status sites for file completeness:"
COUNT=0
for domain in $(tools/shared/list-sites.sh --batch 001 --status "I"); do
  if [ ! -f "sites/${domain}-v1/index.html" ]; then
    echo "❌ Missing index.html: $domain"
  fi
  COUNT=$((COUNT + 1))
  [ $COUNT -ge 20 ] && break
done
```

**Likely Causes**:
1. **Files not yet written**: Verification may be in progress
   - Solution: Wait 5 more minutes
2. **Agent failed silently**: Status marked but files not generated
   - Solution: Re-generate files for that site
3. **Filesystem issue**: Files generated but not accessible
   - Solution: Restart file access, check permissions

**Recovery Actions**:

```bash
# Option 1: Re-run agent for specific site
# (Requires access to agent deployment system)

# Option 2: Manually verify file generation
for domain in haroo.day jeongchi.boo; do
  echo "=== $domain ==="
  ls -lah sites/${domain}-v1/ | grep -E "\.(html|css|js|md)$"
done

# Option 3: If finalization ready, proceed
# (Most sites complete, a few missing files acceptable for finalization)
```

**Recommendation**: Proceed with finalization if:
- 95%+ of sites have files
- I-status count = 572 (agents reported completion)
- Missing files are edge cases (rare TLDs, special characters)

---

## Scenario 6: Ready to Execute Batch 001 Finalization

### Situation
You've confirmed 572 sites at I-status and verified prerequisites.

### Response

**Pre-Execution Checklist**:
```bash
# Final verification before finalization
echo "=== PRE-FINALIZATION CHECKLIST ==="

# 1. I-status must be exactly 572
I=$(tools/shared/list-sites.sh --batch 001 --status "I" | wc -l)
echo "✓ I-status count: $I / 572" [ $I -eq 572 ] || echo "  ❌ NOT READY"

# 2. No remaining O or i status
O=$(tools/shared/list-sites.sh --batch 001 --status "O" | wc -l)
i=$(tools/shared/list-sites.sh --batch 001 --status "i" | wc -l)
echo "✓ No pending O: $O / 0" [ $O -eq 0 ] || echo "  ❌ NOT READY"
echo "✓ No pending i: $i / 0" [ $i -eq 0 ] || echo "  ❌ NOT READY"

# 3. Batch file exists
[ -f .smbatcher/batches/Batch_001.md ] && echo "✓ Batch file exists" || echo "❌ Batch file missing"

# 4. Registry writable
touch .smbatcher/test && rm .smbatcher/test && echo "✓ Registry writable" || echo "❌ Registry not writable"

if [ $I -eq 572 ] && [ $O -eq 0 ] && [ $i -eq 0 ]; then
  echo ""
  echo "✅ ALL CHECKS PASS - READY FOR FINALIZATION"
  echo ""
  echo "Execute: tools/implement/finish.sh --batch 001 --root ."
else
  echo ""
  echo "❌ CHECKS FAILED - NOT READY FOR FINALIZATION"
fi
```

**Execute Finalization**:
```bash
# Run the finalization command
echo "Executing batch 001 finalization..."
tools/implement/finish.sh --batch 001 --root .

# Expected output:
# Processing batch 001...
# Transitioning 572 sites from I → Q...
# Updating registry...
# Batch 001 finalization complete.
```

**Post-Execution Verification**:
```bash
echo "=== POST-FINALIZATION VERIFICATION ==="

# Verify Q-status = 572
Q=$(tools/shared/list-sites.sh --batch 001 --status "Q" | wc -l)
echo "Q-status: $Q / 572" [ $Q -eq 572 ] && echo "✅ SUCCESS" || echo "⚠️ CHECK NEEDED"

# Verify no remaining I-status
REMAINING_I=$(tools/shared/list-sites.sh --batch 001 --status "I" | wc -l)
echo "Remaining I-status: $REMAINING_I / 0"

# Show completion summary
echo ""
echo "Batch 001 Finalization Complete!"
echo "Total sites finalized: $Q / 572"
```

---

## Scenario 7: Proceeding to Batch 010

### Situation
Batch 001 finalized (572 Q-status). Ready to process batch 010 (20241204.com).

### Response

**Reference**: BATCH_010_WORKFLOW.md (complete procedures)

**Quick Execution Path**:
```bash
echo "=== BATCH 010 WORKFLOW ==="

# 1. Create batch 010
echo "Step 1: Creating batch 010..."
tools/prepare/batch.sh --batch-size 1 --input-file sites.csv --version v1

# 2. Lock batch for design
echo "Step 2: Locking batch 010..."
tools/prepare/lock.sh --batch 010

# 3. Design phase
echo "Step 3: Deploying design agent..."
tools/mdesign/launch.py --batch 010
# Wait 5-10 minutes for completion

# 4. Implementation phase
echo "Step 4: Deploying implementation agent..."
tools/implement/mimplement-bg.sh --batch 010 --max-agents 1
# Wait 5-10 minutes for completion

# 5. Finalization
echo "Step 5: Finalizing batch 010..."
tools/implement/finish.sh --batch 010 --root .

# 6. Verify completion
echo "Step 6: Verifying completion..."
tools/shared/list-sites.sh --batch 010 --status "Q" | wc -l
# Expected: 1

echo "✅ BATCH 010 COMPLETE"
```

---

## Scenario 8: Emergency - Agent Failure

### Situation
Many agents appear to have failed, I-status not increasing as expected.

### Response

**Assess Damage**:
```bash
# Check how many sites affected
I=$(tools/shared/list-sites.sh --batch 001 --status "I" | wc -l)
O=$(tools/shared/list-sites.sh --batch 001 --status "O" | wc -l)
i=$(tools/shared/list-sites.sh --batch 001 --status "i" | wc -l)

echo "Current state: I=$I, O=$O, i=$i"
echo "Sites needing completion: $((O + i))"

if [ $O -gt 400 ]; then
  echo "⚠️ Agents haven't started yet"
  echo "Action: Wait 10 minutes for wave initialization"
elif [ $O -gt 50 ]; then
  echo "⚠️ Some waves may not have deployed"
  echo "Action: Check wave deployment status"
else
  echo "⚠️ Agents may have failed"
  echo "Action: Deploy new agents for remaining sites"
fi
```

**Recovery Action** (if agents failed):
```bash
# Re-deploy agents for remaining incomplete sites
echo "Re-deploying agents for remaining sites..."

# Option 1: Deploy full new wave
tools/implement/mimplement-bg.sh --batch 001 --max-agents 25

# Wait for completion
# Monitor progress
# Then proceed to finalization
```

**Last Resort** (if system unstable):
```bash
# If agents continue failing and finalization needed:
# Manually force completion for stuck sites

# NOT RECOMMENDED - only if absolutely necessary
# Check BATCH_001_FINALIZATION_WORKFLOW.md for safe procedures
```

---

## Quick Decision Tree

```
Is I-status increasing?
├─ YES → Continue monitoring (Scenario 1)
│   └─ I-status = 572?
│       └─ YES → Execute finalization (Scenario 6)
│       └─ NO → Wait for completion (Scenario 4)
│
└─ NO (stalled for 30+ minutes)
    ├─ Check registry for updates (Scenario 3)
    ├─ Check for stuck sites (Scenario 3)
    ├─ Check agent execution (Scenario 3)
    └─ If issues found → Recovery (Scenario 3 or 8)

After Batch 001 finalized?
└─ YES → Proceed to Batch 010 (Scenario 7)
```

---

## Key Contacts & References

- **Detailed Procedures**: BATCH_001_MASTER_PLAN.md
- **Monitoring Guide**: DEPLOYMENT_LOG_20260323.md
- **Finalization Steps**: BATCH_001_FINALIZATION_WORKFLOW.md
- **Batch 010 Steps**: BATCH_010_WORKFLOW.md
- **Verification**: VERIFICATION_CHECKLIST.md
- **Troubleshooting**: AGENT_MONITORING_GUIDE.md

---

## Summary

This playbook provides quick reference responses to common operational scenarios. For detailed procedures, consult the referenced documents.

**Expected Duration**: Batch 001 completion by ~18:30 UTC 2026-03-23
**Expected Duration**: Full project completion by ~19:05 UTC 2026-03-23
**Status**: All systems ready for autonomous execution