Skip to content

vercel-labs/agent-skills / skills/vercel-optimize

vercel-optimize

Verified

Use for Vercel cost and performance optimization on deployed projects, especially Next.js, SvelteKit, Nuxt, and limited Astro apps. Collect Vercel metrics, usage, project config, and code scan results first; investigate only metric-backed candidates; produce ranked recommendations grounded in verified files and version-aware Vercel/framework docs. Trigger for Vercel bill reduction, slow or expensive routes, caching opportunities, Function Invocations, Build Minutes, Fast Data Transfer, Core Web Vitals, Bot Management, Fluid compute, or cost breakdown requests.

FileKindSize
AGENTS.mdmarkdown1.9 KB
CONTRIBUTING.mdmarkdown2.2 KB
README.mdmarkdown4.4 KB
SKILL.mdskill md16.9 KB
lib/auth-route.mjsscript807 B
lib/budget-summary.mjsscript7.0 KB
lib/citations.mjsscript3.9 KB
lib/cost-coverage.mjsscript8.4 KB
lib/dedup-recs.mjsscript9.9 KB
lib/deep-dive.mjsscript10.2 KB
lib/display-labels.mjsscript7.4 KB
lib/extract-claims.mjsscript18.7 KB
lib/framework-support.mjsscript2.1 KB
lib/gates/build-minutes-fanout.mjsscript2.9 KB
lib/gates/cold-start.mjsscript2.7 KB
lib/gates/contract.mjsscript3.1 KB
lib/gates/cwv-poor.mjsscript3.3 KB
lib/gates/external-api-slow.mjsscript2.1 KB
lib/gates/hard-gates.mjsscript2.5 KB
lib/gates/index.mjsscript2.0 KB
lib/gates/isr-overrevalidation.mjsscript2.4 KB
lib/gates/middleware-heavy.mjsscript2.0 KB
lib/gates/observability-events-attribution.mjsscript2.2 KB
lib/gates/platform-bot-protection.mjsscript5.0 KB
lib/gates/platform-fluid-compute.mjsscript3.5 KB
lib/gates/region-misconfig.mjsscript3.0 KB
lib/gates/route-errors.mjsscript3.0 KB
lib/gates/scanner-driven.mjsscript5.1 KB
lib/gates/select-candidates.mjsscript4.6 KB
lib/gates/slow-route.mjsscript4.3 KB
lib/gates/types.d.tsscript893 B
lib/gates/uncached-route.mjsscript3.9 KB
lib/gates/usage-spike-triage.mjsscript5.0 KB
lib/grade-recommendation.mjsscript6.7 KB
lib/impact-label.mjsscript5.2 KB
lib/impact-magnitude.mjsscript2.1 KB
lib/investigation-brief.mjsscript34.3 KB
lib/observation-safety.mjsscript9.3 KB
lib/project-facts.mjsscript4.3 KB
lib/queries.mjsscript10.1 KB
lib/reconcile-candidates.mjsscript15.6 KB
lib/render-report.mjsscript38.2 KB
lib/repo-root.mjsscript3.1 KB
lib/route-normalize.mjsscript8.4 KB
lib/sanitizers/bot-protection-certainty.mjsscript1.9 KB
lib/sanitizers/cache-tag-invalidation-certainty.mjsscript1.5 KB
lib/sanitizers/count-correct.mjsscript1.9 KB
lib/sanitizers/function-duration-invocations.mjsscript1.4 KB
lib/sanitizers/index.mjsscript3.0 KB
lib/sanitizers/middleware-conflict.mjsscript1.5 KB
lib/sanitizers/missing-citation.mjsscript497 B
lib/sanitizers/pre-release.mjsscript2.2 KB
lib/sanitizers/rate-limit.mjsscript2.6 KB
lib/sanitizers/rendering-mode-mislabel.mjsscript1.6 KB
lib/sanitizers/undeclared-dep.mjsscript2.8 KB
lib/sanitizers/vercel-directive-strip.mjsscript1.4 KB
lib/sanitizers/window-units.mjsscript869 B
lib/scanners/cache-components-suspense-dedupe.mjsscript4.3 KB
lib/scanners/edge-heavy-import.mjsscript3.7 KB
lib/scanners/force-dynamic.mjsscript1.5 KB
lib/scanners/headers-in-page.mjsscript1.5 KB
lib/scanners/index.mjsscript1.4 KB
lib/scanners/large-static-asset.mjsscript3.2 KB
lib/scanners/max-age-without-s-maxage.mjsscript1.6 KB
lib/scanners/middleware-broad-matcher.mjsscript1.9 KB
lib/scanners/missing-cache-headers.mjsscript3.8 KB
lib/scanners/prisma-include-tree.mjsscript1.5 KB
lib/scanners/region-pin-in-config.mjsscript3.4 KB
lib/scanners/source-maps-production.mjsscript1.3 KB
lib/scanners/sveltekit-prerender-missing.mjsscript2.1 KB
lib/scanners/turbo-force-bypass.mjsscript4.9 KB
lib/scanners/unoptimized-image.mjsscript4.4 KB
lib/scanners/use-cache-date-stamp.mjsscript3.9 KB
lib/support-topics.mjsscript12.5 KB
lib/throttle.mjsscript8.8 KB
lib/util.mjsscript544 B
lib/vercel.mjsscript30.4 KB
lib/verify-claim.mjsscript59.6 KB
lib/workspace-resolver.mjsscript17.1 KB
metadata.jsonconfig903 B
references/candidates.mdmarkdown8.3 KB
references/data-collection.mdmarkdown20.4 KB
references/docs-library.jsonconfig30.8 KB
references/doctrine.mdmarkdown9.3 KB
references/observability-plus.mdmarkdown5.2 KB
references/playbooks/README.mdmarkdown2.7 KB
references/playbooks/ai-application.mdmarkdown3.8 KB
references/playbooks/api-service.mdmarkdown2.4 KB
references/playbooks/content-site.mdmarkdown2.4 KB
references/playbooks/ecommerce.mdmarkdown2.7 KB
references/playbooks/marketing.mdmarkdown2.6 KB
references/playbooks/saas.mdmarkdown2.8 KB
references/playbooks/sveltekit.mdmarkdown3.9 KB
references/recommendations.mdmarkdown10.5 KB
references/scanner-patterns.mdmarkdown13.4 KB
references/scoring.mdmarkdown12.2 KB
references/support-topics/README.mdmarkdown1.7 KB
references/support-topics/astro-edge-middleware-scope.mdmarkdown1012 B
references/support-topics/astro-output-mode-and-isr.mdmarkdown1.1 KB
references/support-topics/auth-preserving-parallelization.mdmarkdown1.2 KB
references/support-topics/bot-protection-product-guardrails.mdmarkdown1.1 KB
references/support-topics/build-minutes-monorepo-fanout.mdmarkdown1.2 KB
references/support-topics/cache-components-static-shell-boundaries.mdmarkdown1.1 KB
references/support-topics/cache-components-suspense-dedupe-pitfall.mdmarkdown1.3 KB
references/support-topics/cdn-cache-auth-safety.mdmarkdown1.0 KB
references/support-topics/cold-start-initialization-bundle.mdmarkdown1.1 KB
references/support-topics/core-web-vitals-client-bottlenecks.mdmarkdown1.0 KB
references/support-topics/database-egress-pooling-region.mdmarkdown1015 B
references/support-topics/dynamic-rendering-traps.mdmarkdown1.1 KB
references/support-topics/external-api-critical-path-platform.mdmarkdown1.1 KB
references/support-topics/external-api-critical-path.mdmarkdown978 B
references/support-topics/fast-data-transfer-payloads.mdmarkdown1.0 KB
references/support-topics/fluid-compute-caveats.mdmarkdown1.1 KB
references/support-topics/function-duration-io-and-after.mdmarkdown1.0 KB
references/support-topics/function-invocation-reduction.mdmarkdown1.2 KB
references/support-topics/function-region-misconfiguration-ttfb.mdmarkdown1.2 KB
references/support-topics/image-optimization-cost-control.mdmarkdown1.0 KB
references/support-topics/isr-revalidation-static-generation.mdmarkdown1.4 KB
references/support-topics/middleware-proxy-edge-cost.mdmarkdown991 B
references/support-topics/next-fetch-revalidate-floor.mdmarkdown1.0 KB
references/support-topics/next-font-cls-self-hosting.mdmarkdown906 B
references/support-topics/next-heavy-ui-lazy-load-boundaries.mdmarkdown1.0 KB
references/support-topics/next-image-lcp-preload-sizes.mdmarkdown1.0 KB
references/support-topics/next-route-handler-get-cache-defaults.mdmarkdown1.0 KB
references/support-topics/next-script-third-party-strategy.mdmarkdown1.0 KB
references/support-topics/nextjs-version-cache-semantics.mdmarkdown996 B
references/support-topics/not-found-catchall-request-waste.mdmarkdown1.2 KB
references/support-topics/nuxt-route-rules-cache-isr.mdmarkdown1.2 KB
references/support-topics/observability-events-cost-attribution.mdmarkdown1.1 KB
references/support-topics/post-response-work-waituntil.mdmarkdown1009 B
references/support-topics/route-error-durable-offload.mdmarkdown1.3 KB
references/support-topics/route-error-runtime-limits.mdmarkdown988 B
references/support-topics/runtime-cache-reusable-data.mdmarkdown1.2 KB
references/support-topics/sveltekit-isr-prerender-safety.mdmarkdown1.1 KB
references/support-topics/sveltekit-split-cold-start-tradeoff.mdmarkdown1.0 KB
references/support-topics/usage-spike-triage.mdmarkdown1018 B
references/support-topics/use-cache-date-stamp-isr-write-amplifier.mdmarkdown1.2 KB
references/support-topics/use-cache-remote-shared-origin-data.mdmarkdown1.1 KB
references/support-topics/workflow-resumable-stream-routes.mdmarkdown1.2 KB
references/verification.mdmarkdown8.8 KB
references/voice.mdmarkdown3.6 KB
scripts/budget-summary.mjsscript2.0 KB
scripts/build-docs.mjsexecutablescript3.3 KB
scripts/check-citations.mjsscript3.4 KB
scripts/check-docs-fresh.mjsexecutablescript3.8 KB
scripts/collect-signals.mjsexecutablescript21.1 KB
scripts/collect-sub-agent-outputs.mjsscript9.9 KB
scripts/deep-dive.mjsexecutablescript12.0 KB
scripts/gate-investigations.mjsexecutablescript6.2 KB
scripts/merge-signals.mjsscript6.2 KB
scripts/prepare-investigation-brief.mjsscript7.9 KB
scripts/reconcile-candidates.mjsscript2.4 KB
scripts/render-report.mjsscript17.0 KB
scripts/scan-codebase.mjsexecutablescript11.3 KB
scripts/verify-and-regen.mjsscript14.9 KB
scripts/verify-finding.mjsexecutablescript698 B

