If a Quality Gate Fails
Gate failures are a normal part of building, and Claude handles most of them without you. What you need to do depends on where the failure happens.
During the build
Section titled “During the build”Claude reads the failure, fixes it and re-runs the check, up to three times. You only hear about it if the third attempt fails. Claude then explains the problem and your options.
Run /quality-check at any time to see the current status of the automated gates.
On the pull request
Section titled “On the pull request”If a GitHub check fails after the pull request opens, Claude doesn’t fix it on its own. It asks whether to re-run the checks, diagnose the failure with you, or force the merge. See What Happens When a Gate Fails.
A failure here usually comes from the environment rather than the code. Try a re-run first.
Common failures
Section titled “Common failures”| Failure | What to do |
|---|---|
| A dependency vulnerability (Gate 2) | Ask Claude: “npm audit is showing vulnerabilities. Can you fix them?” If there’s no fix yet, add a time-limited exception. |
| A commit blocked by the pre-commit check (Gate 3) | Ask Claude: “My commit is being blocked by pre-commit checks. Can you fix the issues?” |
| The same gate keeps failing | The failure usually reveals a conflict in your requirements, or needs a product decision. Describe the behaviour you want and Claude implements it. |
What not to do
Section titled “What not to do”Don’t bypass the gates or disable the checks. They exist to keep main working.
If a gate seems wrong for your project, such as a security rule that’s too strict, tell Claude. It can adjust the configuration and explain the trade-off, rather than hide the problem.