OpenParable
Skip to content
← Back to skills

Bug Investigation

Testing & Quality

Bug Investigation is an Agent Skill for testing & quality published in the vinilana/dotcontext repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Systematic bug investigation and root cause analysis

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/vinilana/dotcontext/blob/HEAD/.context/skills/bug-investigation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/bug-investigation, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Bug Investigation

Systematic approach to investigating and fixing bugs in the @dotcontext/cli CLI tool.

When to Use

  • A CLI command (workflow, sync, mcp, etc.) produces incorrect output or crashes
  • An MCP tool returns an error or unexpected response
  • Semantic analysis (tree-sitter / LSP) fails on certain codebases
  • Scaffold generation produces malformed frontmatter or missing content
  • Workflow phase transitions behave incorrectly
  • Tests fail unexpectedly after changes

Project-Specific Investigation Surfaces

AreaKey FilesCommon Issues
CLI commandssrc/index.ts, src/services/*/index.tsCommander option parsing, missing args
MCP serversrc/services/mcp/mcpServer.ts, src/services/mcp/gateway/*.tsrepoPath resolution, Zod validation failures
Scaffold generationsrc/generators/*/, src/types/scaffoldFrontmatter.tsFrontmatter parsing, file path resolution
Scaffold fill via MCPsrc/services/ai/tools/fillScaffoldingTool.ts, src/services/mcp/gateway/context.tsMissing files, stale context, oversized responses
Semantic analysissrc/services/semantic/codebaseAnalyzer.ts, src/services/semantic/treeSitter/tree-sitter optional dep missing, parse failures
Workflowsrc/workflow/, src/services/workflow/workflowService.tsPhase transition logic, gate checking
i18nsrc/utils/i18n.tsMissing translation keys, locale detection
Frontmattersrc/utils/frontMatter.tsv1 vs v2 format confusion, status detection

Instructions

1. Reproduce the Bug

Run the CLI in dev mode to reproduce:

# Direct execution via tsx
npx tsx src/index.ts workflow --help

# For MCP-related bugs, capture stderr output
npx tsx src/index.ts mcp --verbose 2>mcp-debug.log

For MCP tool bugs, test the gateway handler directly in a script or test file rather than through the full MCP transport.

2. Identify the Service Layer

Trace the call path from the CLI command or MCP tool to the responsible service:

CLI command (src/index.ts)
  -> Service (src/services/<domain>/)
    -> Generator (src/generators/) or Util (src/utils/)

For MCP:

MCP tool (mcpServer.ts registerGatewayTools)
  -> Gateway handler (src/services/mcp/gateway/<tool>.ts)
    -> Service (src/services/<domain>/)

3. Check Known Fragile Points

  • Optional dependencies: tree-sitter and tree-sitter-typescript are in optionalDependencies. Code must handle their absence gracefully. Check src/services/semantic/treeSitter/treeSitterLayer.ts.
  • repoPath resolution: The MCP server has a 4-level priority: explicit param > cached path > initial path > process.cwd(). Bugs often arise from incorrect path resolution. See getRepoPath() in mcpServer.ts.
  • Frontmatter parsing: Two formats exist (v1 simple, v2 scaffold). Check src/utils/frontMatter.ts and isScaffoldFrontmatter().
  • Provider/default detection: Local model defaults are derived from src/services/ai/providerFactory.ts and src/utils/prompts/smartDefaults.ts. MCP-hosted generation usually relies on the connected tool's model.
  • File path handling: Always use path.resolve() or path.join(). Watch for relative vs. absolute path confusion, especially in contextBuilder.ts.

4. Use Existing Tests as Reference

Run the relevant test suite to see what is expected:

# Run all tests
npm test

# Run specific test file
npx jest src/services/mcp/mcpServer.test.ts

# Run tests matching a pattern
npx jest --testPathPattern="mcp"

Key test files:

  • src/services/mcp/mcpServer.test.ts -- MCP server instantiation
  • src/services/mcp/mcpServer.test.ts -- MCP tool registration and dispatch
  • src/services/semantic/codebaseAnalyzer.test.ts -- Semantic analysis
  • src/utils/frontMatter.test.ts -- Frontmatter parsing
  • src/utils/contentSanitizer.test.ts -- Content sanitization
  • src/workflow/gates/gateChecker.test.ts -- Workflow gate logic

5. Isolate with Logging

The project uses ora for spinners and chalk for colored output. For debugging:

  • CLI: Pass --verbose flag to enable detailed logging
  • MCP: The log() method writes to process.stderr when verbose: true
  • Services: Add temporary console.error() calls (never console.log() in MCP mode)

6. Fix and Verify

After identifying root cause:

  1. Write a failing test that demonstrates the bug
  2. Apply the fix in the appropriate service/util
  3. Run the full test suite: npm test
  4. Run the CLI manually to verify end-to-end: npx tsx src/index.ts <command>
  5. Check TypeScript compilation: npm run build

Common Bug Patterns

"Cannot find module" at Runtime

  • Check if the import uses the @generators/agents/* path alias (defined in tsconfig.json)
  • Ensure the file is not excluded from compilation by tsconfig.json

MCP Tool Returns Unexpected Error

  • Check Zod schema validation in mcpServer.ts -- params may not match the schema
  • Check the gateway handler's switch statement for unhandled actions
  • Verify repoPath resolves to a directory with .context/ scaffolding

Frontmatter Status Not Detected

  • v2 scaffold files use scaffoldVersion: "2.0.0" and status: unfilled|filled
  • Ensure isScaffoldFrontmatter() check happens before v1 fallback
  • Check for BOM or encoding issues in the file header

Workflow Phase Transition Fails

  • Check gate configuration in src/workflow/gates/
  • Verify scale-dependent phase skipping (QUICK skips P and R)
  • Check src/workflow/prevcConfig.ts for scale definitions

MCP Scaffold Fill Produces Empty or Placeholder Guidance

  • Verify fillSingleFileTool can read the scaffold and build semantic context
  • Check scaffold structure registration via getScaffoldStructure()
  • Confirm SemanticContextBuilder is returning project-specific content
  • Check response size and cached-context invalidation behavior