playbooks

home / skills / phrazzld / claude-config / fix

fix skill

/skills/fix

This skill diagnoses and fixes errors in code by delegating to Codex with context, then verifies through tests.

npx playbooks add skill phrazzld/claude-config --skill fix

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

Files (1)
SKILL.md
1.1 KB
---
name: fix
description: |
  Diagnose and fix errors with Codex delegation.
  Traces error to root cause, researches approach, delegates fix, verifies.
  Use when: bug reports, error messages, stack traces, test failures.
argument-hint: <error>
effort: high
---

# /fix

Diagnose. Delegate. Verify.

## Role

Senior engineer debugging a production or development issue.

## Objective

Fix the error described in `$ARGUMENTS`. Root cause, not symptom.

## Latitude

- Delegate fix to Codex with diagnosis context
- Research idiomatic approach before implementing
- Write failing test first when feasible

## Workflow

1. **Diagnose** — Read the full error, locate source, understand context, form hypothesis
2. **Research** — Find similar issues, check docs for idiomatic solution
3. **Delegate** — Codex with: root cause, minimal fix, run tests after
4. **Verify** — `pnpm test && pnpm typecheck && pnpm lint`
5. **Commit** — `fix: description`

## Key Question

After investigation, before fix: "Are we solving the root problem or treating a symptom?"

## Output

Error resolved, tests passing, commit created.

Overview

This skill diagnoses and fixes runtime and test errors by delegating implementation to Codex. It focuses on locating the root cause, researching the idiomatic solution, and applying a minimal, verifiable fix. The goal is a passing test suite and a clear commit that describes the root remedy.

How this skill works

I read the full error report, stack trace, and relevant code to form a hypothesis about the root cause. I research language- and framework-specific idioms and similar issues to pick an appropriate fix. I then delegate implementation to Codex with explicit context and a failing test when feasible, run the test/type/lint pipeline, and produce a commit describing the fix.

When to use it

  • You have a failing test, error message, or stack trace you can paste.
  • A production or development bug with unclear root cause that needs focused investigation.
  • Regression introduced after recent changes where tests or typechecks fail.
  • When you need an idiomatic implementation rather than a quick patch.

Best practices

  • Start by reproducing the error and identifying the minimal failing case before coding.
  • Ask: are we fixing the root cause or masking a symptom? Document that decision in the commit message.
  • Research docs and similar issues to prefer idiomatic fixes over hacks.
  • Write a failing test first when feasible to lock behavior and prevent regressions.
  • Keep the fix minimal and scope-limited; run tests, typecheck, and lint before committing.

Example use cases

  • Resolve a traceback in a web request handler by tracing the exception to a misused library API and replacing it with the supported call pattern.
  • Diagnose a flaky test failing under CI by reproducing locally, isolating the race condition, adding a deterministic test, and fixing synchronization.
  • Fix a TypeError from data shape mismatch by adding validation and adapting the code path that produces the unexpected shape.
  • Address a new test failure after dependency upgrades by researching breaking changes and applying the minimal migration.

FAQ

What commands are used to verify the fix?

Run the project verification pipeline: pnpm test && pnpm typecheck && pnpm lint to ensure tests, types, and style pass.

Do you always write a failing test first?

When feasible, yes. Prefer a failing test to lock expected behavior, but create targeted fix-only patches if adding a test is impractical for the change.