# How to Report Bugs in the no-mistakes Project: A Complete Guide

> Easily report bugs in the no-mistakes project by following our guide. Learn how to use the bug report template on GitHub Issues with all necessary details for a quick resolution.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-07-20

---

**Report bugs in the no-mistakes project by opening a GitHub Issue using the bug report template at [`/.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/kunchenguid/no-mistakes/blob/main//.github/ISSUE_TEMPLATE/bug_report.md), providing your environment details, steps to reproduce, and relevant logs from `$NM_HOME/logs/cli.log`.**

The *no-mistakes* repository is a Go CLI application that implements a pipeline-based code review system. To report bugs effectively, you need to understand the project's architecture—which splits runtime logic across `internal/cli`, `internal/daemon`, `internal/pipeline`, and `internal/agent` packages—and provide specific diagnostic information that helps maintainers trace issues to the correct subsystem.

## Where to Report Bugs

All bug reports for no-mistakes are tracked via **GitHub Issues** at `https://github.com/kunchenguid/no-mistakes/issues`.

The project uses structured templates to ensure consistency. When you click "New Issue," select the **"Bug report"** template rather than opening a blank issue. This template is stored at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/kunchenguid/no-mistakes/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) and prompts you for the specific details maintainers need to triage problems in the Go codebase.

## Essential Information to Include

A high-quality bug report should contain enough context to reproduce the issue locally. The maintainers need to know which internal package is affected—whether it's the daemon lifecycle in [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go) or the review pipeline in [`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go).

### Environment Specifications

Always include your runtime environment:

- **Operating system** (e.g., macOS 13.4, Ubuntu 22.04)
- **Go version** (run `go version`)
- **no-mistakes version** (run `no-mistakes version`)
- **Installation method** (built from source, downloaded binary, etc.)

### Log Output and Debugging

The CLI writes operational logs to `$NM_HOME/logs/cli.log`, as referenced in the daemon lock implementation in [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go). When reporting daemon-related bugs, include relevant log snippets from this location.

For additional diagnostic data, run the binary with the `--debug` flag. This enables verbose logging throughout the shell execution layer ([`internal/shellenv/shell_command.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/shellenv/shell_command.go)) and helps trace subprocess failures.

### Minimal Reproduction Steps

Provide exact command-line invocations that trigger the bug. If the issue occurs during pipeline execution, identify the specific step (e.g., [`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go)) and include:

1. The exact command you ran
2. Input data or repository state
3. Expected behavior versus actual behavior

### Test Case Contributions

The repository includes comprehensive unit tests under `internal/pipeline/steps/*_test.go`. If possible, submit a failing test case that reproduces your bug. This allows maintainers to verify fixes using the existing test framework.

## Review CONTRIBUTING.md First

Before submitting, read the **CONTRIBUTING.md** file at the repository root. This document explains:

- Development environment setup
- Code review workflow
- Commit message conventions
- Issue labeling expectations

Following these guidelines ensures your report receives prompt attention.

## Example Bug Report

Below is a well-structured bug report following the template:

```markdown
**Title**  
`no-mistakes daemon fails to acquire singleton lock on macOS`

**Steps to reproduce**  
1. Clone the repository and build the binary (`make build`).  
2. Run `./bin/no-mistakes daemon run --root /tmp/no-mistakes-test` in one terminal.  
3. In another terminal, run the same command again while the first daemon is still alive.

**Expected behaviour**  
The second daemon should exit with an error indicating that the lock is already held.

**Actual behaviour**  
Both daemons start, leading to a race condition and corrupted state.

**Environment**  
- OS: macOS 13.4  
- Go version: 1.22.2  
- no-mistakes version: v0.12.0 (built from main)

**Logs**  

```

2026-07-11T12:34:56Z [error] daemon lock acquisition failed: lock already held

```

**Additional context**  
The lock is implemented in `internal/daemon/lock.go`. The race appears only on macOS; Linux behaves as expected.

```

## Key Source Files to Reference

When describing bugs, reference these specific files to help maintainers locate the problem:

- **[`cmd/no-mistakes/main.go`](https://github.com/kunchenguid/no-mistakes/blob/main/cmd/no-mistakes/main.go)** — CLI entry point that parses commands and launches subsystems
- **[`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go)** — Singleton lock implementation preventing multiple daemon instances
- **[`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go)** — Core review step where many pipeline bugs surface
- **[`internal/shellenv/shell_command.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/shellenv/shell_command.go)** — Subprocess execution helper used throughout the daemon
- **`internal/pipeline/steps/*_test.go`** — Unit test suite for reproducing issues

## Summary

- **Use the GitHub Issue tracker** with the bug report template located at [`.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/kunchenguid/no-mistakes/blob/main/.github/ISSUE_TEMPLATE/bug_report.md)
- **Include environment details**: OS, Go version, and no-mistakes version output
- **Attach logs** from `$NM_HOME/logs/cli.log` and use `--debug` for verbose output
- **Reference specific files** like [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go) or [`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go) when describing the bug location
- **Read CONTRIBUTING.md** before submitting to understand project workflow
- **Provide minimal reproduction steps** or failing test cases when possible

## Frequently Asked Questions

### How do I find the no-mistakes version to include in my bug report?

Run the command `no-mistakes version` in your terminal. The binary outputs its build version and commit hash, which helps maintainers correlate your report with specific code states in the repository.

### Where does no-mistakes store its log files?

The application writes logs to `$NM_HOME/logs/cli.log`. This path is defined in the daemon initialization code in [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go). Check this location for error messages and stack traces when reporting daemon or CLI failures.

### What should I do if the bug only happens in the review pipeline?

If the issue occurs during code review processing, reference [`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go) in your report. Include the specific repository or file that triggers the failure, and if possible, create a failing test in [`internal/pipeline/steps/review_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review_test.go) that demonstrates the issue.

### Can I report security vulnerabilities through public GitHub Issues?

For security-sensitive bugs—such as those affecting the daemon's singleton lock mechanism in [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go) or command injection risks in [`internal/shellenv/shell_command.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/shellenv/shell_command.go)—check the repository's security policy first. Many projects prefer private disclosure for vulnerabilities that could compromise user systems.