debugging-with-opensrc

Debugging with OpenSrc

Overview

Debug external library behavior by reading source first.

Treat OpenSrc mirrors as the source of truth for installed versions.

When to Use This Skill

• Investigate an integration issue where application code depends on third-party library internals.
• Resolve a mismatch between documentation and observed runtime behavior.
• Confirm expected function signatures, defaults, error paths, or edge-case handling in an installed dependency.

OpenSrc Commands

# Sync all repos (run after git clone)
bun run opensrc:sync
 
# Fetch new package
bun run opensrc:use <package>        # npm package

Available Repos (opensrc/repos/github.com/)

Debugging Workflow

1. Define the failing behavior in one sentence (input, observed output, expected output).
2. Identify the exact dependency and package area involved.
3. Locate relevant source files in opensrc/repos/github.com/ using available project search tools.
4. Read implementation and related types before changing app code.
5. Trace call flow from public API to internal helpers.
6. Extract concrete expectations:
   • Function signatures and return types
   • Required wrappers/builders/options
   • Defaults and optional parameter behavior
   • Error handling and edge cases
7. Apply the fix in app code based on verified behavior.
8. Validate with targeted tests or reproduction steps.

Common Debugging Scenarios

Scenario: TanStack Form Validation Not Working

1. Read opensrc/repos/github.com/TanStack/form/packages/react-form/src/useForm.ts.
2. Inspect validator interface and expected return type.
3. Verify how Standard Schema integration is wired in the installed version.
4. Fix application code from verified behavior.

Scenario: TRPC Procedure Not Receiving Context

1. Read opensrc/repos/github.com/trpc/trpc/packages/server/src/core/middleware.ts.
2. Trace how context flows through middleware chain.
3. Verify middleware returns and opts.next() behavior in the active version.

Scenario: Effect Layer Not Providing Service

1. Read opensrc/repos/github.com/Effect-TS/effect/packages/effect/src/Layer.ts.
2. Compare Layer.effect and Layer.succeed behavior.
3. Verify Context.Tag usage against library patterns.

Scenario: Better Auth Session Not Persisting

1. Read opensrc/repos/github.com/better-auth/better-auth/packages/better-auth/src/.
2. Trace session handling and persistence flow.
3. Verify cookie/storage expectations in the installed code.

Key Principle

Source code is the truth.

• Documentation can be outdated
• Stack Overflow answers may not apply to your version
• Blog posts may use different configurations
• Only the source code shows exactly what happens

Example: Full Debugging Session

Problem: useSuspenseQuery returns undefined despite cached data.

1. Read opensrc/repos/github.com/TanStack/query/packages/react-query/src/useSuspenseQuery.ts and nearby type definitions.
2. Verify what input shape is expected in the installed version.
3. Confirm successful usage patterns in project code.
4. Apply a fix that matches verified expectations.

Note: A previous investigation in one version found that wrapping inputs via queryOptions() solved the issue. Treat this as an example finding, not a universal rule.

OpenCode-Specific Internals

Use references/opencode-skill-testing.md when debugging OpenCode skill loading or autoload testing internals.

Remember

1. Read source FIRST - before asking, before web searching
2. Exact version matters - opensrc has YOUR installed version
3. Follow the code path - trace from entry point to implementation
4. Check types - TypeScript types often reveal expected usage
5. Look at tests - library tests show correct usage patterns