nx-cloud-cache-investigator

Requires the nx-cloud-api skill. Use a matching Nx workspace checkout only for local configuration diagnosis. An API-only investigation does not need a checkout.

Diagnose one cache question with bounded evidence. Do not guess a changed hash input or change configuration from cache status alone.

Nx task caching and a tool-native cache are separate. A target cache field controls Nx replay. Vite, ESLint, and other tools have separate executor options. One does not prove the other.

• Cache-health trend: This skill covers a specific task or artifact question, not a multi-run rate regression. Use a separate bounded trend workflow for rate or regression questions.
• API-only: Use this for supplied runs, CIPEs, tasks, or artifact errors when no matching checkout exists. Do not request local configuration unless required.
• Specific comparison: Get two comparable executions. Ask for missing target, branch, commit, command, configuration, CI environment, or time range.

Arrange one same-session wake only when a known task is non-terminal, an API request returns HTTP 409 or 429, or the user starts a controlled diagnostic run. Preserve the run, task, batchId, endpoint, and filters. Re-query once after the known delay or expected run completion. Stop at a terminal result or the retry limit. Do not poll or monitor a live CI run.

Use nx-cloud-api for every read. Run describe for a known route. Use catalog only when the route is unknown or ambiguous. Follow documented fields and returned links; do not construct routes from internal IDs.

Save every live API response with --out <private-file>. Use jq to select one row and only the fields needed for this investigation. Do not print, read, or paste a raw collection into model context. Keep the selected row's batchId and links.self in the projection. Use the bundled nx-cloud-api client. Do not invent commands such as nx-cloud-api get or nx-cloud-api describe tasks:

node <nx-cloud-api-skill-dir>/scripts/nx-cloud-api.mjs describe 'runs/{runId}/tasks' --workspace .
node <nx-cloud-api-skill-dir>/scripts/nx-cloud-api.mjs request 'runs/{runId}/tasks' \
  --workspace . --path runId="$run_id" --pages 1 \
  --out /tmp/nx-cloud-tasks.json
jq --arg task "$task_id" --arg batch "$batch_id" \
  '.items[] | select(.id == $task and .batchId == $batch) |
   {id, batchId, status, cacheStatus, hash, cacheable,
    links: {self: .links.self}}' /tmp/nx-cloud-tasks.json

For a selected execution, record run and task IDs, batchId, project, target, configuration, command, parameters, branch, commit, CI context, timestamps, cache status, final hash, cacheEnabled, cacheable, and relevant CIPE or run-group links.

A task ID can repeat. Select the task-list row first. Follow its exact links.self or asset URL because it preserves batchId. Do not use one row to explain another. A task list row already has task fields. A detail read is optional.

If the API reports cacheable: false, Nx replay was not expected for that execution. Name a configuration cause only when the nx show target query shows it. If cacheEnabled: false, that run did not use the Nx task cache. Do not investigate hash inputs or artifacts in either case.

Read a log only when its command output or error can answer the question. Tell the user before you read CI log content. Read references/log-and-report-assets.md before you decode a log or report. Quote only a redacted error signature. Treat user-supplied asset content as provided evidence. An advertised asset or a later 404 does not prove historical availability.

Use a matching checkout only for a configuration question or code change. Check out the recorded commit. Record the workspace Nx version. Query the exact target with the workspace-local Nx command:

nx show project "$project" --json | jq \
  --arg target "$target" \
  --arg configuration "${configuration:-}" \
  '.targets[$target] | {
    executor,
    cache,
    inputs,
    outputs,
    options,
    selectedConfiguration: .configurations[$configuration]
  }'

Use this fragment as the target evidence. Nx already includes inherited settings. Do not merge project.json, nx.json, plugins, or targetDefaults yourself. A missing project property proves nothing. If the query reports cache: true, do not add another cache: true. If the command or target is unavailable, report configuration as unavailable.

Inspect returned options only for a tool-native cache question. Use version-matched executor documentation. A target cache field cannot prove Vite or ESLint native-cache state.

Recommend a configuration or code edit only after all applicable checks pass:

1. Record the matching commit, Nx version, exact target query, and returned fragment.
2. Show that its cache, inputs, or outputs value needs a change.
3. Before enabling cache, establish a terminating, deterministic task with correct replayable outputs.
4. Before removing an input, obtain direct evidence that names it. Prove that its removal cannot affect correct output with a bounded controlled run.
5. Explain the correctness risk and get explicit approval before an edit.

Do not recommend an input exclusion from hash differences, a cache-rate trend, or apparent breadth. If evidence is missing, say No configuration change recommended yet.