lib/reconcile-candidates.mjs

View on GitHub
// Deterministic post-deep-dive reconciliation.
//
// Runs after metrics deep-dive and before investigation briefs. Its job is to
// prevent weak candidates from consuming investigator budget when the
// follow-up metric evidence already disproves or reframes the gate hypothesis.

const SLOW_ROUTE_P95_THRESHOLD_MS = 500;
const ERROR_RATE_DOMINATES_THRESHOLD = 0.5;
const DEPLOYMENT_OUTLIER_MULTIPLE = 2;
const DEPLOYMENT_OUTLIER_MIN_MS = 1000;
const ROUTE_ERROR_CONFIRMATION_RATIO = 0.1;
const UNCACHED_HEALTHY_HIT_RATE = 0.9;
const UNCACHED_MIN_GET_SHARE = 0.2;
const ISR_WRITE_FLOOR = 100;
const ISR_WRITE_READ_RATIO_THRESHOLD = 0.5;

const SCANNER_ONLY_KINDS = new Set([
  'cache_header_gap',
  'image_optimization',
  'rendering_candidate',
]);

export function reconcileInvestigation(investigation, { gate = null } = {}) {
  if (!investigation || typeof investigation !== 'object') {
    throw new TypeError('reconcileInvestigation investigation must be an object');
  }

  const preResolvedRecords = [];
  const reconciliation = {
    droppedBeforeInvestigation: 0,
    reasons: {},
  };

  const reconcilePool = (pool, group) => {
    if (!Array.isArray(pool)) return [];
    const kept = [];
    for (let i = 0; i < pool.length; i++) {
      const candidate = pool[i];
      const decision = reconcileCandidate(candidate, { group, index: i, gate });
      if (decision.keep) {
        kept.push(candidate);
        continue;
      }
      reconciliation.droppedBeforeInvestigation++;
      reconciliation.reasons[decision.reasonCode] = (reconciliation.reasons[decision.reasonCode] ?? 0) + 1;
      preResolvedRecords.push(decision.record);
    }
    return kept;
  };

  const priorPreResolved = Array.isArray(investigation.preResolvedRecords)
    ? investigation.preResolvedRecords
    : [];

  return {
    ...investigation,
    toLaunch: reconcilePool(investigation.toLaunch, 'toLaunch'),
    platform: reconcilePool(investigation.platform, 'platform'),
    preResolvedRecords: [...priorPreResolved, ...preResolvedRecords],
    reconciliation: {
      ...(investigation.reconciliation ?? {}),
      ...reconciliation,
    },
  };
}

