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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.8 KB |
SKILL.md
View on GitHub---
targets: ['*']
name: bug-hunter
description: 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.
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 |