How no-mistakes Auto-Fix Distinguishes Safe Mechanical Fixes from Intent-Touching Changes

no-mistakes classifies every finding as either auto-fixable (safe mechanical changes) or intent-touching (potential behavior changes), using a three-layer system involving review guidance, step outcome flags, and configuration limits to prevent silent modifications to deliberate code intent.

The no-mistakes engine from the kunchenguid/no-mistakes repository automatically categorizes code issues before attempting repairs. Understanding how it distinguishes between safe mechanical fixes and intent-touching changes ensures that automated remediation never silently alters intended behavior.

The Three-Layer Classification System

The decision to auto-fix or defer to human review operates across three specific code locations.

Review Step Guidance Defines the Categories

According to the source code in internal/pipeline/steps/review.go at line 165, the review step guidance explicitly differentiates between two finding types. Safe mechanical fixes are defined as "non-functional, non user-visible issues (correctness, error handling, security, performance, mechanical code quality)" that can be corrected without discussing the author’s intent. Intent-touching findings are those that "challenge the author’s deliberate intent," such as removing features, changing product behavior, or refactoring that might alter semantics.

Step Outcome Flag Controls Execution

When a step finishes execution, it returns a StepOutcome struct containing an AutoFixable boolean field. This flag is set to true only for findings classified as safe mechanical fixes according to the review guidance. The executor checks this flag in internal/pipeline/executor.go (see lines 317-322) before launching any automatic fix agent.

Configuration Defaults Limit Automatic Repairs

By default, auto-fix is disabled to ensure safety. The autoFixDefaults function in internal/config/config.go (lines 871-872) returns a zero limit, requiring repositories to explicitly raise their auto-fix limit in configuration to enable automatic repairs for findings marked as auto-fixable.

The Pipeline Execution Flow

The distinction between safe mechanical fixes and intent-touching changes follows a strict four-phase pipeline:

1. Collect findings – Each step populates outcome.Findings with detected issues.
2. Classify – Step logic guided by review comments categorizes each finding with either an auto-fix or ask-user action.
3. Mark – The AutoFixable boolean is set to true for auto-fix actions and false for ask-user actions.
4. Execute – The executor evaluates AutoFixable && autoFixLimit > 0. When both conditions are true, findings serialize into autoFixableFindingsJSON and the agent generates fixes. When false, execution pauses for human review.

// internal/pipeline/executor.go (lines 317-322)
if outcome.AutoFixable && autoFixLimit > 0 {
    autoFixableFindingsJSON := serializeFindings(outcome.Findings)
    launchFixAgent(autoFixableFindingsJSON)
} else {
    pauseForHumanReview(outcome.Findings)
}

Safe mechanical fixes (nil-pointer guards, missing error checks, linter warnings) trigger AutoFixable = true, allowing automatic resolution. Intent-touching changes (feature removals, hard-coded design choices, behavioral refactors) result in AutoFixable = false, routing the finding to the user for deliberate review.

Summary

• Three-layer safety: Classification occurs through review guidance at line 165 of review.go, the AutoFixable flag in StepOutcome, and the autoFixDefaults configuration in config.go.
• Clear action types: Findings use either auto-fix (mechanical) or ask-user (intent-touching) actions to signal automation eligibility.
• Execution gate: The executor in executor.go only applies fixes when AutoFixable is true and the repository-specific autoFixLimit permits it.
• Default safety: Auto-fix starts disabled (zero limit), preventing unintended automatic modifications until explicitly configured.

Frequently Asked Questions

What constitutes a safe mechanical fix in no-mistakes?

Safe mechanical fixes are non-functional, non-user-visible issues including correctness bugs, error handling gaps, security vulnerabilities, performance problems, and mechanical code quality violations. These are defined in the review step guidance at internal/pipeline/steps/review.go line 165 and can be corrected without consulting the author’s original intent.

How does the executor know when to apply an auto-fix?

The executor checks the AutoFixable boolean field in the StepOutcome struct returned by each step. According to internal/pipeline/executor.go lines 317-322, it only launches the fix agent when outcome.AutoFixable is true and the configured autoFixLimit is greater than zero.

Can I enable auto-fix by default in my repository?

Yes, but it requires explicit configuration. The autoFixDefaults function in internal/config/config.go (lines 871-872) returns a zero limit by default, disabling auto-fix. You must raise this limit in your repository configuration to allow the executor to automatically apply fixes marked as auto-fixable.

What happens when a finding is classified as intent-touching?

Intent-touching findings are assigned the ask-user action and marked with AutoFixable = false. The executor will not automatically apply these changes; instead, it records the finding and pauses execution, requiring human review and explicit approval before any modification that could alter deliberate product behavior.

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