export function reconcileCandidate(candidate, ctx = {}) {
  if (!candidate || typeof candidate !== 'object') return { keep: true };

  const scannerOnly = scannerOnlyDecision(candidate, ctx);
  if (scannerOnly) return scannerOnly;

  if (candidate.kind === 'slow_route') {
    const errorDecision = slowRouteErrorDecision(candidate, ctx);
    if (errorDecision) return errorDecision;

    const mismatchDecision = slowRouteMetricMismatchDecision(candidate, ctx);
    if (mismatchDecision) return mismatchDecision;

    const regressionDecision = deploymentRegressionDecision(candidate, ctx);
    if (regressionDecision) return regressionDecision;
  }

  if (candidate.kind === 'route_errors') {
    const mismatchDecision = routeErrorsMetricMismatchDecision(candidate, ctx);
    if (mismatchDecision) return mismatchDecision;
  }

  if (candidate.kind === 'uncached_route') {
    const cacheDecision = uncachedRouteCacheDecision(candidate, ctx);
    if (cacheDecision) return cacheDecision;
    const methodDecision = uncachedRouteMethodDecision(candidate, ctx);
    if (methodDecision) return methodDecision;
  }

  if (candidate.kind === 'isr_overrevalidation') {
    const isrDecision = isrOverrevalidationDecision(candidate, ctx);
    if (isrDecision) return isrDecision;
  }

  return { keep: true };
}

