agim-cli 1.2.147 → 1.2.148

package/dist/core/skills/builtin/click-path-audit/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: click-path-audit
+description: "[ECC] Trace every user-facing button/touchpoint through its full state change sequence to find bugs where functions individually work but cancel each other out, produce wrong final state, or leave the UI in an inconsistent state. Use when: systematic debugging found no bugs but users report broken buttons, or after any major refactor touching shared state stores."
+origin: community
+---
+
+# /click-path-audit — Behavioural Flow Audit
+
+Find bugs that static code reading misses: state interaction side effects, race conditions between sequential calls, and handlers that silently undo each other.
+
+## The Problem This Solves
+
+Traditional debugging checks:
+- Does the function exist? (missing wiring)
+- Does it crash? (runtime errors)
+- Does it return the right type? (data flow)
+
+But it does NOT check:
+- **Does the final UI state match what the button label promises?**
+- **Does function B silently undo what function A just did?**
+- **Does shared state (Zustand/Redux/context) have side effects that cancel the intended action?**
+
+Real example: A "New Email" button called `setComposeMode(true)` then `selectThread(null)`. Both worked individually. But `selectThread` had a side effect resetting `composeMode: false`. The button did nothing. 54 bugs were found by systematic debugging — this one was missed.
+
+---
+
+## How It Works
+
+For EVERY interactive touchpoint in the target area:
+
+```
+1. IDENTIFY the handler (onClick, onSubmit, onChange, etc.)
+2. TRACE every function call in the handler, IN ORDER
+3. For EACH function call:
+   a. What state does it READ?
+   b. What state does it WRITE?
+   c. Does it have SIDE EFFECTS on shared state?
+   d. Does it reset/clear any state as a side effect?
+4. CHECK: Does any later call UNDO a state change from an earlier call?
+5. CHECK: Is the FINAL state what the user expects from the button label?
+6. CHECK: Are there race conditions (async calls that resolve in wrong order)?
+```
+
+---
+
+## Execution Steps
+
+### Step 1: Map State Stores
+
+Before auditing any touchpoint, build a side-effect map of every state store action:
+
+```
+For each Zustand store / React context in scope:
+  For each action/setter:
+    - What fields does it set?
+    - Does it RESET other fields as a side effect?
+    - Document: actionName → {sets: [...], resets: [...]}
+```
+
+This is the critical reference. The "New Email" bug was invisible without knowing that `selectThread` resets `composeMode`.
+
+**Output format:**
+```
+STORE: emailStore
+  setComposeMode(bool) → sets: {composeMode}
+  selectThread(thread|null) → sets: {selectedThread, selectedThreadId, messages, drafts, selectedDraft, summary} RESETS: {composeMode: false, composeData: null, redraftOpen: false}
+  setDraftGenerating(bool) → sets: {draftGenerating}
+  ...
+
+DANGEROUS RESETS (actions that clear state they don't own):
+  selectThread → resets composeMode (owned by setComposeMode)
+  reset → resets everything
+```
+
+### Step 2: Audit Each Touchpoint
+
+For each button/toggle/form submit in the target area:
+
+```
+TOUCHPOINT: [Button label] in [Component:line]
+  HANDLER: onClick → {
+    call 1: functionA() → sets {X: true}
+    call 2: functionB() → sets {Y: null} RESETS {X: false}  ← CONFLICT
+  }
+  EXPECTED: User sees [description of what button label promises]
+  ACTUAL: X is false because functionB reset it
+  VERDICT: BUG — [description]
+```
+
+**Check each of these bug patterns:**
+
+#### Pattern 1: Sequential Undo
+```
+handler() {
+  setState_A(true)     // sets X = true
+  setState_B(null)     // side effect: resets X = false
+}
+// Result: X is false. First call was pointless.
+```
+
+#### Pattern 2: Async Race
+```
+handler() {
+  fetchA().then(() => setState({ loading: false }))
+  fetchB().then(() => setState({ loading: true }))
+}
+// Result: final loading state depends on which resolves first
+```
+
+#### Pattern 3: Stale Closure
+```
+const [count, setCount] = useState(0)
+const handler = useCallback(() => {
+  setCount(count + 1)  // captures stale count
+  setCount(count + 1)  // same stale count — increments by 1, not 2
+}, [count])
+```
+
+#### Pattern 4: Missing State Transition
+```
+// Button says "Save" but handler only validates, never actually saves
+// Button says "Delete" but handler sets a flag without calling the API
+// Button says "Send" but the API endpoint is removed/broken
+```
+
+#### Pattern 5: Conditional Dead Path
+```
+handler() {
+  if (someState) {        // someState is ALWAYS false at this point
+    doTheActualThing()    // never reached
+  }
+}
+```
+
+#### Pattern 6: useEffect Interference
+```
+// Button sets stateX = true
+// A useEffect watches stateX and resets it to false
+// User sees nothing happen
+```
+
+### Step 3: Report
+
+For each bug found:
+
+```
+CLICK-PATH-NNN: [severity: CRITICAL/HIGH/MEDIUM/LOW]
+  Touchpoint: [Button label] in [file:line]
+  Pattern: [Sequential Undo / Async Race / Stale Closure / Missing Transition / Dead Path / useEffect Interference]
+  Handler: [function name or inline]
+  Trace:
+    1. [call] → sets {field: value}
+    2. [call] → RESETS {field: value}  ← CONFLICT
+  Expected: [what user expects]
+  Actual: [what actually happens]
+  Fix: [specific fix]
+```
+
+---
+
+## Scope Control
+
+This audit is expensive. Scope it appropriately:
+
+- **Full app audit:** Use when launching or after major refactor. Launch parallel agents per page.
+- **Single page audit:** Use after building a new page or after a user reports a broken button.
+- **Store-focused audit:** Use after modifying a Zustand store — audit all consumers of the changed actions.
+
+### Recommended agent split for full app:
+
+```
+Agent 1: Map ALL state stores (Step 1) — this is shared context for all other agents
+Agent 2: Dashboard (Tasks, Notes, Journal, Ideas)
+Agent 3: Chat (DanteChatColumn, JustChatPage)
+Agent 4: Emails (ThreadList, DraftArea, EmailsPage)
+Agent 5: Projects (ProjectsPage, ProjectOverviewTab, NewProjectWizard)
+Agent 6: CRM (all sub-tabs)
+Agent 7: Profile, Settings, Vault, Notifications
+Agent 8: Management Suite (all pages)
+```
+
+Agent 1 MUST complete first. Its output is input for all other agents.
+
+---
+
+## When to Use
+
+- After systematic debugging finds "no bugs" but users report broken UI
+- After modifying any Zustand store action (check all callers)
+- After any refactor that touches shared state
+- Before release, on critical user flows
+- When a button "does nothing" — this is THE tool for that
+
+## When NOT to Use
+
+- For API-level bugs (wrong response shape, missing endpoint) — use systematic-debugging
+- For styling/layout issues — visual inspection
+- For performance issues — profiling tools
+
+---
+
+## Integration with Other Skills
+
+- Run AFTER `/superpowers:systematic-debugging` (which finds the other 54 bug types)
+- Run BEFORE `/superpowers:verification-before-completion` (which verifies fixes work)
+- Feeds into `/superpowers:test-driven-development` — every bug found here should get a test
+
+---
+
+## Example: The Bug That Inspired This Skill
+
+**ThreadList.tsx "New Email" button:**
+```
+onClick={() => {
+  useEmailStore.getState().setComposeMode(true)   // ✓ sets composeMode = true
+  useEmailStore.getState().selectThread(null)      // ✗ RESETS composeMode = false
+}}
+```
+
+Store definition:
+```
+selectThread: (thread) => set({
+  selectedThread: thread,
+  selectedThreadId: thread?.id ?? null,
+  messages: [],
+  drafts: [],
+  selectedDraft: null,
+  summary: null,
+  composeMode: false,     // ← THIS silent reset killed the button
+  composeData: null,
+  redraftOpen: false,
+})
+```
+
+**Systematic debugging missed it** because:
+- The button has an onClick handler (not dead)
+- Both functions exist (no missing wiring)
+- Neither function crashes (no runtime error)
+- The data types are correct (no type mismatch)
+
+**Click-path audit catches it** because:
+- Step 1 maps `selectThread` resets `composeMode`
+- Step 2 traces the handler: call 1 sets true, call 2 resets false
+- Verdict: Sequential Undo — final state contradicts button intent

