# How to Report a Bug or Issue in OpenSpec: 3 Methods Explained > Discover three simple methods to report a bug or issue in OpenSpec. Learn to use GitHub Issues, Discord, and the openspec feedback CLI for efficient bug reporting with Fission-AI/OpenSpec. - Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec) - Tags: how-to-guide - Published: 2026-06-28 --- **OpenSpec provides three ways to report bugs: GitHub Issues, Discord, and the `openspec feedback` CLI command that auto-populates issue templates with the `feedback` label.** The Fission-AI/OpenSpec repository offers multiple channels to surface problems, ranging from automated CLI workflows to manual issue creation. Whether you encounter a CLI crash, a documentation typo, or unexpected behavior in the `/opsx` commands, you can choose the method that best fits your workflow. All routes ultimately funnel into the same GitHub issue tracker, ensuring your report reaches the maintainers. ## Using the OpenSpec Feedback Command (CLI) The `openspec feedback` command provides the fastest path to report a bug or issue in OpenSpec. Implemented in [`src/commands/feedback.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/feedback.ts), this utility attempts to create a GitHub issue automatically using the `gh` CLI, and falls back to a manual copy-paste workflow when the tool is unavailable. ### How the Feedback Command Works When you run `openspec feedback`, the code in [`src/commands/feedback.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/feedback.ts) (lines 122-140) first checks for the presence of the GitHub CLI. If authenticated, it creates an issue with the **feedback** label pre-applied. If `gh` is missing or not authenticated, the command prints a formatted issue template and prompts you to copy-paste it manually into the repository. The command is registered in [`src/cli/index.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/cli/index.ts) at lines 409-415, making it available as a top-level subcommand. ### Simple Title-Only Reports For quick reports where a title suffices, pass a single string argument: ```bash openspec feedback "Broken /opsx:apply on Nix projects" ``` This creates an issue with the title provided and auto-assigns the `feedback` label. ### Detailed Reports with Body For complex bugs, include a detailed description using the `--body` flag: ```bash openspec feedback "Bug: /opsx:propose hangs" \ --body "Running /opsx:propose on a fresh repo never returns. Steps to reproduce:\n1. \`openspec init\`\n2. In the AI chat type \`/opsx:propose add-feature\`\n3. The command stalls after 'Generating proposal'.\n\nEnvironment: macOS 14, Node 20.19, OpenSpec v1.5.0.\n\nExpected: command should return a proposal markdown file.\nActual: no output, process stays alive." ``` Use newline characters (`\n`) to format the body text with proper line breaks. ### Fallback When GitHub CLI Is Unavailable If the `gh` CLI is not installed or authenticated, the feedback command outputs a formatted template for manual submission: ```bash # When gh CLI is missing openspec feedback "Missing gh CLI fallback test" # Output: # ---------------------------------------------------- # Labels: feedback # Title: Missing gh CLI fallback test # Body: # # ---------------------------------------------------- # Please copy-paste the above into a new GitHub issue. ``` Copy this block and paste it into a new issue at the repository URL. ## Opening Issues Directly on GitHub You can manually report a bug or issue in OpenSpec by visiting the issue tracker directly at `https://github.com/Fission-AI/OpenSpec/issues`. When creating an issue manually: 1. Click **New Issue** 2. Fill in the title and description 3. Add the **feedback** label (or any appropriate category label) This method is documented in [`docs/faq.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/faq.md) under the section "Where do I ask questions or report bugs?" and reinforced in [`docs/README.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/README.md), which notes: "Found something wrong? Open an issue or PR." ## Using Discord for Quick Discussion For informal questions, rapid clarification, or "I just saw a typo" moments, the OpenSpec community Discord offers a lightweight alternative. The Discord link is documented in [`docs/faq.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/faq.md) alongside the GitHub Issues guidance. While Discord threads are not tracked as formally as GitHub issues, maintainers monitor the channel and will create corresponding tracker issues for verified bugs. This is ideal when you need immediate feedback before writing a formal report. ## Summary - **`openspec feedback`** – The fastest method; auto-creates GitHub issues with the `feedback` label via [`src/commands/feedback.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/feedback.ts), with graceful fallback to manual copy-paste. - **GitHub Issues** – The canonical tracker at `Fission-AI/OpenSpec/issues`; use for detailed bug reports and feature requests. - **Discord** – Best for informal discussion and quick questions; documented in [`docs/faq.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/faq.md). ## Frequently Asked Questions ### What is the fastest way to report a bug in OpenSpec? The `openspec feedback` CLI command is the fastest method. It automatically populates the issue title and body, applies the `feedback` label, and creates the issue via the GitHub CLI if available. This eliminates the need to navigate to the browser and manually format your report. ### Does the openspec feedback command require GitHub CLI authentication? Yes, for automatic issue creation. The command logic in [`src/commands/feedback.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/feedback.ts) attempts to invoke the `gh` CLI (lines 122-140). If `gh` is not installed or not authenticated, the command falls back to printing a formatted issue template that you can manually copy and paste into the GitHub web interface. ### Where can I find the official bug reporting guidelines? Official channels are documented in [`docs/faq.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/faq.md) under the section "Where do I ask questions or report bugs?" and in [`docs/README.md`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/README.md). These files outline the three supported methods: GitHub Issues, Discord, and the `openspec feedback` command. Additionally, the feedback workflow template is defined in [`src/core/templates/workflows/feedback.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/src/core/templates/workflows/feedback.ts). ### What information should I include in an OpenSpec bug report? Include your environment details (OS, Node.js version, OpenSpec version), steps to reproduce, expected behavior, and actual behavior. When using the CLI command, utilize the `--body` flag to provide structured formatting with newlines. Detailed context helps maintainers triage issues faster in the GitHub tracker.