@seanyao/roll 0.5.0

package/skills/roll-debug/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: roll-debug
+description: Universal web debugger. Collects diagnostics (console/network/DOM) via Playwright, analyzes root causes, and suggests fixes. Works with or without Black Box (BB) integration.
+---
+
+# Roll Debug
+
+Universal web debugging tool that combines diagnostic collection and analysis into a single workflow: **Diagnose → Analyze → Suggest Fix**.
+
+Two collection modes:
+- **Native BB Mode**: Page has Black Box integrated; click button to collect rich diagnostic data
+- **Universal Diagnostic Mode**: Page has no BB; use Playwright to directly collect console/network/DOM/screenshot data
+
+## When to Use
+
+- "Debug the page"
+- "See what's wrong"
+- "Page shows blank"
+- "Feature not working"
+- User uploads a diagnostic file (`diagnostics-*.json`, `bb-report.json`)
+- "Analyze BB data", "look at the diagnostic file"
+- Any scenario requiring web page diagnosis
+
+## Quick Start
+
+```bash
+# Full workflow: collect + analyze + suggest fix (recommended)
+$roll-debug https://example.com/page
+
+# Collect data only, skip analysis
+$roll-debug https://example.com/page --no-analyze
+
+# Force universal diagnostic mode (no BB)
+$roll-debug https://example.com/page --universal
+
+# Collect + analyze + auto-fix
+$roll-debug https://example.com/page --fix
+
+# Analyze an existing report file (skip collection)
+$roll-debug --report /tmp/bb-report.json
+
+# Batch: diagnose multiple pages
+$roll-debug https://site.com/page1,https://site.com/page2
+$roll-debug --file urls.txt
+```
+
+## Two Collection Modes
+
+### Mode 1: Native BB (Page has Black Box integrated)
+
+```
+Page with BB  →  Playwright clicks BB button  →  Download diagnostic JSON
+```
+
+Requirements:
+- Page has `[data-testid="bb-toggle"]` button
+- Or exposes `window.__BB_DATA__`
+- Or stores data in `localStorage.bb_diagnostic`
+
+### Mode 2: Universal Diagnostic (No BB required)
+
+```
+Any page  →  Playwright injects collector  →  Gather console/network/DOM/screenshot
+```
+
+Collects:
+- Console logs (error/warn/info)
+- Network requests (failed XHR/fetch, slow requests)
+- DOM state (key elements visibility, HTML length)
+- Screenshot (full page + viewport)
+- Performance metrics (load time, FCP, LCP, render blocking)
+- JavaScript errors with stack traces
+
+## Full Workflow
+
+```
+User: "Debug the page"
+    │
+    ▼
+┌─────────────────────────────────────┐
+│ 1. Auto-detect collection mode      │
+│    ├── Try BB button → found?       │
+│    ├── Try window.__BB_DATA__?      │
+│    └── Fallback to Universal        │
+└──────────────────┬──────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────┐
+│ 2. Collect diagnostic data          │
+│    ├── Console logs                 │
+│    ├── Network requests             │
+│    ├── DOM state                    │
+│    └── Screenshot                   │
+└──────────────────┬──────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────┐
+│ 3. Analyze report                   │
+│    ├── Read /tmp/bb-report.json     │
+│    ├── Root cause analysis          │
+│    ├── Issue severity               │
+│    └── Structured findings          │
+└──────────────────┬──────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────┐
+│ 4. Suggest (or apply) fix           │
+│    ├── Actionable fix suggestions   │
+│    ├── Auto-fix via TCR (--fix)     │
+│    └── Deploy & verify              │
+└─────────────────────────────────────┘
+```
+
+## Usage Examples
+
+### Example 1: Full auto-detect + analyze (default)
+
+```bash
+$roll-debug https://yyy.up.railway.app/story/cars/chapter/1
+
+Detecting diagnostic capability...
+├── BB found: [data-testid="bb-toggle"]
+└── Using: Native BB mode
+
+Collecting data...
+├── Console: 3 errors, 5 warnings
+├── Network: 2 failed requests
+├── DOM: #app rendered, .content empty
+└── Screenshot: saved to /tmp/bb-screenshot.png
+
+Report: /tmp/bb-report.json
+
+Analyzing...
+
+## Diagnostic Analysis Report
+
+### Basic Info
+| Field | Value |
+|-------|-------|
+| Diagnostic Mode | native-bb |
+| Page URL | https://yyy.up.railway.app/story/cars/chapter/1 |
+
+### Key Findings
+| Metric | Value | Status |
+|--------|-------|--------|
+| contentLength | 0 | Not loaded |
+| audioState.src | "" | Not set |
+| hasText | false | No content |
+| Console Errors | 3 | Critical |
+| Network Failed | 2 | Critical |
+
+### Diagnosis Conclusion
+useEffect dependency error causing content not to load.
+Dependency `[chapter?.id]` should be `[chapter?.number]`
+
+### Suggested Fix
+Modify Player.tsx line 45, change useEffect dependency
+from `[chapter?.id]` to `[chapter?.number]`
+```
+
+### Example 2: Universal mode (no BB)
+
+```bash
+$roll-debug https://example.com --universal
+
+Universal diagnostic mode (no BB required)
+
+Collected:
+├── Console Errors: 2
+│   ├── TypeError: Cannot read property 'id' of undefined
+│   │   at Player.tsx:45
+│   └── ReferenceError: AudioContext is not defined
+├── Failed Network: 1
+│   └── GET https://api.example.com/data 404
+├── DOM State:
+│   ├── body.innerHTML length: 2340
+│   ├── #root: rendered
+│   ├── .loading: still visible (timeout?)
+│   └── .error-message: visible
+├── Performance:
+│   ├── DOMContentLoaded: 1.2s
+│   ├── First Contentful Paint: 2.3s
+│   └── Largest Contentful Paint: 4.5s
+└── Screenshot: /tmp/bb-screenshot.png
+
+Report: /tmp/bb-report.json
+
+Analyzing...
+
+### Key Findings
+| Metric | Value | Status |
+|--------|-------|--------|
+| Console Errors | 2 | Critical |
+| Network Failed | 1 | Critical |
+| DOM Rendering | Partial | Warning |
+| Load Time (LCP) | 4.5s | Slow |
+
+### Diagnosis Conclusion
+API endpoint returning 404 causes content not to load.
+AudioContext undefined suggests missing polyfill or browser incompatibility.
+
+### Suggested Fix
+1. Fix API route for /data endpoint (404)
+2. Add AudioContext polyfill or guard with `typeof AudioContext !== 'undefined'`
+```
+
+### Example 3: Analyze existing report file
+
+```bash
+$roll-debug --report /tmp/bb-report.json
+
+Reading report: /tmp/bb-report.json (mode: universal)
+
+### Key Findings
+...
+```
+
+## Analysis: Supported Report Formats
+
+| Format | Source | Description |
+|--------|--------|-------------|
+| Native BB | Page with Black Box | `window.__BB_DATA__` or `localStorage.bb_diagnostic` |
+| Universal | Playwright collector | Injected collector data |
+| Legacy | Old diagnostic files | Backward compatible |
+
+### Native BB Mode Fields
+
+```javascript
+const bbData = report.diagnostic.bbData;
+bbData.contentState?.hasText
+bbData.contentState?.contentLength
+bbData.audioState?.src
+bbData.audioState?.error
+bbData.hasAudio
+bbData.errors
+```
+
+### Universal Mode Fields
+
+```javascript
+const d = report.diagnostic;
+d.console.errors
+d.console.warnings
+d.network.failed
+d.network.slow
+d.dom.title
+d.dom['#root']
+d.dom.htmlLength
+d.performance.loadComplete
+d.performance.domContentLoaded
+d.errors
+```
+
+## Analysis Report Template
+
+```markdown
+## Diagnostic Analysis Report
+
+### Basic Info
+| Field | Value |
+|-------|-------|
+| Diagnostic Mode | {native-bb / universal} |
+| Page URL | {url} |
+| Collected At | {timestamp} |
+
+### Key Findings
+| Metric | Value | Status |
+|--------|-------|--------|
+| Console Errors | {N} | {Critical if >0, OK if 0} |
+| Network Failed | {N} | {Critical if >0, OK if 0} |
+| DOM Rendering | {status} | {OK / Not rendered} |
+| Load Time | {X}ms | {OK <2s, Slow 2-5s, Critical >5s} |
+
+### Diagnosis Conclusion
+{Root cause in plain language}
+
+### Suggested Fix
+{Actionable fix steps}
+```
+
+## Common Issue Patterns
+
+### Blank Page
+- `dom.htmlLength < 500` or `dom['#root'].visible = false`
+- Fix: Check console errors, add error boundary
+
+### Content Not Loading
+- `hasText = false` or `contentLength = 0`
+- Fix: Check API, refresh OSS URL, fix useEffect dependencies
+
+### Audio Error
+- `audioState.error` exists
+- Fix: Refresh signed URL, check audio format compatibility
+
+### Network Failure
+- `network.failed` has 4xx/5xx responses
+- Fix: Check API routes, add CORS headers
+
+### Performance Issues
+- LCP > 5s or DOMContentLoaded > 3s
+- Fix: Code-split large bundles, lazy-load images, cache API responses
+
+## Implementation Notes
+
+### Universal Mode Injection
+
+When page has no BB, inject a lightweight collector via `page.evaluate()`:
+
+```javascript
+window.__ROLL_DEBUG_COLLECTOR__ = {
+  console: [],
+  network: [],
+  errors: [],
+
+  init() {
+    // Hook console methods
+    ['error', 'warn', 'log', 'info'].forEach(method => {
+      const original = console[method];
+      console[method] = (...args) => {
+        this.console.push({method, args, timestamp: Date.now()});
+        original.apply(console, args);
+      };
+    });
+
+    // Hook fetch/XHR for network interception
+
+    // Listen for JS errors
+    window.addEventListener('error', e => {
+      this.errors.push({message: e.message, stack: e.error?.stack});
+    });
+  },
+
+  getData() {
+    return {
+      console: this.console,
+      network: this.network,
+      errors: this.errors,
+      dom: this.captureDOM(),
+      performance: this.capturePerformance()
+    };
+  }
+};
+```
+
+The injected collector only exists in the Playwright browser context — no cleanup needed.
+
+## Data Output Formats
+
+### Native BB Mode
+
+```json
+{
+  "mode": "native-bb",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "url": "https://example.com/page",
+  "bbData": {},
+  "collected": {
+    "console": [],
+    "network": []
+  }
+}
+```
+
+### Universal Mode
+
+```json
+{
+  "mode": "universal",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "url": "https://example.com/page",
+  "diagnostic": {
+    "console": {
+      "errors": [{"message": "...", "stack": "...", "timestamp": "..."}],
+      "warnings": [],
+      "logs": []
+    },
+    "network": {
+      "failed": [{"url": "...", "status": 404, "method": "GET"}],
+      "slow": [{"url": "...", "duration": 5000}]
+    },
+    "dom": {
+      "title": "Page Title",
+      "htmlLength": 2340,
+      "keyElements": {
+        "#root": {"exists": true, "visible": true, "children": 5},
+        ".error": {"exists": false}
+      }
+    },
+    "performance": {
+      "domContentLoaded": 1200,
+      "loadComplete": 2300,
+      "firstContentfulPaint": 2300,
+      "largestContentfulPaint": 4500
+    }
+  },
+  "screenshots": {
+    "viewport": "/tmp/roll-debug-viewport.png",
+    "fullPage": "/tmp/roll-debug-fullpage.png"
+  }
+}
+```
+
+## Capability Comparison
+
+| Feature | Native BB Mode | Universal Mode |
+|---------|---------------|----------------|
+| Requires BB integration | Yes | No |
+| Console logs | Yes | Yes |
+| Network data | Yes | Yes |
+| DOM state | Detailed | Key elements |
+| App-specific metrics | Yes | No |
+| Screenshot | Yes | Yes |
+| Performance metrics | Yes | Yes |
+| Works on any site | No | Yes |
+
+## Integration with Build Skills
+
+After `$roll-debug` finds issues:
+
+```bash
+# For a single-file bug fix
+# → Create FIX-XXX in backlog
+# → $roll-fix FIX-XXX
+
+# For a complex multi-step fix
+# → Create US-XXX in backlog
+# → $roll-story US-XXX
+```

