# How to Report a Bug in Ruflo: A Complete Guide to GitHub Issues and Verification

> Learn to report Ruflo bugs effectively on GitHub. Use the rollback-incident template, run verify-appliance.sh, and attach debug logs for quick resolution.

- Repository: [rUv/ruflo](https://github.com/ruvnet/ruflo)
- Tags: how-to-guide
- Published: 2026-03-09

---

**To report a bug in Ruflo, open a GitHub Issue using the rollback-incident template, run the [`verify-appliance.sh`](https://github.com/ruvnet/ruflo/blob/main/verify-appliance.sh) script for diagnostics, and attach debug logs captured with the `--debug` flag.**

When you need to report a bug in Ruflo, the open-source AI orchestration framework for multi-agent swarms, following the project's structured GitHub Issues workflow ensures maintainers can reproduce and resolve issues efficiently. This guide walks through the exact steps to submit a high-quality bug report using the repository's built-in validation tools and issue templates stored in `ruvnet/ruflo`.

## Using the GitHub Issue Template

Every bug report starts with the **Bug** issue template located at [`.github/ISSUE_TEMPLATE/rollback-incident.md`](https://github.com/ruvnet/ruflo/blob/main/.github/ISSUE_TEMPLATE/rollback-incident.md). This template enforces a consistent format that captures all critical diagnostic information required by maintainers.

When you open a new issue, the template prompts you to provide:

- A concise title and clear description of the problem
- Step-by-step reproduction instructions
- Expected behavior versus actual behavior
- Environment details including Node version, OS, and Ruflo version
- Relevant logs, screenshots, or error traces

The template automatically applies the `bug` label to your issue. If the defect blocks production work, manually add the `high-priority` or `needs-triage` labels to expedite review.

## Running the Verification Script

Before submitting your report, execute the **[`scripts/verify-appliance.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/verify-appliance.sh)** script to validate your local environment and generate a baseline diagnostic report. According to the source code, this script performs sanity checks on CLI invocation, MCP server startup, and basic swarm task execution.

```bash
bash ./scripts/verify-appliance.sh

```

The script outputs a concise pass/fail report that you should paste directly into your GitHub issue. Running this verification helps distinguish between environmental configuration issues and actual code defects in the core engine.

## Capturing Debug Logs and Reproduction Cases

The most actionable bug reports include a **minimal reproducible test case** and comprehensive debug logs. To capture detailed output during a failure, use the `--debug` flag with the Ruflo CLI entry point at [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js).

```bash
npx ruflo@latest swarm start \
  --objective "Buggy task" \
  --strategy development \
  --debug > bug-report.log 2>&1

```

Ruflo writes detailed logs to `~/.ruflo/logs` or the `logs/` directory under the project root. If the bug involves swarm coordination failures or agent claim handling—common issues in [`v3/src/coordination/application/SwarmCoordinator.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/src/coordination/application/SwarmCoordinator.ts)—include excerpts from these logs. For MCP communication errors defined in [`v3/mcp/types.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/mcp/types.ts), include relevant RPC contract details in your report.

You can also reference the integration test suite in [`tests/rvf-integration.test.ts`](https://github.com/ruvnet/ruflo/blob/main/tests/rvf-integration.test.ts) to see if your issue matches existing Vitest scenarios or to structure your reproduction case using established test patterns.

## CI Pipeline and Issue Triage

Once submitted, maintainers triage your issue and attempt reproduction against the CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/ruvnet/ruflo/blob/main/.github/workflows/ci.yml). This workflow runs the full Vitest suite on every pull request, ensuring that verified bug fixes pass all integration tests before merging. The maintainers use the same CLI flags (`--debug`, `--wizard`) available in [`bin/cli.js`](https://github.com/ruvnet/ruflo/blob/main/bin/cli.js) to reproduce reported issues in a clean environment.

## Summary

- Open GitHub Issues using the template at [`.github/ISSUE_TEMPLATE/rollback-incident.md`](https://github.com/ruvnet/ruflo/blob/main/.github/ISSUE_TEMPLATE/rollback-incident.md) to ensure consistent formatting and automatic `bug` labeling.
- Run [`scripts/verify-appliance.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/verify-appliance.sh) to generate environment diagnostics before submitting your report.
- Capture debug logs using `npx ruflo@latest --debug` and check `~/.ruflo/logs` for detailed error traces.
- Include environment details (Node version, OS, Ruflo version) and minimal reproduction steps for the fastest resolution.
- Reference core source files like [`v3/src/coordination/application/SwarmCoordinator.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/src/coordination/application/SwarmCoordinator.ts) when reporting swarm coordination issues or [`v3/mcp/types.ts`](https://github.com/ruvnet/ruflo/blob/main/v3/mcp/types.ts) for MCP-related bugs.

## Frequently Asked Questions

### Where does Ruflo store debug logs?

Ruflo writes debug logs to `~/.ruflo/logs` by default, or to the `logs/` folder under the project root when running from a local clone. You can also redirect debug output to a file using the `--debug` flag with the CLI: `npx ruflo@latest --debug > bug-report.log 2>&1`.

### What does the verify-appliance.sh script check?

The script at [`scripts/verify-appliance.sh`](https://github.com/ruvnet/ruflo/blob/main/scripts/verify-appliance.sh) validates CLI invocation, MCP server startup, and basic swarm execution to ensure your local environment is functional. It prints a concise pass/fail report that helps distinguish between configuration errors and actual code defects in the core orchestration logic.

### How should I label urgent bugs?

While the issue template automatically applies the `bug` label, you should manually add `high-priority` if the defect blocks production work or `needs-triage` if you are uncertain about the severity. These labels alert maintainers to time-sensitive issues that require immediate attention.

### How do maintainers confirm that a bug is fixed?

The maintainers reproduce reported issues against the CI pipeline defined in [`.github/workflows/ci.yml`](https://github.com/ruvnet/ruflo/blob/main/.github/workflows/ci.yml), which runs the full Vitest test suite on every pull request. Once a fix is submitted, the integration tests in [`tests/rvf-integration.test.ts`](https://github.com/ruvnet/ruflo/blob/main/tests/rvf-integration.test.ts) must pass before the fix is merged, ensuring the bug is resolved.