Reviewen Randy - Complete Documentation

Reviewen Randy - Complete Documentation

AI-Powered SEO Meta Auditor for Google Sheets

Table of Contents

• Introduction
• Getting Started
• Understanding Lil Randy vs Full Randy
• Reading Your Results
• What Randy Checks
• Scoring System
• Best Practices
• Troubleshooting
• Technical Details

Introduction

Reviewen Randy is a Google Sheets add-on that audits meta titles and descriptions for SEO quality and technical compliance. It combines code-based validation (100% accurate) with AI-powered quality assessment.

Key Features:

• ✅ Instant technical validation (length, double spaces, prohibited terms)
• ✅ AI quality review (CTAs, clarity, keyword usage)
• ✅ Batch processing (up to 50 pages in seconds)
• ✅ Australian English compliance
• ✅ Weighted scoring system
• ✅ Review history with navigation

Getting Started

Step 1: Prepare Your Sheet

Have a sheet named "export" (or configure custom name) with these columns:

Required columns (case-insensitive):

• URL - Full page URL
• Title - Meta title
• Description or Desc - Meta description
• H1 - Page H1 heading

Step 2: Open Randy

• Click Reviewen Randy menu in Google Sheets
• Select "Open Sidebar"
• The sidebar will appear on the right

Step 3: Run Your Review

Choose your review type:

Lil Randy (Recommended for most audits)

• Fast batch analysis (~5 seconds for 50 pages)
• Objective violations only
• Binary checks (yes/no issues)

Full Randy (For detailed feedback)

• Deep per-page review (~2 minutes for 15 pages)
• Includes writing suggestions
• Quality assessments

Understanding Lil Randy vs Full Randy

Lil Randy - Quick Batch Checker

Best for:

• Regular quality checks
• Large page sets (up to 50)
• Finding technical violations
• Pre-publish validation

What it checks:

• ✅ Missing CTAs (binary: present or not)
• ✅ Separator inconsistency
• ✅ AU spelling errors
• ✅ Code validates: length, double spaces, prohibited terms, duplicates

What it DOESN'T do:

• ❌ Subjective quality assessments
• ❌ Writing suggestions
• ❌ "Could be better" feedback

Example output:

• "Missing CTA" (binary violation)
• "Double space in title" (technical error)
• NOT: "Description could be more compelling" (subjective)

Full Randy - Comprehensive Review

Best for:

• New page creation
• High-value pages (homepage, key landing pages)
• Content improvement projects
• Learning better meta writing

What it checks:

• ✅ Everything Lil Randy checks
• ✅ CTA strength and effectiveness
• ✅ Keyword placement and usage
• ✅ Clarity and alignment
• ✅ Compelling vs generic language
• ✅ Brand voice consistency

What you get:

• Technical violations
• Quality assessments
• Specific rewrite suggestions
• Strategic recommendations

Example output:

• "Missing CTA" (violation)
• "CTA present but could be stronger - consider 'Get expert advice today' instead of 'Learn more'" (quality)
• "Description is generic - add specific benefit or unique value proposition" (suggestion)

Reading Your Results

The Results Card

Randy's Message:

• 🟢 "Looking good, mate!" = 80-100 score
• 🔵 "Not too shabby!" = 60-79 score
• 🟡 "Bit of work needed..." = 40-59 score
• 🔴 "No good, might need to read this" = 0-39 score

Top Level Issues

Common patterns affecting multiple pages:

Top Level Issues

├─ 3 pages with double spaces

├─ 5 titles exceed 700px

└─ 2 pages missing CTAs

URL by URL Issues

Individual page problems with priority colors:

🔴 High Priority (Red background)

• Double spaces
• Spelling errors / typos
• Prohibited terms
• Other errors

Fix these FIRST - they're objective mistakes that hurt credibility.

🟡 Medium Priority (Yellow background)

• Title too long
• Description too long
• Separator issues

