openspec-debug

Investigate bugs in OpenSpec changes and produce root-cause analysis with fix tasks.

Updated Jun 26, 2026
One-click install
npx skills add https://github.com/pavelvdo/universal-xml-exchange2 --skill openspec-debug-pavelvdo
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: openspec-debug
Source: https://github.com/pavelvdo/universal-xml-exchange2/tree/main/.cursor/skills/openspec-debug
Command: npx skills add https://github.com/pavelvdo/universal-xml-exchange2 --skill openspec-debug-pavelvdo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a bug is found during testing of an OpenSpec change (a 1C development task), you need a structured way to turn traces, remarks, and screenshots into a verified root-cause analysis and concrete fix tasks captured inside the same change artifacts, instead of ad-hoc debugging in chat. ## Core Features & Use Cases - Structured RCA: Separates verified facts (with trace line and file references) from hypotheses, each hypothesis carrying a verification plan. - Subagent orchestration: Delegates trace parsing to onec-trace-analyst, code exploration to onec-code-explorer, and architectural review to onec-code-architect, saving their reports under the change's reports directory. - Artifact capture: Writes fix tasks into tasks.md with slice-aware placement rules and updates design.md when the bug reveals a design gap, then hands off to /opsx:apply for implementation. - Use Case: A tester reports that a document posting routine excludes the wrong participants and provides a trace file; the skill loads the change context, analyzes the trace, verifies hypotheses against the source XML and BSL code, and records fix tasks in the change. ## Quick Start Run /opsx:debug with a trace file path or a description of the expected versus actual behavior to start a root-cause investigation for the current OpenSpec change.

Frequently Asked Questions about openspec-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a bug inside an OpenSpec change?

Run /opsx:debug with a trace file path, a textual remark, or screenshots. The skill loads the change context, shows a brief for confirmation, then delegates trace and code analysis to subagents and records fix tasks in tasks.md.

What inputs does the debug workflow accept?

It accepts a trace file path, textual expected-versus-actual remarks, attached screenshots, an optional OpenSpec change id, and an optional task number. Any combination of these inputs can be provided in free form.

Does openspec-debug modify code directly?

No. It produces the RCA and captures fix tasks in tasks.md and design.md, then hands off implementation to /opsx:apply. Code changes are only made in the apply workflow, unless the user explicitly requests plan only.

How are hypotheses handled before a fix is applied?

The RCA splits findings into Verified facts with concrete references and Hypotheses with verification plans. If the root cause is a hypothesis, the first plan task is verification, or the fix is marked hypothesis-based with a follow-up verification task.

What happens when the bug reveals a design gap?

The skill adds a note to design.md and may propose routing through /opsx:extend with the debug report, so the change specification is corrected before implementation continues via /opsx:verify and /opsx:apply.