| name | batch-observing |
| description | Parallel multi-user processing using Claude Code native teams. Leader spawns workers per user, each runs /ingest-dm, leader aggregates for cross-canvas patterns. |
| user-invocable | true |
| allowed-tools | Read, Write, Glob, Grep, Edit, Bash |
Batch Observing
Process multiple user DM exports in parallel using Claude Code native teams. A leader agent spawns one worker per user, each worker runs the /ingest-dm pipeline independently, then the leader aggregates results for cross-canvas pattern detection.
Core Principle
Parallel independence, centralized synthesis. Each worker processes one user independently. Cross-user patterns only emerge at the leader level after all workers complete.
Triggers
/batch-observe <path1> <path2> ... # Multiple DM export files
/batch-observe grimoires/keeper/imports/*.csv # Glob pattern
/batch-observe --dir grimoires/keeper/imports/ # All files in directory
When to Use
- Beta expansion: 5+ new users to onboard simultaneously
- Batch DM exports from Discord
- Initial population of the observer canvas set
- Re-processing after Score API data refresh
Workflow
Step 1: Parse Input
Collect the list of DM export files:
- Direct file paths from arguments
- Glob expansion from patterns
- Directory listing from
--dir
Validate each file exists and is readable.
Step 2: Create Team
TeamCreate:
team_name: "observer-batch-{date}"
description: "Parallel DM ingestion for {N} users"
Step 3: Create Tasks
For each input file, create a task:
TaskCreate:
subject: "Ingest DM: {filename}"
description: "Run /ingest-dm pipeline for {filename}"
Step 4: Spawn Workers
For each task, spawn a worker agent:
Task:
subagent_type: general-purpose
team_name: "observer-batch-{date}"
name: "worker-{username}"
prompt: |
You are an observer worker. Run the /ingest-dm pipeline for this file:
File: {filepath}
Steps:
1. Read the file and extract the username
2. Run: scripts/observer/wallet-resolve.sh {username}
3. Run: scripts/observer/score-api-query.sh profile {wallet} --format snapshot
4. Create the enriched canvas at grimoires/keeper/canvas/{username}.md
5. Follow the /ingest-dm SKILL.md template exactly
6. When done, mark your task as completed and send a message to the leader
with the canvas path and a summary of what was extracted.
Stagger starts: Delay 2-3 seconds between worker spawns to avoid Supabase rate limiting.
Step 5: Monitor Progress
Leader monitors via TaskList and incoming messages:
- Track completed vs pending workers
- Handle partial failures gracefully (some workers may fail)
- Collect canvas paths from worker completion messages
Step 6: Cross-Canvas Pattern Detection
Once all workers complete (or timeout after reasonable period), the leader:
6a: Common Gaps
- Read all new canvases
- Grep for
### GAP- sections
- Identify gaps appearing in 2+ canvases (e.g., "data staleness")
6b: Archetype Clustering
- Group users by behavior signals from hypotheses:
- Comparison-driven (earned vs possible)
- Completionist (badge/collection focused)
- Social (mention other users, community)
- Accuracy-focused (data verification)
6c: Signal Distribution
- Aggregate signal types across all canvases
- Calculate weight distribution (HIGH/MEDIUM/LOW)
- Identify dominant signal patterns
Step 7: Present Summary
Display archetype map and pattern summary to operator:
Batch Observation Complete: {N} users processed
Canvases Created:
- grimoires/keeper/canvas/user1.md (Rank #X, {tier})
- grimoires/keeper/canvas/user2.md (Rank #X, {tier})
...
Cross-Canvas Patterns:
- Data staleness: 3/5 users reported (xabbu, elcapitan, ncs)
- Badge display: 2/5 users mentioned (xabbu, cory)
Archetype Clusters:
- Comparison-driven: user1, user3 (focus on earned vs possible)
- Completionist: user2, user5 (badge/collection focus)
Signal Distribution:
- FEEL: 40% | ACCURACY: 30% | WEIGHTINGS: 20% | UX: 10%
Next Steps:
1. Review canvases and refine hypotheses to Level 3
2. Run /gap-to-issues to file cross-user gaps
3. Run /shape when ready to synthesize journeys
Step 8: Shutdown Team
SendMessage:
type: shutdown_request
recipient: each worker
Then: TeamDelete
Counterfactuals — Team Spawning Failures & Partial Results
Batch observing parallelizes canvas creation across multiple users via Claude Code teams. The failure modes are emergent — they arise from the interaction between concurrent workers, not from any single worker's logic.
Target (Correct Behavior)
The leader spawns one worker per user, each running /ingest-dm independently. Workers resolve wallets, call Score API, create canvases, and emit FeedbackEvents. The leader waits for all workers, collects results, detects cross-canvas patterns (shared pain points, common journey fragments), and produces an aggregate report. If a worker fails, the leader logs the failure and continues with successful results.
The critical invariant: the aggregate report accurately reflects which canvases were created, which failed, and what patterns were detected across only the successful canvases. Partial success is reported as partial — never inflated to full success.
Near Miss — Layer Violation
The seductively wrong behavior: treating partial results as complete when calculating cross-canvas patterns.
Scenario: 5 users in batch. Workers for users A, B, C succeed. Workers for D and E fail (wallet resolution timeout). The leader detects a pattern: "3 out of 3 users mentioned score confusion" and reports it as a strong signal. But D and E might have had different experiences — the pattern confidence should be "3 out of 5 attempted" (60%), not "3 out of 3 successful" (100%).
The layer violation is reporting a denominator that excludes failures:
- "All users reported X" (wrong — all successful users reported X)
- "Pattern detected across the cohort" (wrong — pattern detected across the successful subset)
- "No users mentioned Y" (wrong — two users weren't asked)
The correct behavior: always report patterns with both denominators — detected_in / successful_count and successful_count / total_attempted. A pattern found in 3/3 successes from 3/5 attempts is weaker evidence than 3/3 successes from 3/3 attempts. The aggregate report should include a "Coverage" metric showing what fraction of the intended batch completed.
Category Error — Semantic Collapse
The fundamentally wrong behavior: spawning team workers for users who already have canvases, then merging the new canvas with the existing one as if they were the same observation session.
Batch observing is designed for initial canvas creation from DM exports. If a user already has a canvas (from a prior /observe or /ingest-dm), spawning a worker for them creates a collision:
- Worker creates a new canvas from the DM export (complete scaffold)
- Existing canvas has curated hypotheses, validated quotes, enrichment history
- Merging overwrites curated content with raw scaffold data
The semantic collapse: treating "create" and "update" as the same operation because the output is the same file format. A new canvas is a hypothesis scaffold (LOW confidence, everything provisional). An existing canvas may contain validated hypotheses (MEDIUM confidence, evidence-backed). Overwriting validated with provisional is data loss.
The correct behavior: before spawning a worker, check if grimoires/keeper/canvas/{username}-canvas.md exists. If it does, either skip that user (report as "already observed") or run the worker in append-only mode (add new quotes to Quotes Library, do not overwrite User Profile or Level 3 Hypotheses). The leader should report skipped users separately from failed and successful users.
A concrete scenario demonstrating both failure modes together:
Batch of 8 users. Workers for users A, B, C succeed (new canvases). Worker for D fails (Score API timeout). Workers for E, F succeed (new canvases). Worker for G fails (wallet resolution error). Worker for H succeeds but H already had a canvas — the worker overwrites curated hypotheses with a raw scaffold.
The aggregate report says: "6 canvases created, pattern detected: 5/6 users mentioned score confusion." But the actual situation is:
- 5 genuinely new canvases (A, B, C, E, F)
- 1 overwritten canvas (H) — data loss, not creation
- 2 failures (D, G) — unknown user experiences
- Pattern denominator should be "5 out of 8 attempted" not "5 out of 6 successful"
The leader's report should categorize results into four buckets: created (new), updated (existing, append-only), failed (error), and skipped (existing, no new data). Each bucket affects pattern confidence differently.
Additionally, the team spawning itself can fail partially. If Claude Code's team infrastructure limits concurrent workers (e.g., max 5), a batch of 8 users requires sequencing. If the first 5 workers exhaust a rate limit (Score API, Supabase), workers 6-8 may all fail for infrastructure reasons, not data reasons. The leader should distinguish infrastructure failures (retry-worthy) from data failures (skip-worthy) in its error summary.
Error Handling
| Error | Resolution |
|---|
| Worker fails for one user | Log failure, continue with others. Report partial results. |
| Wallet resolution fails | Worker creates canvas without Score API data |
| Rate limiting on Supabase | Workers retry with backoff (built into supabase-query.sh caching) |
| Team creation fails | Fall back to sequential processing |
| All workers fail | Report error summary, no pattern detection |
| Duplicate canvas (user already has one) | Worker appends new quotes to existing canvas |
Validation
Related
/ingest-dm — Single-user pipeline (this skill parallelizes it)/daily-synthesis — Complementary pipeline for UI feedback/shape — Next step after batch observation (requires 3+ canvases)/gap-to-issues — File cross-user gaps detected in Step 6
