How no-mistakes Handles ask-user Findings: The Human Approval Process Explained

When a pipeline step detects a finding with action: "ask-user", it sets NeedsApproval: true in the StepOutcome struct, causing the pipeline to pause and await explicit human intervention via the axi respond CLI command before resuming execution.

The no-mistakes repository implements a gate-based pipeline system where automated steps can encounter situations requiring human judgment. When the ask-user approval process is triggered, the system surfaces specific findings to the operator and blocks further execution until receiving an explicit decision. This ensures that sensitive changes—such as those affecting product behavior or intentional code design—receive proper scrutiny before the pipeline continues.

Step Outcome Detection and the NeedsApproval Flag

Each pipeline step in no-mistakes returns a structured result defined in internal/pipeline/pipeline.go. The StepOutcome struct contains a boolean field NeedsApproval that signals when human intervention is required.

According to the source code at lines 36-42, the StepOutcome struct captures the step's execution state:

type StepOutcome struct {
    NeedsApproval bool
    AutoFixable   bool
    Findings      string
    FixSummary    string
    // ... other fields
}

When NeedsApproval is set to true, the pipeline engine interprets this as a hard gate. The execution halts immediately, and the CLI displays a gate message containing the specific findings that require attention. This mechanism ensures that no step proceeding the gate can execute until the user explicitly resolves the blocking findings.

Detecting ask-user Findings in Pipeline Steps

The detection logic resides within individual step implementations. For example, in the review step (internal/pipeline/steps/review.go), after the agent returns structured findings, the code invokes a helper function to scan for blocking items.

The constant ActionAskUser is defined in internal/types/findings.go at lines 9-14:

const (
    ActionAskUser = "ask-user"
    ActionAutoFix = "auto-fix"
    // ...
)

When processing findings, the review step calls hasBlockingFindings() to check whether any Finding.Action equals ActionAskUser. If true, the step sets NeedsApproval: true in the returned outcome (see lines 201-207 of review.go):

needsApproval := hasBlockingFindings(findings.Items)
findingsJSON, _ := json.Marshal(findings)

return &pipeline.StepOutcome{
    NeedsApproval: needsApproval,
    AutoFixable:   len(findings.Items) > 0,
    Findings:      string(findingsJSON),
    FixSummary:    fixSummary,
}, nil

The helper function implements a simple iteration pattern to identify ask-user findings:

func needsApproval(findings []types.Finding) bool {
    for _, f := range findings {
        if f.Action == types.ActionAskUser {
            return true
        }
    }
    return false
}

The CLI Gate and User Response Flow

When the pipeline encounters NeedsApproval == true, it emits a structured gate message to the terminal. This output includes the step name, the list of findings with their severity and actions, and available help commands.

A typical gate output looks like this:

gate: review
findings[2]{id,severity,file,description,action}:
  r1,medium,cmd/main.go,Refactor this loop for clarity,auto-fix
  r2,high,cmd/main.go,New --force flag bypasses the confirm prompt,ask-user
help[2]:
  no-mistakes axi respond --action fix --findings r1
  no-mistakes axi respond --action approve

As documented in internal/skill/skill.go (lines 31-55), the user must invoke no-mistakes axi respond with one of the following actions:

• --action approve — Accepts the step as-is and allows the pipeline to continue. This is only valid when no ask-user findings remain unapproved.
• --action fix --findings <ids> — Instructs the pipeline to automatically fix the listed findings. This action only works for findings marked auto-fix, not ask-user.
• --action skip — Skips the current step entirely and proceeds to the next phase of the pipeline.

After receiving the response, the pipeline updates the run state and either resumes execution, retries the step, or aborts depending on the chosen action.

Automatic Approval with the --yes Flag

For automated environments or trusted workflows, no-mistakes supports automatic consent mode. When the user supplies the --yes flag on the initial axi run command or the axi respond command, the pipeline treats all actionable findings—including those marked ask-user—as pre-approved.

This bypasses the interactive gate and automatically applies fixes without pausing:

no-mistakes axi run --intent "refactor authentication logic" --yes

In this mode, the NeedsApproval flag is effectively ignored, allowing the pipeline to complete without human intervention. This is useful for CI/CD environments where the operator has already reviewed the potential changes offline.

Summary

• StepOutcome struct in internal/pipeline/pipeline.go uses the NeedsApproval boolean to signal when a pipeline step requires human intervention.
• ActionAskUser constant defined in internal/types/findings.go identifies findings that cannot be auto-resolved without operator consent.
• Detection logic in steps like review.go scans findings using helpers like hasBlockingFindings() to determine if any item requires approval.
• CLI gates display structured output showing ask-user findings and valid axi respond commands for resolution.
• --yes flag enables automatic approval mode, treating ask-user findings as pre-approved for unattended pipeline execution.

Frequently Asked Questions

What triggers the ask-user approval process in no-mistakes?

The process triggers when any pipeline step returns a finding where the Action field equals "ask-user". This constant is defined in internal/types/findings.go, and steps like the review agent check for it using the hasBlockingFindings() helper. When detected, the step sets NeedsApproval: true in the StepOutcome, causing the pipeline to pause and display a gate.

How do I approve ask-user findings from the command line?

You must use the no-mistakes axi respond command with the --action approve flag. For example: no-mistakes axi respond --action approve. This tells the pipeline to accept the current step's findings and continue execution. Note that you cannot use --action fix on ask-user findings; that flag only works for auto-fixable items.

Can I skip the human approval process for automated runs?

Yes. Supply the --yes flag when running no-mistakes axi run or no-mistakes axi respond. This enables automatic consent mode, where the pipeline treats all ask-user findings as pre-approved and applies fixes without pausing for human input. This is designed for CI/CD environments or trusted automation workflows.

Where is the ask-user action constant defined in the codebase?

The ActionAskUser constant is defined in internal/types/findings.go at lines 9-14, where it is set to the string value "ask-user". This constant is referenced throughout the codebase, particularly in step implementations like internal/pipeline/steps/review.go when determining if a step requires human approval.

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