[design-spec] vercel-project-path-traffic-health

[rw-codebundle-agent]

Design Spec: vercel-project-path-traffic-health

Parent: #79
Target: rw-cli-codecollection

Spec

# CodeBundle Design Spec: vercel-project-path-traffic-health
# Parent issue: runwhen-contrib/codecollection-registry#79

codebundle_name: "vercel-project-path-traffic-health"
target_collection: "rw-cli-codecollection"
display_name: "Vercel Project Path Traffic and Missing Routes"
author: "rw-codebundle-agent"

purpose: |
  Analyzes Vercel runtime request logs for a project to surface popular paths (high
  successful traffic), top missing routes (404), and simple anomalies such as sudden
  spikes in 404s for a path prefix. Complements error-rate monitoring by answering
  "what are users hitting" and "what are they failing to find."

tasks:
  - name: "Validate Vercel API Access and Resolve Project for `${VERCEL_PROJECT}`"
    description: |
      Same validation as sibling bundle: token, team scope, project resolution; shared
      behavior should match vercel-project-http-error-health for consistent UX.
    script_name: "vercel-validate-project.sh"
    expected_issue_severity: [3, 4]
    access_level: "read-only"
    data_type: "config"

  - name: "Resolve Production Deployment for Log Analysis for Project `${VERCEL_PROJECT}`"
    description: |
      Selects deployment used for log aggregation (latest production by default).
    script_name: "vercel-resolve-deployment.sh"
    expected_issue_severity: [2, 3]
    access_level: "read-only"
    data_type: "config"

  - name: "Rank Top Popular Paths by Successful Responses for Project `${VERCEL_PROJECT}`"
    description: |
      Aggregates 2xx (and optionally 3xx) hits by requestPath to list the most visited
      routes or assets in the lookback window.
    script_name: "vercel-top-paths-popular.sh"
    expected_issue_severity: [1, 2]
    access_level: "read-only"
    data_type: "metrics"

  - name: "Rank Top Missing Paths by 404 Count for Project `${VERCEL_PROJECT}`"
    description: |
      Lists paths with the highest 404 frequency to catch broken links, stale SEO URLs,
      or misconfigured rewrites.
    script_name: "vercel-top-paths-404.sh"
    expected_issue_severity: [2, 3]
    access_level: "read-only"
    data_type: "metrics"

  - name: "Detect Abnormal 404 Spike for Project `${VERCEL_PROJECT}`"
    description: |
      Compares 404 rate or count to `${NOT_FOUND_SPIKE_THRESHOLD_PCT}` (or absolute
      delta vs a baseline window if implemented) and raises issues when missing-route
      traffic surges unexpectedly.
    script_name: "vercel-detect-404-spike.sh"
    expected_issue_severity: [2, 4]
    access_level: "read-only"
    data_type: "metrics"

  - name: "Optional Path Prefix Summary for Project `${VERCEL_PROJECT}`"
    description: |
      Rolls up traffic and 404 counts by first path segment or configurable prefix map
      so large sites can see trends at section granularity (e.g. /blog, /docs).
    script_name: "vercel-summarize-path-prefixes.sh"
    expected_issue_severity: [1, 2]
    access_level: "read-only"
    data_type: "metrics"

scope:
  level: "Project"
  qualifiers:
    - VERCEL_TEAM_ID
    - VERCEL_PROJECT
  iteration_pattern: |
    One SLX per configured Vercel project under a team, matching project slug or id.

resource_types:
  - "vercel_project"
generation_strategy: |
  One TaskSet/SLX per Vercel project with qualifiers team id and project identifier.

env_vars:
  - name: VERCEL_TEAM_ID
    description: "Vercel team (teamId) scope for API calls"
    required: true

  - name: VERCEL_PROJECT
    description: "Project id or slug to analyze"
    required: true

  - name: LOOKBACK_MINUTES
    description: "Log aggregation window"
    required: false
    default: "60"

  - name: TOP_N_PATHS
    description: "How many paths to show in ranked lists"
    required: false
    default: "25"

  - name: NOT_FOUND_SPIKE_THRESHOLD_PCT
    description: "Issue when 404s exceed this share of sampled requests (configurable)"
    required: false
    default: "15"

secrets:
  - name: vercel_api_token
    description: "Vercel bearer token with read access to projects and deployment logs"
    format: "Plain text token (VERCEL_TOKEN or Bearer)"

platform:
  name: "vercel"
  cli_tools:
    - "curl"
    - "jq"
  auth_methods:
    - "Bearer token (read access to deployment runtime logs)"
  api_docs: "https://vercel.com/docs/rest-api"

related_bundles:
  - name: "vercel-project-http-error-health"
    relationship: "complements"
    notes: "Sibling bundle focuses on 4xx/5xx rates and error path rankings."
  - name: "curl-http-ok"
    relationship: "complements"
    notes: "Synthetic probes; this bundle summarizes real user path traffic from logs."

test_scenarios:
  - name: "steady_traffic"
    description: "Popular paths stable, 404s below spike threshold"
    expected_issues: 0

  - name: "404_campaign_spike"
    description: "Sudden surge in 404s for a new path prefix"
    expected_issues: 1
    expected_severities: [3]

notes: |
  Popular/missing path analysis relies on the same runtime log fields as the error
  bundle (requestPath, responseStatusCode). Very high QPS may require sampling; document
  methodology in the report. Browser Web Analytics is out of scope here. If runtime logs
  omit static edge-cached hits, call that limitation out in README and consider pairing
  with CDN or analytics in future work.

[rw-codebundle-agent]

🔧 Creator agent starting (sre mode). Target: runwhen-contrib/rw-cli-codecollection

[rw-codebundle-agent]

✅ Creator agent completed. PR: runwhen-contrib/rw-cli-codecollection#651

vercel-project-path-traffic-health — 104/104 (PASS)

Category	Score	Max
Structure	29	29
Robot Framework Quality	30	30
Execution Design	16	16
Generation Rules And Templates	18	18
Documentation	11	11