dsh-ecc-skills 0.4.0

package/skills/e2e-testing/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: e2e-testing
+description: Playwright E2E testing patterns, Page Object Model, configuration, CI/CD integration, artifact management, and flaky test strategies. Use when writing Playwright tests, structuring page objects, or fixing flaky E2E runs in CI.
+metadata:
+  origin: ECC
+---
+
+# E2E Testing Patterns
+
+Comprehensive Playwright patterns for building stable, fast, and maintainable E2E test suites.
+
+## Test File Organization
+
+```
+tests/
+├── e2e/
+│   ├── auth/
+│   │   ├── login.spec.ts
+│   │   ├── logout.spec.ts
+│   │   └── register.spec.ts
+│   ├── features/
+│   │   ├── browse.spec.ts
+│   │   ├── search.spec.ts
+│   │   └── create.spec.ts
+│   └── api/
+│       └── endpoints.spec.ts
+├── fixtures/
+│   ├── auth.ts
+│   └── data.ts
+└── playwright.config.ts
+```
+
+## Page Object Model (POM)
+
+```typescript
+import { Page, Locator } from '@playwright/test'
+
+export class ItemsPage {
+  readonly page: Page
+  readonly searchInput: Locator
+  readonly itemCards: Locator
+  readonly createButton: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.searchInput = page.locator('[data-testid="search-input"]')
+    this.itemCards = page.locator('[data-testid="item-card"]')
+    this.createButton = page.locator('[data-testid="create-btn"]')
+  }
+
+  async goto() {
+    await this.page.goto('/items')
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async search(query: string) {
+    await this.searchInput.fill(query)
+    await this.page.waitForResponse(resp => resp.url().includes('/api/search'))
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async getItemCount() {
+    return await this.itemCards.count()
+  }
+}
+```
+
+## Test Structure
+
+```typescript
+import { test, expect } from '@playwright/test'
+import { ItemsPage } from '../../pages/ItemsPage'
+
+test.describe('Item Search', () => {
+  let itemsPage: ItemsPage
+
+  test.beforeEach(async ({ page }) => {
+    itemsPage = new ItemsPage(page)
+    await itemsPage.goto()
+  })
+
+  test('should search by keyword', async ({ page }) => {
+    await itemsPage.search('test')
+
+    const count = await itemsPage.getItemCount()
+    expect(count).toBeGreaterThan(0)
+
+    await expect(itemsPage.itemCards.first()).toContainText(/test/i)
+    await page.screenshot({ path: 'artifacts/search-results.png' })
+  })
+
+  test('should handle no results', async ({ page }) => {
+    await itemsPage.search('xyznonexistent123')
+
+    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
+    expect(await itemsPage.getItemCount()).toBe(0)
+  })
+})
+```
+
+## Playwright Configuration
+
+```typescript
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report' }],
+    ['junit', { outputFile: 'playwright-results.xml' }],
+    ['json', { outputFile: 'playwright-results.json' }]
+  ],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    actionTimeout: 10000,
+    navigationTimeout: 30000,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+})
+```
+
+## Flaky Test Patterns
+
+### Quarantine
+
+```typescript
+test('flaky: complex search', async ({ page }) => {
+  test.fixme(true, 'Flaky - Issue #123')
+  // test code...
+})
+
+test('conditional skip', async ({ page }) => {
+  test.skip(process.env.CI, 'Flaky in CI - Issue #123')
+  // test code...
+})
+```
+
+### Identify Flakiness
+
+```bash
+npx playwright test tests/search.spec.ts --repeat-each=10
+npx playwright test tests/search.spec.ts --retries=3
+```
+
+### Common Causes & Fixes
+
+**Race conditions:**
+```typescript
+// Bad: assumes element is ready
+await page.click('[data-testid="button"]')
+
+// Good: auto-wait locator
+await page.locator('[data-testid="button"]').click()
+```
+
+**Network timing:**
+```typescript
+// Bad: arbitrary timeout
+await page.waitForTimeout(5000)
+
+// Good: wait for specific condition
+await page.waitForResponse(resp => resp.url().includes('/api/data'))
+```
+
+**Animation timing:**
+```typescript
+// Bad: click during animation
+await page.click('[data-testid="menu-item"]')
+
+// Good: wait for stability
+await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
+await page.waitForLoadState('networkidle')
+await page.locator('[data-testid="menu-item"]').click()
+```
+
+## Artifact Management
+
+### Screenshots
+
+```typescript
+await page.screenshot({ path: 'artifacts/after-login.png' })
+await page.screenshot({ path: 'artifacts/full-page.png', fullPage: true })
+await page.locator('[data-testid="chart"]').screenshot({ path: 'artifacts/chart.png' })
+```
+
+### Traces
+
+```typescript
+await browser.startTracing(page, {
+  path: 'artifacts/trace.json',
+  screenshots: true,
+  snapshots: true,
+})
+// ... test actions ...
+await browser.stopTracing()
+```
+
+### Video
+
+```typescript
+// In playwright.config.ts
+use: {
+  video: 'retain-on-failure',
+  videosPath: 'artifacts/videos/'
+}
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+        env:
+          BASE_URL: ${{ vars.STAGING_URL }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+## Test Report Template
+
+```markdown
+# E2E Test Report
+
+**Date:** YYYY-MM-DD HH:MM
+**Duration:** Xm Ys
+**Status:** PASSING / FAILING
+
+## Summary
+- Total: X | Passed: Y (Z%) | Failed: A | Flaky: B | Skipped: C
+
+## Failed Tests
+
+### test-name
+**File:** `tests/e2e/feature.spec.ts:45`
+**Error:** Expected element to be visible
+**Screenshot:** artifacts/failed.png
+**Recommended Fix:** [description]
+
+## Artifacts
+- HTML Report: playwright-report/index.html
+- Screenshots: artifacts/*.png
+- Videos: artifacts/videos/*.webm
+- Traces: artifacts/*.zip
+```
+
+## Wallet / Web3 Testing
+
+```typescript
+test('wallet connection', async ({ page, context }) => {
+  // Mock wallet provider
+  await context.addInitScript(() => {
+    window.ethereum = {
+      isMetaMask: true,
+      request: async ({ method }) => {
+        if (method === 'eth_requestAccounts')
+          return ['0x1234567890123456789012345678901234567890']
+        if (method === 'eth_chainId') return '0x1'
+      }
+    }
+  })
+
+  await page.goto('/')
+  await page.locator('[data-testid="connect-wallet"]').click()
+  await expect(page.locator('[data-testid="wallet-address"]')).toContainText('0x1234')
+})
+```
+
+## Financial / Critical Flow Testing
+
+```typescript
+test('trade execution', async ({ page }) => {
+  // Skip on production — real money
+  test.skip(process.env.NODE_ENV === 'production', 'Skip on production')
+
+  await page.goto('/markets/test-market')
+  await page.locator('[data-testid="position-yes"]').click()
+  await page.locator('[data-testid="trade-amount"]').fill('1.0')
+
+  // Verify preview
+  const preview = page.locator('[data-testid="trade-preview"]')
+  await expect(preview).toContainText('1.0')
+
+  // Confirm and wait for blockchain
+  await page.locator('[data-testid="confirm-trade"]').click()
+  await page.waitForResponse(
+    resp => resp.url().includes('/api/trade') && resp.status() === 200,
+    { timeout: 30000 }
+  )
+
+  await expect(page.locator('[data-testid="trade-success"]')).toBeVisible()
+})
+```

package/skills/ecc-tools-cost-audit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: ecc-tools-cost-audit
+description: Evidence-first ECC Tools burn and billing audit workflow. Use when investigating runaway PR creation, quota bypass, premium-model leakage, duplicate jobs, or GitHub App cost spikes in the ECC Tools repo.
+metadata:
+  origin: ECC
+---
+
+# ECC Tools Cost Audit
+
+Use this skill when the user suspects the ECC Tools GitHub App is burning cost, over-creating PRs, bypassing usage limits, or routing free users into premium analysis paths.
+
+This is a focused operator workflow for the sibling [ECC-Tools](../../ECC-Tools) repo. It is not a generic billing skill and it is not a repo-wide code review pass.
+
+## Skill Stack
+
+Pull these ECC-native skills into the workflow when relevant:
+
+- `autonomous-loops` for bounded multi-step audits that cross webhooks, queues, billing, and retries
+- `agentic-engineering` for tracing the request path into discrete, provable units
+- `customer-billing-ops` when repo behavior and customer-impact math must be separated cleanly
+- `search-first` before inventing helpers or re-implementing repo-local utilities
+- `security-review` when auth, usage gates, entitlements, or secrets are touched
+- `verification-loop` for proving rerun safety and exact post-fix state
+- `tdd-workflow` when the fix needs regression coverage in the worker, router, or billing paths
+
+## When To Use
+
+- user says ECC Tools burn rate, PR recursion, over-created PRs, usage-limit bypass, or premium-model leakage
+- the task is in the sibling `ECC-Tools` repo and depends on webhook handlers, queue workers, usage reservation, PR creation logic, or paid-gate enforcement
+- a customer report says the app created too many PRs, billed incorrectly, or analyzed code without producing a usable result
+
+## Scope Guardrails
+
+- work in the sibling `ECC-Tools` repo, not in `everything-claude-code`
+- start read-only unless the user clearly asked for a fix
+- do not mutate unrelated billing, checkout, or UI flows while tracing analysis burn
+- treat app-generated branches and app-generated PRs as red-flag recursion paths until proved otherwise
+- separate three things explicitly:
+  - repo-side burn root cause
+  - customer-facing billing impact
+  - product or entitlement gaps that need backlog follow-up
+
+## Workflow
+
+### 1. Freeze repo scope
+
+- switch into the sibling `ECC-Tools` repo
+- check branch and local diff first
+- identify the exact surface under audit:
+  - webhook router
+  - queue producer
+  - queue consumer
+  - PR creation path
+  - usage reservation / billing path
+  - model routing path
+
+### 2. Trace ingress before theorizing
+
+- inspect `src/index.*` or the main entrypoint first
+- map every enqueue path before suggesting a fix
+- confirm which GitHub events share a queue type
+- confirm whether push, pull_request, synchronize, comment, or manual re-run events can converge on the same expensive path
+
+### 3. Trace the worker and side effects
+
+- inspect the queue consumer or scheduled worker that handles analysis
+- confirm whether a queued analysis always ends in:
+  - PR creation
+  - branch creation
+  - file updates
+  - premium model calls
+  - usage increments
+- if analysis can spend tokens and then fail before output is persisted, classify it as burn-with-broken-output
+
+### 4. Audit the high-signal burn paths
+
+#### PR multiplication
+
+- inspect PR helpers and branch naming
+- check dedupe, synchronize-event handling, and existing-PR reuse
+- if app-generated branches can re-enter analysis, treat that as a priority-0 recursion risk
+
+#### Quota bypass
+
+- inspect where quota is checked versus where usage is reserved or incremented
+- if quota is checked before enqueue but usage is charged only inside the worker, treat concurrent front-door passes as a real race
+
+#### Premium-model leakage
+
+- inspect model selection, tier branching, and provider routing
+- verify whether free or capped users can still hit premium analyzers when premium keys are present
+
+#### Retry burn
+
+- inspect retry loops, duplicate queue jobs, and deterministic failure reruns
+- if the same non-transient error can spend analysis repeatedly, fix that before quality improvements
+
+### 5. Fix in burn order
+
+If the user asked for code changes, prioritize fixes in this order:
+
+1. stop automatic PR multiplication
+2. stop quota bypass
+3. stop premium leakage
+4. stop duplicate-job fanout and pointless retries
+5. close rerun/update safety gaps
+
+Keep the pass bounded to one to three direct fixes unless the same root cause clearly spans multiple files.
+
+### 6. Verify with the smallest proving steps
+
+- rerun only the targeted tests or integration slices that cover the changed path
+- verify whether the burn path is now:
+  - blocked
+  - deduped
+  - downgraded to cheaper analysis
+  - or rejected early
+- state the final status exactly:
+  - changed locally
+  - verified locally
+  - pushed
+  - deployed
+  - still blocked
+
+## High-Signal Failure Patterns
+
+### 1. One queue type for all triggers
+
+If pushes, PR syncs, and manual audits all enqueue the same job and the worker always creates a PR, analysis equals PR spam.
+
+### 2. Post-enqueue usage reservation
+
+If usage is checked at the front door but only incremented in the worker, concurrent requests can all pass the gate and exceed quota.
+
+### 3. Free tier on premium path
+
+If free queued jobs can still route into Anthropic or another premium provider when keys exist, that is real spend leakage even if the user never sees the premium result.
+
+### 4. App-generated branches re-enter the webhook
+
+If `pull_request.synchronize`, branch pushes, or comment-triggered runs fire on app-owned branches, the app can recursively analyze its own output.
+
+### 5. Expensive work before persistence safety
+
+If the system can spend tokens and then fail on PR creation, file update, or branch collision, it is burning cost without shipping value.
+
+## Pitfalls
+
+- do not begin with broad repo wandering; settle webhook -> queue -> worker first
+- do not mix customer billing inference with code-backed product truth
+- do not fix lower-value quality issues before the highest-burn path is contained
+- do not claim burn is fixed until the narrow proving step was rerun
+- do not push or deploy unless the user asked
+- do not touch unrelated repo-local changes if they are already in progress
+
+## Verification
+
+- root causes cite exact file paths and code areas
+- fixes are ordered by burn impact, not code neatness
+- proving commands are named
+- final status distinguishes local change, verification, push, and deployment

package/skills/email-ops/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: email-ops
+description: Evidence-first mailbox triage, drafting, send verification, and sent-mail-safe follow-up workflow for ECC. Use when the user wants to organize email, draft or send through the real mail surface, or prove what landed in Sent.
+metadata:
+  origin: ECC
+---
+
+# Email Ops
+
+Use this when the real task is mailbox work: triage, drafting, replying, sending, or proving a message landed in Sent.
+
+This is not a generic writing skill. It is an operator workflow around the actual mail surface.
+
+## Skill Stack
+
+Pull these ECC-native skills into the workflow when relevant:
+
+- `brand-voice` before drafting anything user-facing
+- `investor-outreach` for investor, partner, or sponsor-facing mail
+- `customer-billing-ops` when the thread is a billing/support incident rather than generic correspondence
+- `knowledge-ops` when the message or thread should be captured into durable context afterward
+- `research-ops` when a reply depends on fresh external facts
+
+## When to Use
+
+- user asks to triage inbox or archive low-signal mail
+- user wants a draft, reply, or new outbound email
+- user wants to know whether a mail was already sent
+- the user wants proof of which account, thread, or Sent entry was used
+
+## Guardrails
+
+- draft first unless the user clearly asked for a live send
+- never claim a message was sent without a real Sent-folder or client-side confirmation
+- do not switch sender accounts casually; choose the account that matches the project and recipient
+- do not delete uncertain business mail during cleanup
+- if the task is really DM or iMessage work, hand off to `messages-ops`
+
+## Workflow
+
+### 1. Resolve the exact surface
+
+Before acting, settle:
+
+- which mailbox account
+- which thread or recipient
+- whether the task is triage, draft, reply, or send
+- whether the user wants draft-only or live send
+
+### 2. Read the thread before composing
+
+If replying:
+
+- read the existing thread
+- identify the last outbound touch
+- identify any commitments, deadlines, or unanswered questions
+
+If creating a new outbound:
+
+- identify warmth level
+- select the correct channel and sender account
+- pull `brand-voice` before drafting
+
+### 3. Draft, then verify
+
+For draft-only work:
+
+- produce the final copy
+- state sender, recipient, subject, and purpose
+
+For live-send work:
+
+- verify the exact final body first
+- send through the chosen mail surface
+- confirm the message landed in Sent or the equivalent sent-copy store
+
+### 4. Report exact state
+
+Use exact status words:
+
+- drafted
+- approval-pending
+- sent
+- blocked
+- awaiting verification
+
+If the send surface is blocked, preserve the draft and report the exact blocker instead of improvising a second transport without saying so.
+
+## Output Format
+
+```text
+MAIL SURFACE
+- account
+- thread / recipient
+- requested action
+
+DRAFT
+- subject
+- body
+
+STATUS
+- drafted / sent / blocked
+- proof of Sent when applicable
+
+NEXT STEP
+- send
+- follow up
+- archive / move
+```
+
+## Pitfalls
+
+- do not claim send success without a sent-copy check
+- do not ignore the thread history and write a contextless reply
+- do not mix mailbox work with DM or text-message workflows
+- do not expose secrets, auth details, or unnecessary message metadata
+
+## Verification
+
+- the response names the account and thread or recipient
+- any send claim includes Sent proof or an explicit client-side confirmation
+- the final state is one of drafted / sent / blocked / awaiting verification