⚪ Low Priority (Gray background)

• Missing H1
• Quality suggestions
• Other recommendations

Navigation

Use the navigation bar to review past audits:

[← Previous] Review 4 of 4 [LATEST] [Next →]

• Latest review = Always shown first (highest number)
• Previous = Go back in time to older reviews
• Next = Go forward to newer reviews

Toggle H1 Issues

Click "Show H1 Issues" / "Hide H1 Issues" to filter results:

• Hide: Focus on title/description only
• Show: Include all H1 problems

What Randy Checks

Code-Based Validation (100% Accurate)

These checks are performed by code - never hallucinated, always reliable:

1. Length Check

• Title: Flags if > 700px (~65+ chars)
• Target: 55 chars / 600px
• Format: "Title too long - Current: 68 chars (705px), Recommended: 55 chars (600px)"
• Description: Flags if > 1050px (~165+ chars)
• Target: 155 chars / 920px
• Format: "Description too long - Current: 165 chars (998px), Recommended: 155 chars (920px)"

Why pixels? Different characters have different widths. "WWW" is wider than "iii". Randy counts pixels for accurate SERP display.

2. Double Spaces

• Detects: Two or more consecutive spaces
• Format: "Double space in title" or "Double space in description"
• Impact: -10 points (high severity)

3. Prohibited Terms

Exact whole-word matches (case-insensitive):

• "top notch" or "top-notch"
• "superior"
• "swift"
• "delve"

Format: Contains prohibited term: "top-notch" Impact: -10 points (high severity)

4. Duplicate Descriptions

• Flags: 100% identical descriptions across pages
• Format: "4 pages have identical descriptions: 'Barry Nilsson is a leading...'"

AI-Based Validation

5. Missing CTA (Binary)

Lil Randy: Only flags if NO call-to-action exists Full Randy: Flags missing CTAs AND suggests improvements

Valid CTAs:

• "Enquire online"
• "Contact us"
• "Get in touch"
• "Book now"
• "Call today"

❌ Lil Randy will NOT flag: "Weak CTA" or "Could be better" ✅ Full Randy WILL provide: CTA strength feedback

6. Separator Consistency

Flags if DIFFERENT separators are mixed across titles:

Valid separators:

• - (hyphen)
• – (en dash)
• — (em dash)
• | (pipe)

✅ OK: All titles use - ✅ OK: All titles use | ❌ FLAG: 5 titles use -, 3 titles use |

7. AU Spelling

Flags actual misspellings and US spelling:

Common AU vs US:

• ❌ organize → ✅ organise
• ❌ color → ✅ colour
• ❌ center → ✅ centre

8. Quality Assessments (Full Randy Only)

• Keyword placement and usage
• Clarity and alignment with page intent
• Compelling vs generic language
• Brand voice consistency
• Location mention appropriateness

Scoring System

Randy uses weighted scoring based on issue severity:

Point Deductions

High Severity (-10 points each):

• Double spaces
• Prohibited terms
• Spelling errors
• Typos

Medium Severity (-5 points each):

• Title too long (>700px)
• Description too long (>1050px)
• Separator inconsistency

Low Severity (-3 points each):

• Missing H1
• Templated descriptions
• Quality suggestions

Score Ranges

Score Examples

Example 1: Perfect Score

• 0 issues = 100/100 ✅

Example 2: One Double Space

• 1 double space = 90/100 (-10 points)

Example 3: Mixed Issues

• 1 typo (-10) + 2 length issues (-10) + 1 H1 (-3) = 77/100

Example 4: Critical Errors

• 3 double spaces (-30) + 2 prohibited terms (-20) = 50/100

Best Practices

When to Use Lil Randy

✅ Use for:

• Regular batch audits
• Pre-publish checks
• Finding technical violations
• Large page sets (20-50 pages)
• Quick quality validation

⏱️ Processing time: 3-8 seconds

When to Use Full Randy

