The Built-in Guide Skill Is Only Advice — Pair It With a Gate That Mechanically Rejects Antigravity's Output

Put "the reasons behind decisions" in the advisory layer

So what belongs in the Guide? I center it on things a machine can't inspect after the fact.

• Why this repository uses HTML tables (the renderer doesn't parse GFM)
• Why commits stay small (so review units can be reverted independently)
• Naming and tone policy (reader-facing prose, avoid hyperbole)

Conversely, mechanically inspectable rules (table syntax, file correspondence, banned words) may go in the Guide, but I place them there on the premise that I won't rely on them. The Guide shares intent; inspection is a separate layer. That division of labor is the whole idea.

# Repository Guide (excerpt)
 
## Tables
- Always write tables as HTML <table>. Markdown pipe syntax renders broken.
- Background: this project's renderer does not load the GFM table extension.
 
## Commit granularity
- One commit = one meaningful change. Don't mix mechanical replacements with semantic ones.
- Reason: keep units where a reviewer can choose to revert just this part.
 
## Tone
- Reader-facing prose stays polite and plain.
- No hyperbole (best-ever, blazing, godlike).

An agent that reads this Guide writes HTML tables almost every time. Turning "almost" into "always" is the job of the next, deterministic layer.

The deterministic layer: stop inspectable rules in code

Rules a machine can decide, I reject in code rather than ask for in prose. The key is that the gate returns only true or false. It admits no ambiguity.

Below is a minimal gate that verifies the two machine-checkable rules among the three in my Guide. It takes the agent's generated or edited output and, on violation, returns exit code 1 along with the offenses.

#!/usr/bin/env python3
"""guide_gate.py — deterministically verify the machine-checkable parts of the Guide.
   exit 0 = pass / exit 1 = violation (offenses printed to stdout)"""
import re
import sys
from pathlib import Path
 
# Rule 1: forbid Markdown pipe tables (outside code fences); force HTML <table>
TABLE_SEP = re.compile(r"(?m)^\s*\|?[ :]*-{2,}[ :]*(?:\|[ :]*-{2,}[ :]*)+\|?\s*$")
# Rule 2: banned words (hyperbole)
BANNED = ["best-ever", "blazing-fast", "godlike", "everything you need"]
 
def strip_code(text: str) -> str:
    text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
    return re.sub(r"`[^`\n]*`", "", text)
 
def check(path: Path):
    body = strip_code(path.read_text(encoding="utf-8"))
    issues = []
    if TABLE_SEP.search(body):
        issues.append("markdown-table: pipe-syntax table found; convert to <table>")
    for w in BANNED:
        if w in body:
            issues.append(f"banned-word: found '{w}'")
    return issues
 
def main():
    failed = False
    for arg in sys.argv[1:]:
        issues = check(Path(arg))
        if issues:
            failed = True
            print(f"[NG] {arg}")
            for i in issues:
                print(f"   - {i}")
        else:
            print(f"[OK] {arg}")
    sys.exit(1 if failed else 0)
 
if __name__ == "__main__":
    main()

The implementation detail that matters is stripping code blocks with strip_code() first, so example tables inside fences aren't falsely flagged. When I first wrote this, the gate kept reacting to the sample tables in an article and looped on endless rework. That "exclude examples from what you inspect" trap is common to verification gates.

The loop that feeds violations back to the agent

When the gate returns a violation, a human doesn't fix it — the violation text is handed straight back to the agent to fix. When the Guide drives intent, the gate decides facts, and the bounce-back drives correction, the workflow runs almost unattended.

#!/usr/bin/env bash
# regenerate_until_clean.sh — have the agent fix until the gate passes
set -euo pipefail
MAX_RETRY=3
TARGET="$1"   # file to verify
 
for attempt in $(seq 1 "$MAX_RETRY"); do
  if python3 guide_gate.py "$TARGET"; then
    echo "✅ gate passed (attempt ${attempt})"
    exit 0
  fi
  echo "↩️ bouncing violations back for regeneration (${attempt}/${MAX_RETRY})"
  VIOLATIONS="$(python3 guide_gate.py "$TARGET" || true)"
  agy run --file "$TARGET" --instruction "Fix only the following violations. Touch nothing else:
${VIOLATIONS}"
done
 
echo "🛑 did not converge in ${MAX_RETRY} attempts. Escalate to human review."
exit 1

agy run is how I invoke it in my environment, so adapt the launch to your own setup. The argument design is what counts. On bounce-back, scope it: "Fix only the following violations. Touch nothing else." Without that line, the agent rewrites unrelated lines while it's in there, and the review surface balloons. Capping retries (three here) and escalating to a human is equally essential — an unbounded loop quietly burns tokens.

Results: advice-only vs advice + gate

Here is the comparison from two weeks across four repositories. The counts are hand-tallied, so this is not rigorous statistics, but the trend was clear.

Notice that adding the gate to the Guide doesn't change the violation rate itself. The gate isn't a tool for reducing occurrences; it's a tool for keeping the ones that occur out of production. The roles differ, so neither layer closes the workflow alone. Lower the violation rate with the Guide; drive slips to zero with the gate — keep that division in mind from the start and the design comes out clean.

For me, after switching to this combination, even changes like AdMob configuration files — where a break hits revenue directly but is hard to spot by eye — get stopped by the gate first. The drop in the psychological load of review mattered more than the numbers.

Your next step

Start by sorting the rules currently in your AGENTS.md into two piles: "intent a human should understand the background of" and "rules a machine can decide true or false." The former goes to the Guide skill; the latter to a ten-line gate. Begin your first gate with a rule you've personally let slip at least once before — you'll feel the effect immediately. Whether you can build the paradox "the better the advice works, the more inspection it needs" into your operations is, I think, what decides whether you can run an agent unattended for the long haul.