package/skills/roll-design/ENGINEERING_CHECKLIST.md

@@ -0,0 +1,256 @@
+# Wukong Engineering Common Sense Checklist
+
+> **These are not best practices — they are baseline requirements.** Violations are bugs.
+
+## 1. Idempotency 🔁
+
+**Definition:** Performing the same operation N times produces the same result as performing it once.
+
+**Must test:**
+```typescript
+it('should be idempotent', async () => {
+  await operation(data)  // 1st
+  const result1 = await getState()
+  
+  await operation(data)  // 2nd
+  const result2 = await getState()
+  
+  await operation(data)  // 3rd
+  const result3 = await getState()
+  
+  expect(result1).toEqual(result2)
+  expect(result2).toEqual(result3)
+})
+```
+
+**Common scenarios:**
+- [ ] Import/ingest operations
+- [ ] Configuration updates
+- [ ] State transitions
+- [ ] API calls
+- [ ] File writes
+
+**Counter-example (this time):** Running ingest repeatedly → files duplicated 7 times
+
+---
+
+## 2. Cross-Module Contract Consistency 🔗
+
+**Definition:** Data/IDs/formats shared across multiple modules must be fully consistent.
+
+**Must check:**
+```typescript
+// Checklist
+- [ ] Is the ID generation algorithm consistent?
+- [ ] Is the data serialization format consistent?
+- [ ] Is path handling consistent? (e.g., / vs -)
+- [ ] Is it extracted into a shared function/constant?
+```
+
+**Test template:**
+```typescript
+it('should generate same ID across modules', () => {
+  const scannerId = generateScannerId('articles/test.md')
+  const inboxId = generateInboxId('articles/test.md')
+  expect(scannerId).toEqual(inboxId)
+})
+```
+
+**Counter-example (this time):** Scanner replaces `/` with `-`, inbox uses raw path → deduplication fails
+
+---
+
+## 3. Data Flow Integrity 🌊
+
+**Definition:** The complete data pipeline from producer to consumer must be unobstructed.
+
+**Must verify:**
+```typescript
+// Integration test - must exist
+describe('Data Flow: Producer -> Consumer', () => {
+  it('should write data that consumer can read', async () => {
+    await producer.write(testData)
+    const result = await consumer.read()
+    expect(result).toEqual(testData)
+  })
+})
+```
+
+**Checklist:**
+- [ ] Who writes the data? (Producer)
+- [ ] Who reads the data? (Consumer)
+- [ ] What is the intermediate storage? (state/file/cache)
+- [ ] Is there an integration test to verify?
+
+**Counter-example (this time):** Ingest doesn't write state, status can't read it → displays 0
+
+---
+
+## 4. Atomicity ⚛️
+
+**Definition:** An operation either fully succeeds or doesn't execute at all (no intermediate states).
+
+**Must consider:**
+- [ ] How to roll back on partial failure?
+- [ ] Is there a transaction mechanism?
+- [ ] How is data consistency guaranteed after a crash?
+
+**Test template:**
+```typescript
+it('should be atomic', async () => {
+  try {
+    await operation([item1, item2, INVALID_ITEM, item4])
+  } catch (e) {
+    // After failure, already-processed items should be rolled back
+    const state = await getState()
+    expect(state).toEqual(initialState)
+  }
+})
+```
+
+---
+
+## 5. Input Validation 🛡️
+
+**Definition:** Never trust any external input — it must be validated.
+
+**Must check:**
+- [ ] Null/undefined handling
+- [ ] Type checking
+- [ ] Range checking (array length, numeric range)
+- [ ] Special character/injection attack protection
+- [ ] File path traversal protection
+
+**Test template:**
+```typescript
+it('should handle invalid inputs gracefully', async () => {
+  await expect(operation(null)).rejects.toThrow()
+  await expect(operation('')).rejects.toThrow()
+  await expect(operation({})).rejects.toThrow()
+})
+```
+
+---
+
+## 6. Graceful Degradation 🪂
+
+**Definition:** When a dependency fails, the system should still provide limited functionality.
+
+**Must consider:**
+- [ ] What happens when an external API fails?
+- [ ] What happens when the database connection drops?
+- [ ] Is there a fallback mechanism?
+- [ ] What feedback does the user receive?
+
+**Test template:**
+```typescript
+it('should degrade gracefully when dependency fails', async () => {
+  mockDependency.toThrow('Network error')
+  
+  // Should not crash
+  const result = await operation()
+  
+  // Should return a fallback value or partial result
+  expect(result).toEqual(fallbackValue)
+})
+```
+
+---
+
+## 7. Observability 👁️
+
+**Definition:** System state must be visible and traceable.
+
+**Must provide:**
+- [ ] Progress feedback (for long-running operations)
+- [ ] State query interface (e.g., status command)
+- [ ] Error logs (failure reasons)
+- [ ] Key metrics (counts, durations)
+
+**Improvements made this time:**
+- Added `kkb status` to show raw files statistics ✅
+- Added `kkb compile` progress feedback ✅
+
+---
+
+## 8. Concurrency Safety 🧵
+
+**Definition:** Access to shared resources across multiple threads/processes must be safe.
+
+**Must consider:**
+- [ ] File read/write conflicts
+- [ ] Database transaction isolation level
+- [ ] Locking for shared in-memory state
+- [ ] Race conditions
+
+**Test template:**
+```typescript
+it('should handle concurrent writes', async () => {
+  await Promise.all([
+    operation(data1),
+    operation(data2),
+    operation(data3)
+  ])
+  
+  // Verify final state consistency
+  const state = await getState()
+  expect(state).toBeValid()
+})
+```
+
+---
+
+## Mandatory Check Process
+
+During the **Test Design Review** phase of each Story, the following must be answered:
+
+```markdown
+### Engineering Common Sense Checklist
+- [ ] **Idempotency**: Can it be run repeatedly? Are there tests?
+- [ ] **Cross-module contract**: Are IDs/formats/algorithms consistent?
+- [ ] **Data flow**: Is the producer → consumer pipeline complete?
+- [ ] **Atomicity**: Does partial failure trigger a rollback?
+- [ ] **Input validation**: Are all inputs validated?
+- [ ] **Graceful degradation**: What happens when a dependency fails?
+- [ ] **Observability**: Can the user see progress/status?
+- [ ] **Concurrency safety**: Is multi-threaded access safe?
+
+**If any item is not satisfied, tests/design must be added before writing implementation code.**
+```
+
+---
+
+## Automated Protection
+
+### Sentinel Patrol Rules
+```yaml
+# .github/roll-sentinel-config.yml
+checks:
+  idempotency:
+    - pattern: "ingest|import|sync"
+      require_test: "idempotency"
+  
+  cross_module_contract:
+    - files: ["src/*/index.ts"]
+      check: "shared_id_generation"
+  
+  data_flow:
+    - require_integration_test: true
+```
+
+### Pre-Commit Hook
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+echo "🔍 Checking engineering common sense..."
+
+# Check for idempotency tests
+if git diff --cached --name-only | grep -q "ingest\|import\|sync"; then
+  if ! grep -r "idempotency\|repeated run\|multiple times" tests/ 2>/dev/null; then
+    echo "❌ Missing idempotency tests!"
+    exit 1
+  fi
+fi
+
+echo "✅ Basic checks passed"
+```