octanejs/octane / .rulesync/skills/bug-hunter
bug-hunter
VerifiedFind 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.mdbefore assuming React mismatch is a bug
Workflow
-
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.
-
Reproduce before fixing
- Add or locate the smallest failing test/fixture.
- For compiler/runtime behavior, prefer
packages/octane/tests/_fixtures/*.tsrxplus 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.
-
Minimize
- Remove unrelated props, effects, timing, and DOM.
- Keep
.tsrxfixtures tiny. - Confirm the test fails for the intended reason, not setup/aliasing/jsdom.
-
Localize
- Runtime: inspect the owning
packages/octane/src/runtime/module's comments and closest tests. - Compiler: inspect
packages/octane/src/compiler/compile.jsand emitted output if needed. - SSR: inspect
runtime.server.ts,server/index.ts, hydration tests. - Bindings: compare existing package patterns and upstream React binding behavior.
- Runtime: inspect the owning
-
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.
-
Validate
- Run the new failing test until it passes.
- Run nearby affected tests.
- If runtime/compiler changed, consider wider
packages/octane/testsorpnpm testdepending on scope. - Run
pnpm typecheckwhen TS/API surfaces changed.
-
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. Controlledvalue/checkedis supported, but text editing uses nativeonInput;OCTANE_NATIVE_TEXT_ONCHANGEwarns about likely React-style host wiring without changing native behavior. Deliberate commit-on-blur usessuppressNativeChangeWarning. - Differential
innerHTMLcannot catch render counts, effect timing, refs, focus, or node move sets. - jsdom layout/focus limitations can masquerade as library bugs.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |