Debug Specmatic Failures

Workflow

1. Capture the exact failure.

   • Before creating repros or comparing multiple specs, identify the exact specification path that Specmatic is using in the failing command. Sources may include the user's prompt, shell command, specmatic.yaml, wrapper code, CI logs, build output, git diff, or runtime logs.
   • Treat the identified spec path(s) as the investigation scope. Do not introduce sibling specs, version-numbered specs, generated variants, or inferred before/after files unless the user's command, git diff, config, code, or logs explicitly show Specmatic using them.
   • Preserve the command, Specmatic output, specmatic.yaml, relevant OpenAPI spec, externalized examples, filters, mode-specific inputs, and wrapper code.
   • Extract the version lines, especially Specmatic Enterprise v... and Specmatic Core v....
   • If version is not visible, inspect Docker image tags, Gradle/Maven dependencies, NuGet/JUnit wrapper configuration, or CI logs.

2. Identify the execution mode.

   • Command family: test, mock/stub, validate, backward compatibility, MCP, proxy, or another Specmatic command.
   • Enterprise: Docker image or binary reports Specmatic Enterprise v....
   • OSS/Core: project uses specmatic-core, specmatic-executable, junit5-support, or specmatic/specmatic without Enterprise.
   • Wrapper: .NET/JUnit/custom test framework invokes Specmatic; follow the wrapper to the actual CLI/image/version.