Build Verification Expert

Build Verification Expert

Systematic verification of build output after code changes. Catches the class of bugs that pass all tests but break in production: missing assets, broken static exports, inflated bundles, dead routes, and malformed sitemaps.

When to Use

Use for:

• Verifying a build completes without errors or warnings after significant changes
• Checking that static site exports contain all expected routes and pages
• Validating artifact sizes haven't regressed beyond acceptable thresholds
• Confirming asset references (images, fonts, scripts) resolve to real files
• Auditing sitemap.xml and robots.txt for correctness after content changes
• Comparing build output structure against a known-good baseline
• Pre-deploy sanity checks in CI or before manual deploy
• Diagnosing "works in dev but broken in production" issues

Do NOT use for:

• Writing or running unit/integration tests (use test-automation-expert)
• Performance profiling of the running application (use performance-profiling)
• Setting up CI/CD pipelines (use github-actions-pipeline-builder or cloudflare-pages-cicd)
• Optimizing bundle size proactively (use cost-optimizer or framework-specific skills)

Core Capabilities

1. Build Execution and Error Classification

Run the build and classify every diagnostic:

# Capture full build output with timing
time npm run build 2>&1 | tee /tmp/build-output.log

# Separate errors from warnings
grep -E "^(Error|error|ERROR)" /tmp/build-output.log > /tmp/build-errors.log
grep -iE "(warn|warning)" /tmp/build-output.log > /tmp/build-warnings.log

Error classification:

Critical rule: A build that exits 0 but emits TypeScript errors to stderr is NOT a passing build. Many frameworks continue past type errors in dev mode. Always check --strict or the equivalent.

2. Output Structure Validation

After a successful build, verify the output directory matches expectations:

# For Next.js static export
OUTPUT_DIR="out"

# Verify critical files exist
REQUIRED_FILES=(
  "index.html"
  "404.html"
  "_next/static"
  "sitemap.xml"
  "robots.txt"
  "favicon.ico"
)

for file in "${REQUIRED_FILES[@]}"; do
  if [ ! -e "$OUTPUT_DIR/$file" ]; then
    echo "MISSING: $file"
  fi
done

# Count HTML pages — compare against expected routes
ACTUAL_PAGES=$(find "$OUTPUT_DIR" -name "*.html" | wc -l)
echo "HTML pages found: $ACTUAL_PAGES"

Framework-specific output expectations:

3. Asset Reference Integrity

Broken asset references are the most common post-build failure. An image path that works in dev (via dev server magic) but fails in production (because the path is wrong relative to the output).

