Stage Gates: What Blocks Progress and Why

You just clicked Advance Stage and Fabriq responded with:

GATE_BLOCKED: Feature "add-dark-mode-toggle" cannot advance from Design to Implementation.
Missing required document: docs/04-technical-design.md

Don't panic. This is a stage gate — a deterministic check that ensures you have the prerequisite work done before moving to the next stage. The error message tells you exactly what's missing.

Why gates exist

Gates exist to prevent common failure modes:

• Skipping analysis: jumping into code without understanding the current state
• Coding before design: writing code without a technical plan
• Shipping without testing: approving changes without validating them

Every team says "we'd never do that." Gates make sure the process catches you if you try.

How gates work

When you click Advance Stage, Fabriq checks:

Current: Implementation
Requested: Validation

Gate checks:
✅ testability.md exists?        → Yes
❌ testability.md has content?   → No (file exists but is empty)
❌ Validation run completed?     → No (never ran)

Result: GATE_BLOCKED

The error message tells you exactly which check failed and what's needed to pass.

Common gate errors

Error	What's missing	How to fix
Missing required document: docs/03-business-design.md	The business design doc hasn't been created	Wait for the agent to finish the Design stage, or fill it in yourself
Missing required document: docs/04-technical-design.md	The technical design doc is missing	Same — the agent creates this during Technical Design
testability.md is empty	You haven't filled in the test plan	Go to the Tests tab and fill in entrypoints, scenarios, and scope
No validation runs found for this feature	Validation hasn't been executed	Run validation from the Validation tab first
Feature has not been reviewed or approved	The feature hasn't gone through the Review stage	Complete the review and click Approve
Validation run failed: 3 tests failing	Validation ran but tests didn't pass	Fix the failing tests (the agent helps) or accept known failures with confirmed=true

Hard vs soft gates

Type	Behavior	Can bypass?
Hard gate	Blocks advancement completely. No override.	No — missing critical prerequisite
Soft gate	Blocks advancement but allows bypass with confirmed=true	Yes — override is logged to audit

Hard gates protect against irreversible mistakes (e.g., closing without review). Soft gates protect against process skips (e.g., advancing without a design doc when you have a good reason).

Bypassing a gate

If you need to advance despite a gate failure:

1. In the gate error dialog, check "I understand the risk, advance anyway"
2. This uses confirmed=true — the override is logged to the audit trail
3. The stage advances

Use this sparingly. Each bypass is recorded with your identity and reason. If a gate is consistently blocking you for a valid reason, consider adjusting your process rather than repeatedly bypassing.

What to do when a gate blocks you

1. Read the error message — it tells you exactly what's missing
2. Fix what's missing — write the doc, fill in the form, run the validation
3. Try again — click Advance Stage once more

Gates are not punishments. They're guardrails. The error message is the fastest path to resolution.

Next steps

• Feature Lifecycle — see where gates fit in each stage
• Validation — from testability to test report
• Closing a Feature — the final gate before close
• Audit Trail — bypasses are logged here