mcpField
D
debugging-with-opensrc

debugging-with-opensrc

github.com/blogic-czDevelopment389 installsUpdated 3d ago
Repository

About debugging-with-opensrc

A debugging skill for developers investigating third-party library behavior. It prioritizes reading OpenSrc mirrors of installed dependency source and tracing code paths before applying and validating an application-level fix.

Key features

  1. 01Inspect installed dependency source
  2. 02Trace calls from API to internals
  3. 03Check signatures, defaults, and errors
  4. 04Use types and tests as evidence
  5. 05Validate targeted fixes

Use cases

  1. 01Investigate a library integration failure
  2. 02Resolve docs and runtime mismatches
  3. 03Confirm dependency behavior in edge cases

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/blogic-cz/blogic-marketplace --skill debugging-with-opensrc

After installing, type/debugging-with-opensrcin Claude Code to confirm it loaded.

Bundled filesreferences/opencode-skill-testing.md

Details

From the project README

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 configured repos when the OpenSrc config exists
test ! -f opensrc/sources.json || \
bun run scripts/opensrc-sync.ts

# Fetch a package or GitHub repo
bunx opensrc --modify false <package-or-owner/repo>

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

LibraryPathWhat to look for
EffectEffect-TS/effect/packages/effect/src/Schema, Effect.gen, Layer, Context
TanStack RouterTanStack/router/packages/react-router/src/createFileRoute, loader, useParams
TanStack QueryTanStack/query/packages/react-query/src/useSuspenseQuery, queryOptions
TanStack FormTanStack/form/packages/react-form/src/useForm, validation
TanStack StartTanStack/router/packages/start/src/SSR, server functions
TRPCtrpc/trpc/packages/server/src/procedures, middleware, routers
Drizzle ORMdrizzle-team/drizzle-orm/drizzle-orm/src/pgTable, relations, queries
Better Authbetter-auth/better-auth/packages/better-auth/src/auth config, plugins, sessions
OpenCodesst/opencode/packages/opencode/src/skills, commands, plugins
Pinopinojs/pino/lib/logger, transports
Sentrygetsentry/sentry-javascript/packages/SDK, integrations, tracing

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

Comments

Markdown supported