function scannerOnlyDecision(candidate, ctx) {
  if (!SCANNER_ONLY_KINDS.has(candidate.kind)) return null;
  if (candidate.o11ySignal !== 'scanner-only') return null;
  return dropWithObservation(candidate, ctx, {
    reasonCode: 'scanner_only_no_metric',
    reason: 'Static scanner found a possible optimization, but no Vercel metric tied traffic or cost to this target.',
    observation: {
      kind: 'scanner_only_no_metric',
      summary: `${targetLabel(candidate)} has a static scanner finding, but no route-level Vercel metric signal.`,
      evidence: `gate signal=${candidate.o11ySignal}`,
      suggestedAction: 'Do not ship a recommendation from this finding unless a Vercel metric shows material traffic, cost, or latency for the same target.',
    },
  });
}

function slowRouteMetricMismatchDecision(candidate, ctx) {
  const p95 = numberAt(candidate, ['evidence', 'deepDive', 'latency', 'p95']);
  if (p95 == null) return null;
  if (p95 >= SLOW_ROUTE_P95_THRESHOLD_MS) return null;
  return dropWithObservation(candidate, ctx, {
    reasonCode: 'metric_mismatch',
    reason: `Deep-dive p95 (${formatMs(p95)}) is below the slow-route threshold, so the broad gate did not survive follow-up verification.`,
    observation: {
      kind: 'metric_mismatch',
      summary: `${targetLabel(candidate)} was flagged as slow in the broad pass, but follow-up p95 is below threshold.`,
      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.latency.p95=${formatMs(p95)}`,
      suggestedAction: 'Skip code investigation for this run. Re-check only if the broad and follow-up windows converge in a later run.',
    },
  });
}

function slowRouteErrorDecision(candidate, ctx) {
  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'statusDistribution']);
  if (rows.length === 0) return null;
  let total = 0;
  let errors = 0;
  for (const row of rows) {
    const value = numberValue(row?.value);
    if (value == null) continue;
    total += value;
    if (/^5/.test(String(row.http_status ?? ''))) errors += value;
  }
  if (total <= 0) return null;
  const rate = errors / total;
  if (rate <= ERROR_RATE_DOMINATES_THRESHOLD) return null;
  return dropWithObservation(candidate, ctx, {
    reasonCode: 'error_storm',
    reason: `Function-level 5xx responses dominate this route (${formatPct(rate)}), so this is a reliability finding rather than a slow-route finding.`,
    observation: {
      kind: 'error_storm',
      summary: `${targetLabel(candidate)} latency is dominated by function-level 5xx responses.`,
      evidence: `deepDive.statusDistribution: ${formatInteger(errors)} 5xx of ${formatInteger(total)} function invocations (${formatPct(rate)})`,
      suggestedAction: 'Investigate as route_errors with runtime logs and error classification before making performance recommendations.',
    },
  });
}

function deploymentRegressionDecision(candidate, ctx) {
  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'perDeployment'])
    .filter((row) => row && typeof row.deployment_id === 'string' && numberValue(row.value) != null)
    .map((row) => ({ deploymentId: row.deployment_id, p95: numberValue(row.value) }))
    .sort((a, b) => b.p95 - a.p95);

  if (rows.length < 3) return null;
  const [worst, second] = rows;
  if (!worst || !second || worst.p95 < DEPLOYMENT_OUTLIER_MIN_MS) return null;
  if (worst.p95 < second.p95 * DEPLOYMENT_OUTLIER_MULTIPLE) return null;

  return dropWithObservation(candidate, ctx, {
    reasonCode: 'deployment_regression',
    reason: `One deployment is a large latency outlier (${worst.deploymentId} at ${formatMs(worst.p95)}), so the next action is regression triage rather than generic code optimization.`,
    observation: {
      kind: 'deployment_regression',
      summary: `${targetLabel(candidate)} p95 is concentrated in one deployment.`,
      evidence: `${worst.deploymentId} p95=${formatMs(worst.p95)} vs next highest ${second.deploymentId} p95=${formatMs(second.p95)}`,
      suggestedAction: 'Compare the outlier deployment against the prior deployment and inspect runtime logs before recommending a code-level performance change.',
    },
  });
}

function routeErrorsMetricMismatchDecision(candidate, ctx) {
  const broadErrors = numberAt(candidate, ['evidence', 'count']) ?? parseSignalNumber(candidate.o11ySignal, 'errs');
  if (broadErrors == null || broadErrors < 1000) return null;
  const rows = [
    ...arrayAt(candidate, ['evidence', 'deepDive', 'errorStatusPattern']),
    ...arrayAt(candidate, ['evidence', 'deepDive', 'errorsByDeployment']),
  ];
  if (rows.length === 0) return null;
  let confirmed5xx = 0;
  for (const row of rows) {
    if (!/^5\d\d$/.test(String(row?.http_status ?? ''))) continue;
    const value = numberValue(row?.value);
    if (value != null) confirmed5xx += value;
  }
  // errorStatusPattern and errorsByDeployment can both be present; avoid
  // double-count inflation by taking the lower non-zero route-level view when available.
  const statusRows = arrayAt(candidate, ['evidence', 'deepDive', 'errorStatusPattern']);
  const status5xx = sumRows(statusRows, (row) => /^5\d\d$/.test(String(row?.http_status ?? '')));
  if (status5xx > 0) confirmed5xx = status5xx;
  if (confirmed5xx >= broadErrors * ROUTE_ERROR_CONFIRMATION_RATIO) return null;
  return dropWithObservation(candidate, ctx, {
    reasonCode: 'metric_mismatch',
    reason: `Deep-dive 5xx volume (${formatInteger(confirmed5xx)}) does not confirm the broad route_errors gate (${formatInteger(broadErrors)}).`,
    observation: {
      kind: 'metric_mismatch',
      summary: `${targetLabel(candidate)} was flagged for 5xx errors, but follow-up status data did not confirm the volume.`,
      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.confirmed5xx=${formatInteger(confirmed5xx)}`,
      suggestedAction: 'Skip code recommendations from this run. Re-run with refreshed status metrics or runtime logs if the route is still suspected.',
    },
  });
}

