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

Report bugs in the no-mistakes project by opening a GitHub Issue using the bug report template at /.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 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 or the review pipeline in 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. 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) 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) 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:

**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 — CLI entry point that parses commands and launches subsystems
• internal/daemon/lock.go — Singleton lock implementation preventing multiple daemon instances
• internal/pipeline/steps/review.go — Core review step where many pipeline bugs surface
• 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
• 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 or 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. 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 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 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 or command injection risks in internal/shellenv/shell_command.go—check the repository's security policy first. Many projects prefer private disclosure for vulnerabilities that could compromise user systems.

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