# Extract all asset references from HTML files
grep -rhoP '(?:src|href)="([^"]*)"' "$OUTPUT_DIR"/*.html | \
  sed 's/.*="\(.*\)"/\1/' | \
  sort -u > /tmp/referenced-assets.txt

# Check each reference resolves
while read -r ref; do
  # Skip external URLs, data URIs, and anchors
  if [[ "$ref" =~ ^(http|https|data:|#|mailto:) ]]; then
    continue
  fi

  # Resolve relative to output dir
  target="$OUTPUT_DIR/$ref"
  if [ ! -e "$target" ]; then
    echo "BROKEN REF: $ref"
  fi
done < /tmp/referenced-assets.txt

Common broken reference patterns:

• /images/logo.png when the actual file is at /img/logo.png
• Hashed filenames (main.abc123.js) not matching because the hash changed
• Absolute paths that assumed a subdirectory deploy but built for root
• Case sensitivity differences between macOS (case-insensitive) and Linux (case-sensitive)

4. Bundle Size Tracking

Size regressions are silent killers. A single unguarded import can add 200KB.

# Capture current sizes
find "$OUTPUT_DIR" -type f -name "*.js" -exec du -k {} + | sort -rn > /tmp/js-sizes.txt
find "$OUTPUT_DIR" -type f -name "*.css" -exec du -k {} + | sort -rn > /tmp/css-sizes.txt

# Total JS payload
JS_TOTAL=$(find "$OUTPUT_DIR" -name "*.js" -exec cat {} + | wc -c)
echo "Total JS: $(echo "scale=1; $JS_TOTAL / 1024" | bc)KB"

# Compare against threshold
JS_LIMIT_KB=500
JS_ACTUAL_KB=$((JS_TOTAL / 1024))
if [ "$JS_ACTUAL_KB" -gt "$JS_LIMIT_KB" ]; then
  echo "WARNING: JS bundle ($JS_ACTUAL_KB KB) exceeds limit ($JS_LIMIT_KB KB)"
fi

Size budget guidance:

5. Sitemap and SEO Artifact Validation

# Validate sitemap.xml is well-formed XML
xmllint --noout "$OUTPUT_DIR/sitemap.xml" 2>&1

# Extract URLs from sitemap and verify they correspond to real pages
grep -oP '<loc>\K[^<]+' "$OUTPUT_DIR/sitemap.xml" | while read -r url; do
  # Convert URL to local path
  path=$(echo "$url" | sed 's|https\?://[^/]*||')
  local_path="$OUTPUT_DIR${path}index.html"

  if [ ! -f "$local_path" ] && [ ! -f "$OUTPUT_DIR${path%.html}.html" ]; then
    echo "SITEMAP ORPHAN: $url has no corresponding page"
  fi
done

# Check robots.txt
if [ -f "$OUTPUT_DIR/robots.txt" ]; then
  echo "robots.txt exists"
  # Verify sitemap reference
  grep -q "Sitemap:" "$OUTPUT_DIR/robots.txt" || echo "WARNING: robots.txt missing Sitemap directive"
else
  echo "WARNING: No robots.txt found"
fi

6. Static Export Completeness

For statically exported sites, every route must produce an HTML file:

# Extract all internal links from the built site
grep -rhoP 'href="(/[^"]*)"' "$OUTPUT_DIR" | \
  sed 's/href="//;s/"//' | \
  sort -u > /tmp/internal-links.txt

# Check each link resolves to a file
while read -r link; do
  # Try both /path/index.html and /path.html
  if [ ! -f "$OUTPUT_DIR${link}index.html" ] && \
     [ ! -f "$OUTPUT_DIR${link}.html" ] && \
     [ ! -f "$OUTPUT_DIR${link}" ]; then
    echo "DEAD INTERNAL LINK: $link"
  fi
done < /tmp/internal-links.txt

Decision Points

When to Fail vs Warn

Build Comparison Strategy

When comparing against a baseline:

1. Always compare against the last known-good build, not against "what I expect."
2. Store baselines as JSON manifests: { "files": [...], "sizes": {...}, "routes": [...] }
3. Diff the manifests to surface additions, removals, and size changes.
4. New files are usually fine. Missing files are usually bad.

Anti-Patterns

Anti-Pattern: "Build Passed, Ship It"

What it looks like: CI shows green checkmark because npm run build exited 0.

Why wrong: A zero exit code means the build tool finished. It does not mean the output is correct, complete, or deployable. Frameworks routinely exit 0 while emitting warnings about missing pages, oversized bundles, or unresolved imports that fall back to runtime errors.

Instead: Run explicit post-build verification. The build command is step 1. Verification is step 2. They are not the same step.

Anti-Pattern: Manual Spot-Checking

What it looks like: Developer opens the built site in a browser, clicks around for 30 seconds, says "looks good."

Why wrong: Humans cannot visually verify 50 routes, 200 asset references, and bundle sizes in 30 seconds. They check the homepage and maybe one other page.

Instead: Automated scripts that exhaustively check every route and asset. Human review is for visual fidelity, not structural integrity.

Anti-Pattern: Ignoring Warnings

What it looks like: Build output shows 47 warnings. Developer says "those have always been there."

Why wrong: Warning count creep is how technical debt compounds. Each warning was once new. Nobody investigated it. Now there are 47 and nobody reads them. The 48th warning — the one that actually matters — is invisible.

Instead: Treat warning count as a ratchet. Today's count is the ceiling. New warnings must be resolved or explicitly acknowledged before merge. Track warning count in CI and fail if it increases.

Anti-Pattern: Size Limits Without Context

What it looks like: "Our bundle limit is 500KB" applied uniformly to every page.

Why wrong: A landing page and an admin dashboard have different size budgets. The landing page needs to be fast for first-time visitors on mobile. The admin dashboard is used by logged-in users on desktop who will tolerate a larger initial load.

Instead: Per-route or per-entry-point size budgets. Use tools like bundlesize, size-limit, or next/bundle-analyzer to set granular limits.

Quality Checklist

Before declaring a build verified:

• Build completed with exit code 0
• Zero TypeScript/compilation errors in output log
• All expected route HTML files exist in output directory
• All asset references (src, href) resolve to real files in output
• No case-sensitivity mismatches between references and filenames
• Bundle sizes within established budgets (JS, CSS, images)
• sitemap.xml is well-formed and all URLs correspond to real pages
• robots.txt exists and references the sitemap
• favicon.ico and meta assets present
• No new warnings introduced (warning count stable or decreased)
• Output directory contains no unexpected large files (>1MB)
• If static export: internal links all resolve to HTML files
• If Cloudflare/Vercel/Netlify: platform-specific files present (_redirects, _headers, _worker.js)

Output Contract

This skill produces:

• Build verification report listing pass/fail/warn for each check category
• Size diff comparing current build against baseline (if baseline exists)
• Broken reference list with file:line locations of each broken asset reference
• Route coverage report mapping expected routes to their HTML file presence
• Actionable fix list prioritized by severity (FAIL items first, then WARN)

References

• references/build-manifest-schema.md -- JSON schema for build baseline manifests used in comparisons
• references/framework-output-maps.md -- Expected output structures for Next.js, Vite, Astro, and Cloudflare Pages