Skip to content

octanejs/octane / .agents/skills/bug-hunter

bug-hunter

Verified

Find and fix a bug in the octane monorepo. Use when given a failing test, a regression, or a report that behavior differs from expectation, including deciding whether a React mismatch is an intentional divergence.

Skill: Octane bug hunter

Use this to find, reproduce, minimize, and fix a suspected Octane bug.

Read first

  • AGENTS.md
  • Owning source and nearby tests
  • docs/differences-from-react.md before assuming React mismatch is a bug

Workflow

  1. State the suspected behavior

    • Expected behavior, actual behavior, package, environment, and reproduction path.
    • Decide whether the issue concerns runtime, compiler, SSR/hydration, Vite plugin, or an ecosystem binding.
  2. Reproduce before fixing

    • Add or locate the smallest failing test/fixture.
    • For compiler/runtime behavior, prefer packages/octane/tests/_fixtures/*.tsrx plus a focused *.test.ts.
    • For React parity, cite source React tests and use conformance/differential conventions.
    • For ecosystem packages, use that package's tests/ harness.
  3. Minimize

    • Remove unrelated props, effects, timing, and DOM.
    • Keep .tsrx fixtures tiny.
    • Confirm the test fails for the intended reason, not setup/aliasing/jsdom.
  4. Localize

    • Runtime: inspect the owning packages/octane/src/runtime/ module's comments and closest tests.
    • Compiler: inspect packages/octane/src/compiler/compile.js and emitted output if needed.
    • SSR: inspect runtime.server.ts, server/index.ts, hydration tests.
    • Bindings: compare existing package patterns and upstream React binding behavior.
  5. Patch carefully

    • Preserve documented intentional divergences.
    • Prefer fixing owning source over weakening tests.
    • Add regression coverage that would fail on the old behavior.
    • Keep changes minimal and idiomatic.
  6. Validate

    • Run the new failing test until it passes.
    • Run nearby affected tests.
    • If runtime/compiler changed, consider wider packages/octane/tests or pnpm test depending on scope.
    • Run pnpm typecheck when TS/API surfaces changed.
  7. Report

    • Root cause.
    • Files changed.
    • Tests added/updated and commands run.
    • Any remaining risks or intentional divergences.

Common traps

  • React synthetic onChange, StrictMode double invoke, and class components are not bugs by default. Controlled value/checked is supported, but text editing uses native onInput; OCTANE_NATIVE_TEXT_ONCHANGE warns about likely React-style host wiring without changing native behavior. Deliberate commit-on-blur uses suppressNativeChangeWarning.
  • Differential innerHTML cannot catch render counts, effect timing, refs, focus, or node move sets.
  • jsdom layout/focus limitations can masquerade as library bugs.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall