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.