package/dist/core/skills/builtin/clickhouse-io/SKILL.md

@@ -0,0 +1,439 @@
+---
+name: clickhouse-io
+description: [ECC] ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.
+origin: ECC
+---
+
+# ClickHouse Analytics Patterns
+
+ClickHouse-specific patterns for high-performance analytics and data engineering.
+
+## When to Activate
+
+- Designing ClickHouse table schemas (MergeTree engine selection)
+- Writing analytical queries (aggregations, window functions, joins)
+- Optimizing query performance (partition pruning, projections, materialized views)
+- Ingesting large volumes of data (batch inserts, Kafka integration)
+- Migrating from PostgreSQL/MySQL to ClickHouse for analytics
+- Implementing real-time dashboards or time-series analytics
+
+## Overview
+
+ClickHouse is a column-oriented database management system (DBMS) for online analytical processing (OLAP). It's optimized for fast analytical queries on large datasets.
+
+**Key Features:**
+- Column-oriented storage
+- Data compression
+- Parallel query execution
+- Distributed queries
+- Real-time analytics
+
+## Table Design Patterns
+
+### MergeTree Engine (Most Common)
+
+```sql
+CREATE TABLE markets_analytics (
+    date Date,
+    market_id String,
+    market_name String,
+    volume UInt64,
+    trades UInt32,
+    unique_traders UInt32,
+    avg_trade_size Float64,
+    created_at DateTime
+) ENGINE = MergeTree()
+PARTITION BY toYYYYMM(date)
+ORDER BY (date, market_id)
+SETTINGS index_granularity = 8192;
+```
+
+### ReplacingMergeTree (Deduplication)
+
+```sql
+-- For data that may have duplicates (e.g., from multiple sources)
+CREATE TABLE user_events (
+    event_id String,
+    user_id String,
+    event_type String,
+    timestamp DateTime,
+    properties String
+) ENGINE = ReplacingMergeTree()
+PARTITION BY toYYYYMM(timestamp)
+ORDER BY (user_id, event_id, timestamp)
+PRIMARY KEY (user_id, event_id);
+```
+
+### AggregatingMergeTree (Pre-aggregation)
+
+```sql
+-- For maintaining aggregated metrics
+CREATE TABLE market_stats_hourly (
+    hour DateTime,
+    market_id String,
+    total_volume AggregateFunction(sum, UInt64),
+    total_trades AggregateFunction(count, UInt32),
+    unique_users AggregateFunction(uniq, String)
+) ENGINE = AggregatingMergeTree()
+PARTITION BY toYYYYMM(hour)
+ORDER BY (hour, market_id);
+
+-- Query aggregated data
+SELECT
+    hour,
+    market_id,
+    sumMerge(total_volume) AS volume,
+    countMerge(total_trades) AS trades,
+    uniqMerge(unique_users) AS users
+FROM market_stats_hourly
+WHERE hour >= toStartOfHour(now() - INTERVAL 24 HOUR)
+GROUP BY hour, market_id
+ORDER BY hour DESC;
+```
+
+## Query Optimization Patterns
+
+### Efficient Filtering
+
+```sql
+-- PASS: GOOD: Use indexed columns first
+SELECT *
+FROM markets_analytics
+WHERE date >= '2025-01-01'
+  AND market_id = 'market-123'
+  AND volume > 1000
+ORDER BY date DESC
+LIMIT 100;
+
+-- FAIL: BAD: Filter on non-indexed columns first
+SELECT *
+FROM markets_analytics
+WHERE volume > 1000
+  AND market_name LIKE '%election%'
+  AND date >= '2025-01-01';
+```
+
+### Aggregations
+
+```sql
+-- PASS: GOOD: Use ClickHouse-specific aggregation functions
+SELECT
+    toStartOfDay(created_at) AS day,
+    market_id,
+    sum(volume) AS total_volume,
+    count() AS total_trades,
+    uniq(trader_id) AS unique_traders,
+    avg(trade_size) AS avg_size
+FROM trades
+WHERE created_at >= today() - INTERVAL 7 DAY
+GROUP BY day, market_id
+ORDER BY day DESC, total_volume DESC;
+
+-- PASS: Use quantile for percentiles (more efficient than percentile)
+SELECT
+    quantile(0.50)(trade_size) AS median,
+    quantile(0.95)(trade_size) AS p95,
+    quantile(0.99)(trade_size) AS p99
+FROM trades
+WHERE created_at >= now() - INTERVAL 1 HOUR;
+```
+
+### Window Functions
+
+```sql
+-- Calculate running totals
+SELECT
+    date,
+    market_id,
+    volume,
+    sum(volume) OVER (
+        PARTITION BY market_id
+        ORDER BY date
+        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+    ) AS cumulative_volume
+FROM markets_analytics
+WHERE date >= today() - INTERVAL 30 DAY
+ORDER BY market_id, date;
+```
+
+## Data Insertion Patterns
+
+### Bulk Insert (Recommended)
+
+```typescript
+import { ClickHouse } from 'clickhouse'
+
+const clickhouse = new ClickHouse({
+  url: process.env.CLICKHOUSE_URL,
+  port: 8123,
+  basicAuth: {
+    username: process.env.CLICKHOUSE_USER,
+    password: process.env.CLICKHOUSE_PASSWORD
+  }
+})
+
+// PASS: Batch insert (efficient)
+async function bulkInsertTrades(trades: Trade[]) {
+  const values = trades.map(trade => `(
+    '${trade.id}',
+    '${trade.market_id}',
+    '${trade.user_id}',
+    ${trade.amount},
+    '${trade.timestamp.toISOString()}'
+  )`).join(',')
+
+  await clickhouse.query(`
+    INSERT INTO trades (id, market_id, user_id, amount, timestamp)
+    VALUES ${values}
+  `).toPromise()
+}
+
+// FAIL: Individual inserts (slow)
+async function insertTrade(trade: Trade) {
+  // Don't do this in a loop!
+  await clickhouse.query(`
+    INSERT INTO trades VALUES ('${trade.id}', ...)
+  `).toPromise()
+}
+```
+
+### Streaming Insert
+
+```typescript
+// For continuous data ingestion
+import { createWriteStream } from 'fs'
+import { pipeline } from 'stream/promises'
+
+async function streamInserts() {
+  const stream = clickhouse.insert('trades').stream()
+
+  for await (const batch of dataSource) {
+    stream.write(batch)
+  }
+
+  await stream.end()
+}
+```
+
+## Materialized Views
+
+### Real-time Aggregations
+
+```sql
+-- Create materialized view for hourly stats
+CREATE MATERIALIZED VIEW market_stats_hourly_mv
+TO market_stats_hourly
+AS SELECT
+    toStartOfHour(timestamp) AS hour,
+    market_id,
+    sumState(amount) AS total_volume,
+    countState() AS total_trades,
+    uniqState(user_id) AS unique_users
+FROM trades
+GROUP BY hour, market_id;
+
+-- Query the materialized view
+SELECT
+    hour,
+    market_id,
+    sumMerge(total_volume) AS volume,
+    countMerge(total_trades) AS trades,
+    uniqMerge(unique_users) AS users
+FROM market_stats_hourly
+WHERE hour >= now() - INTERVAL 24 HOUR
+GROUP BY hour, market_id;
+```
+
+## Performance Monitoring
+
+### Query Performance
+
+```sql
+-- Check slow queries
+SELECT
+    query_id,
+    user,
+    query,
+    query_duration_ms,
+    read_rows,
+    read_bytes,
+    memory_usage
+FROM system.query_log
+WHERE type = 'QueryFinish'
+  AND query_duration_ms > 1000
+  AND event_time >= now() - INTERVAL 1 HOUR
+ORDER BY query_duration_ms DESC
+LIMIT 10;
+```
+
+### Table Statistics
+
+```sql
+-- Check table sizes
+SELECT
+    database,
+    table,
+    formatReadableSize(sum(bytes)) AS size,
+    sum(rows) AS rows,
+    max(modification_time) AS latest_modification
+FROM system.parts
+WHERE active
+GROUP BY database, table
+ORDER BY sum(bytes) DESC;
+```
+
+## Common Analytics Queries
+
+### Time Series Analysis
+
+```sql
+-- Daily active users
+SELECT
+    toDate(timestamp) AS date,
+    uniq(user_id) AS daily_active_users
+FROM events
+WHERE timestamp >= today() - INTERVAL 30 DAY
+GROUP BY date
+ORDER BY date;
+
+-- Retention analysis
+SELECT
+    signup_date,
+    countIf(days_since_signup = 0) AS day_0,
+    countIf(days_since_signup = 1) AS day_1,
+    countIf(days_since_signup = 7) AS day_7,
+    countIf(days_since_signup = 30) AS day_30
+FROM (
+    SELECT
+        user_id,
+        min(toDate(timestamp)) AS signup_date,
+        toDate(timestamp) AS activity_date,
+        dateDiff('day', signup_date, activity_date) AS days_since_signup
+    FROM events
+    GROUP BY user_id, activity_date
+)
+GROUP BY signup_date
+ORDER BY signup_date DESC;
+```
+
+### Funnel Analysis
+
+```sql
+-- Conversion funnel
+SELECT
+    countIf(step = 'viewed_market') AS viewed,
+    countIf(step = 'clicked_trade') AS clicked,
+    countIf(step = 'completed_trade') AS completed,
+    round(clicked / viewed * 100, 2) AS view_to_click_rate,
+    round(completed / clicked * 100, 2) AS click_to_completion_rate
+FROM (
+    SELECT
+        user_id,
+        session_id,
+        event_type AS step
+    FROM events
+    WHERE event_date = today()
+)
+GROUP BY session_id;
+```
+
+### Cohort Analysis
+
+```sql
+-- User cohorts by signup month
+SELECT
+    toStartOfMonth(signup_date) AS cohort,
+    toStartOfMonth(activity_date) AS month,
+    dateDiff('month', cohort, month) AS months_since_signup,
+    count(DISTINCT user_id) AS active_users
+FROM (
+    SELECT
+        user_id,
+        min(toDate(timestamp)) OVER (PARTITION BY user_id) AS signup_date,
+        toDate(timestamp) AS activity_date
+    FROM events
+)
+GROUP BY cohort, month, months_since_signup
+ORDER BY cohort, months_since_signup;
+```
+
+## Data Pipeline Patterns
+
+### ETL Pattern
+
+```typescript
+// Extract, Transform, Load
+async function etlPipeline() {
+  // 1. Extract from source
+  const rawData = await extractFromPostgres()
+
+  // 2. Transform
+  const transformed = rawData.map(row => ({
+    date: new Date(row.created_at).toISOString().split('T')[0],
+    market_id: row.market_slug,
+    volume: parseFloat(row.total_volume),
+    trades: parseInt(row.trade_count)
+  }))
+
+  // 3. Load to ClickHouse
+  await bulkInsertToClickHouse(transformed)
+}
+
+// Run periodically
+setInterval(etlPipeline, 60 * 60 * 1000)  // Every hour
+```
+
+### Change Data Capture (CDC)
+
+```typescript
+// Listen to PostgreSQL changes and sync to ClickHouse
+import { Client } from 'pg'
+
+const pgClient = new Client({ connectionString: process.env.DATABASE_URL })
+
+pgClient.query('LISTEN market_updates')
+
+pgClient.on('notification', async (msg) => {
+  const update = JSON.parse(msg.payload)
+
+  await clickhouse.insert('market_updates', [
+    {
+      market_id: update.id,
+      event_type: update.operation,  // INSERT, UPDATE, DELETE
+      timestamp: new Date(),
+      data: JSON.stringify(update.new_data)
+    }
+  ])
+})
+```
+
+## Best Practices
+
+### 1. Partitioning Strategy
+- Partition by time (usually month or day)
+- Avoid too many partitions (performance impact)
+- Use DATE type for partition key
+
+### 2. Ordering Key
+- Put most frequently filtered columns first
+- Consider cardinality (high cardinality first)
+- Order impacts compression
+
+### 3. Data Types
+- Use smallest appropriate type (UInt32 vs UInt64)
+- Use LowCardinality for repeated strings
+- Use Enum for categorical data
+
+### 4. Avoid
+- SELECT * (specify columns)
+- FINAL (merge data before query instead)
+- Too many JOINs (denormalize for analytics)
+- Small frequent inserts (batch instead)
+
+### 5. Monitoring
+- Track query performance
+- Monitor disk usage
+- Check merge operations
+- Review slow query log
+
+**Remember**: ClickHouse excels at analytical workloads. Design tables for your query patterns, batch inserts, and leverage materialized views for real-time aggregations.