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

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 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 and click New issue.

2. Select the Bug Report Template

Choose the Bug report template located at /.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. 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.

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). 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:

**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 – CLI entry point that parses commands and launches subsystems
• internal/daemon/lock.go – Implements the singleton lock mechanism; relevant for daemon startup issues
• internal/pipeline/steps/review.go – Core review step where many pipeline errors surface
• 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 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 or 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}