function uncachedRouteCacheDecision(candidate, ctx) {
  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'cacheBreakdown']);
  if (rows.length === 0) return null;
  const total = sumRows(rows);
  if (total <= 0) return null;
  const hits = sumRows(rows, (row) => ['HIT', 'STALE'].includes(String(row?.cache_result ?? '').toUpperCase()));
  const hitRate = hits / total;
  if (hitRate < UNCACHED_HEALTHY_HIT_RATE) return null;
  return dropWithObservation(candidate, ctx, {
    reasonCode: 'metric_mismatch',
    reason: `Deep-dive cache hit rate (${formatPct(hitRate)}) is already healthy, so the uncached-route gate did not survive follow-up verification.`,
    observation: {
      kind: 'metric_mismatch',
      summary: `${targetLabel(candidate)} was flagged as low-cache, but follow-up cache data is already healthy.`,
      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.cacheHitRate=${formatPct(hitRate)}`,
      suggestedAction: 'Skip cache recommendations for this candidate unless a later run shows sustained MISS/BYPASS traffic.',
    },
  });
}

function uncachedRouteMethodDecision(candidate, ctx) {
  const rows = arrayAt(candidate, ['evidence', 'deepDive', 'methodDistribution']);
  if (rows.length === 0) return null;
  const total = sumRows(rows);
  if (total <= 0) return null;
  const gets = sumRows(rows, (row) => String(row?.request_method ?? '').toUpperCase() === 'GET');
  const getShare = gets / total;
  if (getShare >= UNCACHED_MIN_GET_SHARE) return null;
  return dropWithObservation(candidate, ctx, {
    reasonCode: 'protocol_mismatch',
    reason: `Deep-dive GET share (${formatPct(getShare)}) is below the cacheable-route floor, so this is not a good shared-cache candidate.`,
    observation: {
      kind: 'protocol_mismatch',
      summary: `${targetLabel(candidate)} is not GET-heavy enough for a shared-cache recommendation.`,
      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.getShare=${formatPct(getShare)}`,
      suggestedAction: 'Do not recommend CDN caching for this route from aggregate traffic alone. Investigate write-path cost only if another metric gate fires.',
    },
  });
}

