curiositech/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:

| Severity | Pattern | Action | |----------|---------|--------| | Fatal | Error: Build failed, non-zero exit code | Stop. Fix before proceeding. | | Type error | TS\d+:, Type '...' is not assignable | Fix. These are bugs hiding as warnings. | | Missing module | Module not found, Cannot resolve | Check imports, package.json, and tsconfig paths. | | Deprecation | DeprecationWarning | Log for future cleanup, not blocking. | | Size warning | exceeds the recommended size limit | Investigate if new, acceptable if known. |

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:

| Framework | Output Dir | Key Artifacts | |-----------|-----------|---------------| | Next.js (static) | out/ | index.html, _next/static/, _next/data/ | | Next.js (server) | .next/ | .next/server/, .next/static/ | | Vite/React | dist/ | index.html, assets/ | | Astro | dist/ | Per-route HTML, _astro/ | | Cloudflare Pages | out/ or dist/ | _worker.js (if functions), _headers, _redirects |

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:

| Asset Type | Warning Threshold | Hard Limit | Why | |-----------|-------------------|------------|-----| | Total JS | 300KB gzipped | 500KB gzipped | LCP impact on mobile | | Single chunk | 150KB gzipped | 250KB gzipped | Parse time | | Total CSS | 50KB gzipped | 100KB gzipped | Render blocking | | Individual image | 200KB | 500KB | Layout shift, bandwidth | | Total HTML per page | 100KB | 200KB | Time to first byte |

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

| Condition | Verdict | Reasoning | |-----------|---------|-----------| | Build exits non-zero | FAIL | Obvious. Nothing to verify. | | TypeScript errors in output | FAIL | Type errors are bugs. Period. | | Missing route HTML file | FAIL | 404 in production. | | Broken asset reference | FAIL | Visible breakage to users. | | Bundle size exceeds hard limit | FAIL | Performance degradation ships. | | Bundle size exceeds warning threshold | WARN | Investigate, but may be intentional. | | Deprecation warnings | WARN | Track, schedule cleanup. | | New unrecognized file type in output | WARN | Could be intentional, could be accidental. | | Sitemap URL with no page | WARN | SEO issue, not user-facing breakage. |

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