✅ Use for:

• New page creation
• Homepage and key landing pages
• Content improvement projects
• Learning better meta writing
• Smaller focused sets (5-15 pages)

⏱️ Processing time: 30 seconds - 2 minutes

Meta Writing Tips

Titles:

• Keep ~55 chars / 600px target
• Use one separator consistently
• Include primary keyword once
• Match page intent
• Format: Keyword/Service – Brand or Brand – What You Do

Descriptions:

• Keep 130-155 chars / 920px target
• Include keyword naturally once
• Add clear CTA
• Include USP/benefit
• Be specific, not generic

Example - Good:

Title: Family Law Solicitors Melbourne – Smith Legal

Desc: Expert family law advice for divorce, custody, and property settlements in Melbourne. Enquire online for a confidential consultation.

Example - Bad:

Title: Smith Legal | Family Law | Melbourne | Divorce | Custody | Property | Experts

Desc: We are the best law firm in Melbourne. We provide superior service. Contact us today to learn more about our services.

Review Workflow

• Export your pages to Google Sheets
• Run Lil Randy for quick check
• Fix all red issues (double spaces, typos, prohibited terms)
• Fix medium issues (length, separators)
• Run Full Randy on key pages for quality feedback
• Iterate and improve
• Re-run Lil Randy to verify all issues resolved

Troubleshooting

"No rows provided" Error

Issue: Sheet name not found

Fix:

• Ensure sheet is named "export" (case-insensitive)
• OR set custom sheet name in Script Properties: INPUT_SHEET_NAME

"Missing input sheet" Error

Issue: Required columns not found

Fix: Ensure your sheet has columns named (case-insensitive):

• URL
• Title
• Description (or Desc)
• H1

"OPENAI_API_KEY not found" Error

Issue: API credentials not configured

Fix:

• Verify GCP_PROJECT_NUMBER is set in Script Properties
• Ensure OPENAI_API_KEY exists in Secret Manager
• Check IAM permissions are configured correctly

Results Not Showing

Issue: Empty results or "No results yet"

Fix:

• Click Refresh button
• Check if review actually ran (look for "done" status)
• Try closing and reopening sidebar

Webmaster - Permissions

You need sign out of in your browser

AI Hallucinating Issues

This shouldn't happen! Randy uses code for all binary checks.

If you see false positives:

• Check if it's in a subjective category (Full Randy quality assessment)
• Report in #seo-help with example
• We may need to move more checks to code

Technical Details

Models Used

• Lil Randy: gpt-5-nano or gpt-4o-mini
• Full Randy: gpt-5-mini or gpt-4o-mini

Set via Script Properties: OPENAI_MODEL

Configuration Options

Script Properties (optional):

Page Limits

• Lil Randy: Up to 50 pages
• Full Randy: Up to 15 pages
• Basic review: Configurable via MAX_LOCAL (default: 3)

Results Storage

Results are stored in hidden sheet _ai_results with:

• URL
• Status
• Timestamp
• Model used
• Raw AI response
• Parsed results
• Review score (weighted)

Each batch creates a new BATCH_SUMMARY_V# entry.

Review History

Randy keeps all past reviews. Navigate using:

• Previous = Older reviews
• Next = Newer reviews
• Latest badge = Most recent review

Support

Questions? Ask in #seo-help

Bug reports? Include:

• What you were doing
• Error message (if any)
• Expected vs actual behavior
• Screenshot if helpful

Feature requests? We're always improving Randy!

Changelog

Current Version: Workspace Edition with Secret Manager

Recent updates:

• ✅ Code-based validation for length, double spaces, prohibited terms
• ✅ Weighted scoring system (high/medium/low severity)
• ✅ Review history with navigation
• ✅ Improved sidebar with priority colors
• ✅ "No issues found" success state
• ✅ Lil Randy vs Full Randy separation
• ✅ Toggle H1 issues visibility