function isrOverrevalidationDecision(candidate, ctx) {
  const writeRows = arrayAt(candidate, ['evidence', 'deepDive', 'writePattern']);
  const readRows = arrayAt(candidate, ['evidence', 'deepDive', 'readPattern']);
  if (writeRows.length === 0 && readRows.length === 0) return null;
  const writes = sumRows(writeRows);
  const reads = sumRows(readRows);
  const ratio = reads > 0 ? writes / reads : (writes > 0 ? Infinity : 0);
  if (reads <= 0) {
    return dropWithObservation(candidate, ctx, {
      reasonCode: 'metric_mismatch',
      reason: 'Deep-dive ISR read units were not present, so the write/read over-revalidation signal was not confirmed.',
      observation: {
        kind: 'metric_mismatch',
        summary: `${targetLabel(candidate)} was flagged for ISR over-revalidation, but follow-up ISR read data was empty.`,
        evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${formatInteger(writes)}; deepDive.isrReads=${formatInteger(reads)}`,
        suggestedAction: 'Skip ISR recommendations for this candidate unless a later run confirms both ISR writes and reads for the same route.',
      },
    });
  }
  if (writes >= ISR_WRITE_FLOOR && ratio > ISR_WRITE_READ_RATIO_THRESHOLD) return null;
  const ratioLabel = ratio === Infinity ? 'Infinity' : ratio.toFixed(2);
  return dropWithObservation(candidate, ctx, {
    reasonCode: 'metric_mismatch',
    reason: `Deep-dive ISR writes per read (${ratioLabel}) no longer crosses the over-revalidation threshold.`,
    observation: {
      kind: 'metric_mismatch',
      summary: `${targetLabel(candidate)} was flagged for ISR over-revalidation, but follow-up ISR data did not confirm it.`,
      evidence: `${candidate.o11ySignal ?? 'gate signal unavailable'}; deepDive.isrWrites=${formatInteger(writes)}; deepDive.isrReads=${formatInteger(reads)}; ratio=${ratioLabel}`,
      suggestedAction: 'Skip ISR recommendations for this candidate unless a later run shows sustained write amplification.',
    },
  });
}

function dropWithObservation(candidate, ctx, { reasonCode, reason, observation }) {
  return {
    keep: false,
    reasonCode,
    record: {
      abstain: true,
      candidateRef: candidateRefFor(candidate),
      reason,
      observation,
      reconciliation: {
        droppedBeforeInvestigation: true,
        reasonCode,
        group: ctx.group ?? null,
        index: Number.isInteger(ctx.index) ? ctx.index : null,
      },
    },
  };
}

export function candidateRefFor(candidate, files = candidate?.files) {
  if (!candidate || typeof candidate !== 'object') return 'unknown:<unknown>';
  const target = candidate.route
    ?? candidate.hostname
    ?? (Array.isArray(files) && files.length > 0 ? `<account>#${files[0]}` : '<account>');
  return `${candidate.kind ?? 'unknown'}:${target}`;
}

function targetLabel(candidate) {
  return candidate.route ?? candidate.hostname ?? candidate.files?.[0] ?? 'account-level target';
}

function arrayAt(obj, path) {
  let cur = obj;
  for (const p of path) cur = cur?.[p];
  return Array.isArray(cur) ? cur : [];
}

function numberAt(obj, path) {
  let cur = obj;
  for (const p of path) cur = cur?.[p];
  return numberValue(cur);
}

function numberValue(value) {
  return typeof value === 'number' && Number.isFinite(value) ? value : null;
}

function sumRows(rows, predicate = () => true) {
  if (!Array.isArray(rows)) return 0;
  let total = 0;
  for (const row of rows) {
    if (!predicate(row)) continue;
    const value = numberValue(row?.value);
    if (value != null) total += value;
  }
  return total;
}

function parseSignalNumber(signal, key) {
  if (typeof signal !== 'string') return null;
  const re = new RegExp(`(?:^|,)${key}=([\\d,.]+)`);
  const m = signal.match(re);
  if (!m) return null;
  const n = Number(m[1].replace(/,/g, ''));
  return Number.isFinite(n) ? n : null;
}

function formatMs(value) {
  const n = numberValue(value);
  if (n == null) return String(value);
  return `${Math.round(n)}ms`;
}

function formatPct(value) {
  const n = numberValue(value);
  if (n == null) return String(value);
  return `${(n * 100).toFixed(n >= 0.1 ? 1 : 2)}%`;
}

function formatInteger(value) {
  const n = numberValue(value);
  if (n == null) return String(value);
  return Math.round(n).toLocaleString('en-US');
}
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall