# Recurring Tool Patterns > Collection of frequently re-learned tool, process, and dispatch patterns that the swarm encounters across sessions. Each pattern has its own trigger, making this a multi-pattern reference rather than a single workflow. - Skill: `zaxbyhub/recurring-tool-patterns` (Agent Skill) - Install (CLI): `npx skillmds@latest add zaxbyhub/recurring-tool-patterns` - Raw SKILL.md: https://api.skillmd.com/api/skills/zaxbyhub/recurring-tool-patterns/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: zaxbyhub (https://skillmd.com/u/zaxbyhub) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zaxbyhub/recurring-tool-patterns --- # Recurring Tool & Process Patterns Multi-pattern reference for tool, dispatch, and process patterns the swarm has repeatedly re-learned. Each section below is independent and applies only when its trigger condition is met. --- ## Pattern A: tree-sitter TSX false positive handling **Trigger:** `syntax_check` fails on a `.tsx` file with JSX content. ### Required Procedure 1. Open the failing file and inspect the reported syntax error location. 2. Verify the error is a JSX tokenization failure (e.g. `unexpected token '<'` at a JSX component tag, or `unexpected token '}'` at a closing brace within JSX). 3. Verify `tsconfig.json` has `"jsx": "react-jsx"` (or `"preserve"`) in `compilerOptions`. 4. If BOTH conditions are met (tree-sitter JSX false positive + correct tsconfig): treat the `syntax_check` failure as PASS. Do NOT return to coder. 5. If the error is NOT a JSX tokenization failure (e.g. unclosed tag, mismatched braces, missing import): route through the normal coder-retry path — this is a real syntax error that tree-sitter correctly detected. ### Forbidden Shortcuts - Do NOT auto-pass all `.tsx` failures based on tsconfig alone — real syntax errors exist even in JSX-enabled projects. - Do NOT skip inspecting the actual failure message — the classification must be per-failure, not per-file. ### Reviewer Checks - Confirm the tsconfig `jsx` setting matches the project's actual build configuration. - Verify at least one skipped `.tsx` file's failure was actually a JSX tokenization error, not a real syntax error. --- ## Pattern B: Parallel Stage B dispatch **Trigger:** A TIER 2+ coder task is ready for Stage B review. ### Required Procedure - Dispatch `reviewer` and `test_engineer` TOGETHER in a single message as the default. - Only dispatch sequentially when: - Security-sensitive changes where reviewer findings would materially alter test scope. - Ambiguous requirements where the reviewer validates intended behavior before tests are written. - First-time changes to a subsystem with no existing test patterns. ### Forbidden Shortcuts - Do NOT dispatch sequentially as the default — this wastes significant time per task. - Do NOT skip the carve-out conditions — sequential dispatch IS appropriate for the three documented exceptions. ### Reviewer Checks - Verify that parallel dispatch was used unless the task explicitly met one of the three carve-out conditions. --- ## Pattern C: Agent prefix enforcement **Trigger:** Any agent delegation dispatch. ### Required Procedure - Before every delegation, verify the agent name includes the active swarm's prefix. - The active swarm prefix is derived from: - `.swarm/plan.json` → `swarm_id` field (primary) - `.swarm/context.md` → `Swarm:` line (fallback) - Example: if swarm is `modelrelay`, dispatch `modelrelay_coder`, not `coder` or `lowtier_coder`. ### Forbidden Shortcuts - Do NOT memorize the prefix from a prior session — it may differ per project. - Do NOT dispatch without checking — the swarm_id in plan.json is the source of truth. ### Reviewer Checks - Confirm the prefix used in all delegations matches the swarm_id in plan.json. --- ## Pattern D: ExtractionError plain-object handling **Trigger:** A Python `ExtractionError` is raised with a non-serializable payload object. ### Required Procedure 1. Verify the payload is JSON-compatible (no circular references, no `BigInt`, no `datetime` objects). 2. If JSON-compatible: wrap it with `json.loads(json.dumps(payload))` to produce a plain dict/list before further processing. 3. If NOT JSON-compatible (circular references, non-serializable types): implement a safe extractor that handles the specific type, or catch and log the raw object without attempting to clone. ### Forbidden Shortcuts - Do NOT use `json.dumps()` on circular references — it will raise `ValueError`. - Do NOT use `json.dumps()` on objects containing `datetime`, `Decimal`, `bytes`, or `numpy` types without a custom serializer. - Do NOT silently drop the error payload — always log the original object before conversion. ### Reviewer Checks - Verify that `json.dumps()` calls are wrapped in `try/except (TypeError, ValueError)` — a `default=` serializer does NOT handle circular container references. - Verify original error payload is logged before conversion (logged as raw object, not after attempted serialization). --- ## Pattern E: EdgeVec WASM API verification **Trigger:** Writing tests or code that uses EdgeVec in-browser HNSW index operations. ### Required Procedure 1. Before mocking EdgeVec API in tests, verify actual method signatures against the installed npm package version. 2. EdgeVec search operations return **similarity scores**, not distances — mock and test accordingly. 3. Check `package.json` or `node_modules/edgevec/` for the locked version; do NOT guess API shapes from memory or documentation alone. ### Forbidden Shortcuts - Do NOT mock EdgeVec APIs based on memory or external docs — the installed version's API is the source of truth. - Do NOT assume distance-based semantics — EdgeVec uses cosine similarity by default. ### Reviewer Checks - Verify that EdgeVec mocks match the installed version's actual TypeScript types (check `node_modules/edgevec/dist/` for type declarations). - Verify tests assert on similarity values in the correct range (typically 0–1, higher = more similar). ## Delegation Template When delegating a task affected by this skill, include: ``` SKILLS: file:.opencode/skills/generated/recurring-tool-patterns/SKILL.md ``` ## Source Knowledge IDs - 3b4854a0-93f1-4cf2-b091-a72c7c336a32 — tree-sitter syntax_check produces false positives on .tsx files with JSX content. When tsconfig.json declares `"jsx": "react-jsx"`, treat syntax_check failures on .tsx files as PASS after confirming the tsconfig setting. Do not return to coder for these failures. - 89c6518d-d3d2-47f8-af0f-f3d277ca318b — Parallel Stage B dispatch (reviewer + test_engineer together) saves significant time vs sequential dispatch and is the default for TIER 2+ changes. Only dispatch sequentially for security-sensitive changes, ambiguous requirements, or first-time work in a subsystem. - 387a5a19-8ae1-4e65-817d-7f23ff3c7f11 — Agent prefix must match active swarm (e.g. modelrelay_ for modelrelay). Wrong prefix calls non-existent agents. Verify swarm_id from plan.json or context.md before every delegation. - a6c83db5-c837-4a64-92d6-3e8b633c62ec — ExtractionError with non-serializable payload: wrap in JSON.parse(JSON.stringify()) to convert to plain object before processing. Fixes repeated crashes on the same extraction path. - e55b7c42-8f93-4775-9886-150dc01eefb9 — EdgeVec WASM API corrections: HNSW index operations use specific WASM method shapes. Search returns similarity scores, not distances. Always verify API shape against npm package before mocking in tests.