home / skills / commontoolsinc / labs / pattern-debug

pattern-debug skill

safe

This skill helps you debug pattern errors systematically by guiding you through TS checks, docs mapping, and minimal reproduction to verify fixes.

npx playbooks add skill commontoolsinc/labs --skill pattern-debug

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: pattern-debug
description: Debug pattern errors systematically
user-invocable: false
---

# Debug Pattern

Use `Skill("ct")` for ct CLI documentation if debugging deployment or charm issues.

## Read First
- `docs/development/debugging/workflow.md` - 5-step debugging process
- `docs/development/debugging/README.md` - Error reference matrix

## Process

1. **Check TypeScript errors:**
   ```bash
   deno task ct check pattern.tsx --no-run
   ```

2. **Match error to documentation:**
   - Read the error message carefully
   - Check `docs/development/debugging/README.md` for matching errors

3. **Check gotchas:**
   - `docs/development/debugging/gotchas/handler-inside-pattern.md`
   - `docs/development/debugging/gotchas/filter-map-find-not-a-function.md`
   - `docs/development/debugging/gotchas/onclick-inside-computed.md`

4. **Simplify to minimal reproduction:**
   - Comment out code until error disappears
   - Add back piece by piece to find root cause

5. **Fix and verify:**
   - Apply fix
   - Run tests to confirm

## Common Issues

**Handler defined inside pattern body:**
- Move handler() to module scope
- Only bind it inside pattern: `onClick={myHandler({ state })}`

**Type errors with Writable/Default:**
- Check if field needs write access → use Writable<>
- Check if field could be undefined → use Default<T, value>

**Action not triggering:**
- Ensure Output type includes action as Stream<void>
- Use .send() not .get() to trigger

## Done When
- Root cause identified
- Error fixed
- Tests pass again

Overview

This skill helps you debug pattern-related errors in TypeScript projects systematically. It provides a focused workflow to identify, reproduce, and fix issues related to patterns, handlers, actions, and type mismatches. Use it to accelerate root-cause analysis and verify fixes with tests.

How this skill works

The skill guides you through a five-step debugging process: run a type check, match the error to documented cases, verify common gotchas, reduce the code to a minimal repro, and apply a fix then run tests. It highlights specific checks for handler placement, writable/default type usage, and action triggering semantics so you can quickly pinpoint mistakes. Follow each step in sequence to move from error to verified resolution.

When to use it

A TypeScript type error appears in a pattern or component file
An action or output is not firing as expected in a pattern
You suspect a handler is incorrectly scoped inside a pattern body
You need to produce a minimal reproducible example for a tricky bug
Before opening an issue or submitting a patch to confirm root cause

Best practices

Run a full type check (no-run) on the pattern file before debugging runtime behavior
Consult documented error cases and gotchas that match your error message first
Move handler functions to module scope and bind them in the pattern body
Use Writable<> for fields that require write access and Default<T, value> for possibly undefined fields
When testing actions, ensure the Output type uses Stream<void> and invoke .send() to trigger

Example use cases

Resolve a TS error caused by a handler function defined inside a pattern body by relocating the handler to module scope
Fix a failing action by updating the Output type to include the action as Stream<void> and switching .get() to .send()
Diagnose a type mismatch where a field should be writable or have a default value and apply Writable<> or Default<> accordingly
Create a minimal reproduction by commenting out code sections until the error disappears, then add parts back to isolate the cause

FAQ

What is the first command I should run?

Start with a static type check on the pattern file, e.g. deno task ct check pattern.tsx --no-run.

Why move handlers to module scope?

Handlers inside the pattern body can cause scoping and re-creation issues; defining them at module scope and binding them in the pattern ensures stable references.