Automated Quality Guardrails Engine

The Quality Guardrails Engine is an automated governance pipeline (.github/scripts/doc_quality_checker.py) that audits newly created or modified Markdown files during pull requests using the Gemini API.

🎯 Key Capabilities

Automated Style & Tone Review: Evaluates documentation against strict standards for active voice, clear heading structure, code example completeness, and callout usage (> [!NOTE]).
Dynamic Rate-Limit Parsing: Extracts the exact retryDelay metadata directly from Gemini API error payloads (429 / 503 status codes) to dynamically back off during quota limits rather than failing abruptly.
Quota Conservation: Automatically filters out auto-generated gap stubs stored under docs/gaps/ during PR runs to conserve API request quotas for user-authored updates.

⚙️ Workflow Execution & Environment

The script runs within a GitHub Actions workflow and relies on the following environment variables:

GEMINI_API_KEY="..."
GITHUB_TOKEN="..."
PR_NUMBER="12"
REPOSITORY="user/repo"
CHANGED_FILES="docs/setup-guide.md docs/gaps/gap_stub.md"

🔍 Core Logic Highlights

File Filtering (Excluding Stubs) To prevent automated gap PRs from exhausting API quotas, files under docs/gaps/ are filtered out before calling the LLM:

Python md_files = [ f for f in CHANGED_FILES if f.endswith((“.md”, “.markdown”)) and not f.startswith(“docs/gaps/”) ]

Smart Retry Delay Parsing When the Gemini API returns a rate limit error, the script parses the recommended wait duration from the error details:

Python details = error_data.get(“error”, {}).get(“details”, []) for d in details: if “retryDelay” in d: # Strip trailing ‘s’ and add a 1-second buffer raw_delay = d[“retryDelay”].rstrip(“s”) retry_delay = float(raw_delay) + 1.0 📊 PR Evaluation Output Upon completing the evaluation, the engine compiles the results and posts a summary comment directly to the GitHub PR thread:

🛠️ Automated Doc Quality Guardrails Review File: docs/setup-guide.md — Score: 9/10 (🟢 PASS) What works well:

Direct second-person address (“you”) and clear prerequisites section.
Proper syntax highlighting on code snippets.