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

> Report a bug in the no-mistakes project by opening a GitHub Issue. Follow our guide to provide environment details, steps to reproduce, and logs for a quick resolution.

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

---

**File a bug report by opening a GitHub Issue using the bug_report.md template, providing your environment details, steps to reproduce, and logs from $NM_HOME/logs/cli.log.**

The no-mistakes project is a Go-based CLI application that automates code review pipelines through a daemon-driven architecture. Located at `kunchenguid/no-mistakes`, the codebase organizes its runtime logic across internal packages such as `internal/cli`, `internal/daemon`, and `internal/pipeline`. When you need to report a bug in the no-mistakes project, submitting a structured issue helps maintainers locate problems quickly within the daemon lifecycle or pipeline execution.

## Prerequisites: Read the Contribution Guidelines

Before filing, review [`CONTRIBUTING.md`](https://github.com/kunchenguid/no-mistakes/blob/main/CONTRIBUTING.md) in the repository root. This document outlines the development workflow, coding standards, and expectations for issue quality according to the no-mistakes source code.

## Step-by-Step Bug Reporting Process

### 1. Open a GitHub Issue

Navigate to [https://github.com/kunchenguid/no-mistakes/issues](https://github.com/kunchenguid/no-mistakes/issues) and click **New issue**.

### 2. Select the Bug Report Template

Choose 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). This template enforces a consistent structure that covers environment, reproduction steps, and expected versus actual behavior.

### 3. Document Your Environment

Include:

- **Operating system** and version
- **Go version** (e.g., 1.22.2)
- **no-mistakes version** (run `no-mistakes version`)
- **Installation method** (built from source, binary release, etc.)

### 4. Collect Logs and Debug Information

The CLI writes runtime logs to `$NM_HOME/logs/cli.log`, as implemented in [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go). If the issue involves daemon startup or lock acquisition failures, check this log file. Run the binary with the `--debug` flag to enable verbose logging in `internal/shellenv`, which captures subprocess execution details via [`internal/shellenv/shell_command.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/shellenv/shell_command.go).

### 5. Provide a Minimal Reproducible Example

If the bug manifests in a specific pipeline step, reference the relevant source file (e.g., [`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go)). When possible, add a failing test case to the existing suite in `internal/pipeline/steps/*_test.go` to demonstrate the defect and accelerate the fix.

## Anatomy of a High-Quality Bug Report

Here is a complete example that follows 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 for Debugging Context

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

- **[`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)** – Implements the singleton lock mechanism; relevant for daemon startup issues
- **[`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go)** – Core review step where many pipeline errors 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

## Summary

- **Use the template**: Always select 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) to ensure consistent formatting.
- **Include logs**: Attach output from `$NM_HOME/logs/cli.log` and use `--debug` for verbose tracing.
- **Specify versions**: Report your Go version, OS, and the output of `no-mistakes version`.
- **Reference code**: Point to 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 relevant.
- **Provide tests**: Add a failing test in `internal/pipeline/steps/*_test.go` to accelerate the fix verification.

## Frequently Asked Questions

### Where do I find the log files for no-mistakes?

The CLI writes runtime logs to `$NM_HOME/logs/cli.log`. This path is defined in the daemon initialization code within [`internal/daemon/lock.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/lock.go). If you encounter daemon startup failures or race conditions, check this file for lock acquisition errors or process state conflicts.

### What information is required in the bug report template?

The template at [`/.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/kunchenguid/no-mistakes/blob/main//.github/ISSUE_TEMPLATE/bug_report.md) requires a clear title, step-by-step reproduction instructions, expected versus actual behavior, environment details (OS, Go version, no-mistakes version), relevant log output, and any additional context such as specific source files affected.

### How can I run no-mistakes with extra debugging enabled?

Pass the `--debug` flag when executing commands. This enables verbose logging in `internal/shellenv`, which captures detailed information about subprocess execution and environment setup. This is particularly useful when debugging pipeline step failures or shell command issues.

### Should I write a test case for the bug I found?

Yes, if possible. The repository includes a comprehensive test suite in `internal/pipeline/steps/*_test.go`. Creating a minimal reproduction as a failing test helps maintainers verify the issue quickly and ensures the fix is properly validated against regression.