Preface¶

A common scene when writing code with AI: the Agent finishes a version, runs the tests, and a few cases fail; you ask it to fix them, and more fail again; after a few rounds, the conversation hasn’t ended yet, the context is already very long, and you’re exhausted. Most of the time the reason for the failure is not complicated—assertion mismatches, type errors, lint violations—but what really takes time is the cycle of “fix → run → check output → fix again”.

grinding-until-pass is a reusable Agent Skill that formalizes this cycle: specify a command whose exit code determines success or failure, and let the Agent run the loop autonomously locally until the tests pass, the build succeeds, or linting passes cleanly, instead of stopping after each change and waiting for you to prompt for the next round.

What It Is¶

grinding-until-pass (also referred to as Grind Until Pass in documentation) comes from the open source collection awesome-cursor-skills maintained by Spencer Pauly, located at resources/grinding-until-pass/. Its core is a standard SKILL.md file. It does not replace testing frameworks or invent new CI tools, but rather constrains how the Agent works: under a clear success condition (command exit code 0), it continuously executes “fix → run → check → repeat” until the goal is achieved or a safe upper limit is reached.

This type of Skill follows the universal SKILL.md format and can be installed and used in tools that support Agent Skills such as Cursor, Codex CLI, Claude Code, etc.; the directory names may vary across tools, but the file structure is consistent.

Core Workflow and Constraints¶

The official SKILL.md breaks the workflow into four straightforward steps:

Define the target command: Use the exit code of which command to judge “success”. For example, use npm test or npx vitest run for tests, npm run build for builds, npm run lint for linting, npx tsc --noEmit for type checking; you can also chain commands, for example:

npm run lint && npx tsc --noEmit && npm test && npm run build

Run the command: Execute it and retain the full output.
Analyze and make minimal fixes on failure: Read the errors, locate the root cause (assertion failures, type errors, lint issues, import problems, etc.), make only minimal changes, avoid refactoring on the side, then return to step 2.
Stop and report on success: Explain what was fixed, how many iterations were completed, and a summary of the changes.

There are also several hard rules for the loop, which are what differentiate it from just “letting the AI fix things until it works”:
- Maximum 10 rounds: Stop after 10 failed attempts and report the stuck point to avoid spinning wastefully and burning tokens.
- Fix only one thing at a time: Fix the first error first before rerunning, as downstream errors sometimes disappear on their own.
- Do not delete tests: Fix the implementation if tests fail; only modify tests if they are clearly written incorrectly (for example, testing intentionally deprecated old behavior).
- Do not suppress errors: Prohibit using @ts-ignore, eslint-disable, arbitrary any types, or other methods to hide errors.
- Monitor error count: If the number of errors increases after a fix, stop and re-evaluate your approach.

Installation and Activation¶

Repository note: In Cursor, Skills are usually placed in the project’s .cursor/skills/ (or personal global directory) and are automatically detected by the Agent. The official collection also recommends installing via the community CLI npx skills.

Method 1: CLI Installation (Recommended)

Install a single Skill:

npx skills add spencerpauly/awesome-cursor-skills --skill grinding-until-pass

If using in Claude Code, you can specify the agent and install to the current project’s .claude/skills/:

npx skills add spencerpauly/awesome-cursor-skills --skill grinding-until-pass --agent claude-code

Method 2: Manual Copy

Extract resources/grinding-until-pass/SKILL.md from the repository and place it in the corresponding local directory, for example:

# Project-level for Cursor
.cursor/skills/grinding-until-pass/SKILL.md

# Or personal global for Cursor
~/.cursor/skills/grinding-until-pass/SKILL.md

Cursor also supports reading .agents/skills/, .claude/skills/, .codex/skills/ and their corresponding user home directory paths; Codex / Claude Code follow their own conventions using .codex/skills/ and .claude/skills/. Just follow the documentation for your current tool.

After activation, use /grinding-until-pass in the chat, or attach the Skill with @, then specify the target command; you can also directly describe “follow grinding-until-pass to make npm test pass all tests”.

Typical Usage¶

When tests turn red after a large refactor, dependency upgrades introduce type errors, or you need to resolve conflict-related failures after merging a branch, you can clearly state your goal and let the Agent loop according to the Skill. For example:

Follow grinding-until-pass.
Target command: npm test
Requirements: Fix only one failure at a time; do not delete tests; do not suppress errors with @ts-ignore / eslint-disable.
Maximum 10 rounds; report what was fixed and the number of iterations after passing.

If you want to pass type checks, linting, tests, and builds all at once:

Target command: npm run lint && npx tsc --noEmit && npm test && npm run build
Use grinding-until-pass to get everything passing.

The official also provides an advanced practice: using Cursor Hooks to automatically run tests again after the Agent finishes a round; if tests still fail, return a followup_message via the hook script to prompt for the next round automatically. An example configuration is written in the project’s .cursor/hooks.json:

{
  "hooks": [
    {
      "event": "stop",
      "command": "bash .cursor/scripts/check-tests.sh",
      "description": "Re-run tests after agent stops and send follow-up if failing"
    }
  ]
}

The check-tests.sh script needs to be implemented by yourself: check the test exit code, and return a follow-up message if the tests fail. This extends the “grind until green” workflow from a single chat request into an automatic接力 after each round of the Agent.

Applicable Scenarios and Notes¶

Applicable scenarios are consistent with the official description: multiple test failures after a large refactor, type errors introduced by dependency upgrades, resolving compilation/test failures after merging conflicts, and when you trust the test suite and just want to “make it green first” by handing over the mechanical cycle to the Agent.

A few notes before using:
- Tests should be fast: The official notes that if the test suite takes 5 minutes or more, the entire loop will be very slow; prioritize using unit tests or commands with --bail / --fail-fast to stop at the first failure as early as possible.
- Green does not equal correct design: The Skill emphasizes that the Agent will stick strictly to the requirements but is not good at large architectural changes; you still need to make decisions on product or design adjustments yourself.
- Success criteria must be machine-determinable: The target must be a single (or chained) command with a clear exit code; this Skill cannot be used without stable test/build commands.
- 10 rounds is a safety fuse: Repeated failed fixes usually mean the root cause is not in the local patch, so you should stop and re-examine the environment, data, or requirements themselves.

Summary¶

grinding-until-pass turns the verbal request of “fix until it works” into an installable, reusable Agent workflow: clear target commands, minimal fixes, prohibition of deleting tests or suppressing errors, and a 10-round limit. For daily mechanical tasks like “tests are red, types are broken, linting fails”, it can significantly reduce human back-and-forth; for problems that require design changes, it will honestly stop at the stuck point and hand the task back to you.

Official address: https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/grinding-until-pass

Let Agent fix itself until all tests pass with grinding-until-pass