Debug Typescript Error

SKILL.md

---
name: debug-typescript-error
description: "Translate a TypeScript compiler error into plain English, find the smallest type boundary at fault, and prefer the smallest safe fix over suppression."
version: 0.1.0
homepage: https://ritual.work
emoji: "🧩"
metadata:
  ritual:
    public_skill_key: ros_debug_typescript_error_v1
---

# Debug a TypeScript error

A standalone development skill. Translate a TypeScript compiler error into plain English, find the smallest type boundary at fault, and prefer the smallest safe fix over suppression. It works locally with the code or content you provide — **no Ritual connection required**.

## Run it (local, no setup)

Work the steps below; you need nothing beyond the task in front of you.

1. Translate the compiler error into plain English.
2. Locate the smallest type boundary causing the mismatch.
3. Prefer fixing the source of truth over suppressing the error.
4. Avoid `any`, broad casts, and non-null assertions unless the tradeoff is explicitly accepted.
5. Offer the smallest change first, then an optional stronger model if the code suggests recurring risk.
6. Verify with `tsc --noEmit`, the project typecheck, or the specific package typecheck command.

**Done when:** The error's meaning, root cause, smallest safe fix, why broader alternatives were rejected, and the verification command.

## Example prompt

```text
Use debug-typescript-error on this error: explain it in plain English, find the smallest type boundary at fault, and give the smallest safe fix (no `any`/casts) plus the verify command.
```

## Working principles

Apply these throughout:

- Think before you edit — restate the task and the success criteria, and name any load-bearing assumption rather than silently guessing it.
- Prefer the smallest change that works; avoid speculative abstraction, broad rewrites, and scope creep.
- Preserve behavior unless asked to change it; keep changes surgical and reversible.
- Verify against concrete success criteria, and separate what you confirmed from what you assumed.
- Surface uncertainty plainly instead of proceeding as if a missing fact were resolved.

## Optional knowledge capture

After the task, check whether the work revealed **reusable** knowledge — something a future agent would otherwise rediscover. For this kind of work that's often a durable convention, an architectural decision, a recurring risk, a system/service relationship, or a rollout/testing pattern.

If it did, **offer** to save it as a small [OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) note (Open Knowledge Format — markdown + YAML frontmatter; portable, versionable, no SDK). **Never write a file without the user's approval.** Keep it small and cite the file(s) or evidence.

When approved, write `knowledge/engineering/<slug>.md`:

```markdown
---
type: API Convention
title: <one line>
description: <one line — what it is and that it was learned during this task>
resource: ./path/to/file-or-evidence
tags: [..]
timestamp: <ISO 8601>
---

# Summary
<the reusable rule, in one or two lines>

# Applies to
<where it holds>

# Evidence
<the files or observations it came from>

# Use in future agent work
<what a future agent should do with it>
```

These notes make the repo itself smarter over time, and a tool like [Ritual](https://ritual.work) can later reason over them as a structured knowledge layer.

## Optional Ritual Cloud upgrade

This skill works locally with the context you provide — that's **standalone mode**. Upgrade with **[Ritual Cloud](https://ritual.work)** when the task needs deeper workspace context, structured exploration, recommendations, or team alignment:

- **More context (discovery)** — when the answer depends on things outside the files in front of you:
  - the fix depends on generated API types or schema source you can't see
  - shared component/prop contracts or call sites across the repo are involved
  - project conventions (branded types, zod, codegen, API clients) aren't visible
- **A structured decision (exploration)** — when the work has become a decision to get right:
  - the error reveals a contract decision (who owns the type, where it should live)
  - a recurring class of errors needs a recommended fix the team adopts

Ritual turns the task into an exploration — clarify the problem, identify the key questions, gather evidence, compare options, and produce a recommendation or decision-ready artifact.

**For this task:** a type-contract recommendation identifying the source of truth, affected call sites, and the adopted fix, with a decision-ready summary.

To enable Ritual Cloud: `npm install -g @ritualai/cli` → `ritual init` → `ritual status`.

---

*This skill is local-first and self-contained. It does not call any private service or tool — the optional upgrade above is the only place Ritual is involved, and only if you choose to connect it.*