What Does "Clean PRs by Default" Mean in no-mistakes? A Complete Guide

In the no-mistakes workflow, "clean PRs by default" means that pull requests are automatically created only after a full validation pipeline succeeds, containing exactly the commits you authored without any extra tooling-generated intermediate commits or merge artifacts.

The kunchenguid/no-mistakes repository implements a Git gate that intercepts your pushes before they reach the remote. According to the source code in README.md (lines 33-41), when you push to no-mistakes instead of origin, the tool validates your changes in an isolated environment and opens a PR automatically—but only if the pipeline passes, ensuring every PR is "clean" by default.

How the Gate Creates Clean PRs

The clean PR guarantee relies on a disposable work-tree architecture that separates validation from your working branch.

Disposable Work-Tree Isolation

When you run git push no-mistakes <branch>, the tool immediately creates a disposable work-tree so your original branch stays untouched. As illustrated in the README diagram (lines 44-57), this isolates the validation process from your local development state, ensuring that no matter what fixes or checks run, your original commit history remains intact until the gate approves forwarding.

The Validation Pipeline

Inside the disposable work-tree, no-mistakes executes a fully automated pipeline that runs through review, test, documentation, and lint steps. The gate applies auto-fixes automatically for harmless issues, but stops on any finding that needs human judgement—presenting these for your approval before continuing. Only after every step returns green does the gate forward the branch to the real remote.

The Clean PR Output

The resulting PR contains the exact set of commits you originally pushed—no extra "gate" commits, no "merge-commit" fluff. This gives you a tidy, linear history on the contribution side while still benefiting from the safety net of automated validation.

Working with Clean PRs in Practice

Command Line Push

Initialize the gate once per repository, then push through it instead of origin:

# Initialise the gate (once per repo)

no-mistakes init

# Work on a feature branch as usual

git checkout -b feature-awesome

# …make changes, commit them

git commit -am "Add awesome feature"

# Push through the gate

git push no-mistakes feature-awesome

# → pipeline starts, auto-fixes harmless issues,

#   and when all checks are green the gate:

#   * pushes the branch to the configured remote

#   * opens a PR on that remote containing only your commit(s)

Interactive TUI Workflow

For a guided experience, use the TUI which walks you through the disposable work-tree creation and validation:

# After you have committed locally

no-mistakes          # launches the TUI

# The wizard walks you through:

#   – creating a work-tree,

#   – running the pipeline,

#   – reviewing any findings,

#   – finally forwarding the branch and opening the PR.

Agent-Driven Execution

The clean PR pipeline integrates with coding agents via the /no-mistakes skill:

# Example with Claude as the coding agent

claude "implement foo()" /no-mistakes

# The skill runs the same pipeline, auto-fixes, and ends with a clean PR.

Implementation Details

The clean PR behavior is implemented across several key files in the repository:

• README.md (lines 33-41): Documents the high-level guarantee that pushing to no-mistakes "opens a clean PR automatically."
• internal/pipeline/steps/push.go: Implements the final push-and-PR step, ensuring only green commits are forwarded and creating the PR via gh pr create.
• internal/cli/axi_render.go: Renders the final "clean PR, opened for you" status in the TUI.
• internal/agent/: Contains the agent-native entry points (/no-mistakes skill) that drive the same pipeline headlessly.

These components work together to ensure every PR produced by the tool is clean: it contains only the developer’s intended commits, and it appears only after the full automated validation pipeline has succeeded.

Summary

• Clean PRs contain only your original commits with no tooling artifacts or intermediate fix commits.
• Validation happens first in a disposable work-tree, leaving your original branch untouched until the pipeline is green.
• Automatic creation occurs via gh pr create only after all checks pass, ensuring the PR is ready for review immediately.
• Multiple interfaces support the same guarantee: direct Git push, interactive TUI, and agent-driven workflows.
• Linear history is preserved by avoiding merge commits and extra gate-generated commits.

Frequently Asked Questions

Does no-mistakes modify my original commits during the clean PR process?

No. The tool creates a disposable work-tree to run the pipeline, leaving your original branch untouched. Any auto-fixes are applied in the isolated environment, but the commits that land in the PR are exactly the ones you authored, as implemented in internal/pipeline/steps/push.go.

What happens if the validation pipeline finds issues that need human judgement?

The gate stops and presents findings that require your approval. It does not forward the branch to the remote or create a PR until every step is green. You review the issues in the TUI or command line, approve or fix them, and the process resumes from where it left off.

Can I use no-mistakes with my existing GitHub workflow?

Yes. You initialize the gate once per repository with no-mistakes init, then use git push no-mistakes <branch> instead of pushing to origin. According to the source code in README.md, the tool handles opening the PR automatically via gh pr create once validation passes, integrating seamlessly with standard GitHub pull request workflows.

Are the PRs opened as drafts or ready for review?

The PRs are opened automatically after the pipeline succeeds, with the final status rendered in internal/cli/axi_render.go. The analysis indicates these are standard PRs containing your clean commit history, ready for review immediately upon creation.

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