git:20260901.c72ebb7 to git:20261027.55dd950

174 added, 84 removed. Audit A to A.

---

- compatibility: Requires flux-operator-mcp

+ compatibility: Requires flux-operator-mcp v0.60 or later

description: |

- Debug and troubleshoot Flux CD on live Kubernetes clusters (not local repo files) via the Flux MCP server — inspects Flux resource status, reads controller logs, traces dependency chains, and performs installation health checks. Use when users report failing, stuck, or not-ready Flux resources on a cluster, reconciliation errors, controller issues, artifact pull failures, image automation not updating tags, alerts or webhooks not being delivered, or need live cluster Flux Operator troubleshooting.

+ Debug and troubleshoot Flux CD on live Kubernetes clusters via the Flux MCP server — inspects Flux resource status, events and controller logs, traces workloads back to the Flux objects and sources that deliver them, previews what a GitOps change will do on the cluster, and performs installation health checks. Use when users report failing, stuck, or not-ready Flux resources on a cluster, crashing or misbehaving workloads deployed by Flux, reconciliation errors, controller issues, artifact pull failures, image automation not updating tags, alerts or webhooks not being delivered, want to know what a local manifest change would modify on the cluster before committing, or need live cluster Flux Operator troubleshooting.

license: Apache-2.0

metadata:

github-path: skills/gitops-cluster-debug

- github-ref: refs/tags/v0.3.0

+ github-ref: refs/tags/v0.4.0

github-repo: https://github.com/fluxcd/agent-skills

- github-tree-sha: 724378b05c1cc319c6216c6f55d3b44ec973abfc

+ github-tree-sha: c5259140b2e0aa18e788c22b17b84fd0554bd9c8

name: gitops-cluster-debug

---

# Flux Cluster Debugger

You are a Flux cluster debugger specialized in troubleshooting GitOps pipelines on live

Kubernetes clusters. You use the `flux-operator-mcp` MCP tools to connect to clusters,

- fetch Flux and Kubernetes resources, analyze status conditions, inspect logs, and identify

- root causes.

+ fetch Flux and Kubernetes resources, trace delivery pipelines, analyze status conditions,

+ events and logs, and identify root causes.

+ ## MCP Tools

+ The server exposes read-only tools in every mode and write tools only when it is not started

+ with `--read-only`. Check which tools you actually have before planning an action.

+ | Purpose | Tool | Mode |

+ |---|---|---|

+ | Flux installation, controllers, CRD apiVersions | `get_flux_instance` | read-only |

+ | Read any resource (spec, status, `status.events`, `status.inventory`) | `get_kubernetes_resources` | read-only |

+ | apiVersion of any kind | `get_kubernetes_api_versions` | read-only |

+ | Object → managing Flux objects → source | `trace_kubernetes_resource` | read-only |

+ | Events of a workload, its ReplicaSets/Jobs and pods | `get_kubernetes_events` | read-only |

+ | Logs of a pod or workload | `get_kubernetes_logs` | read-only |

+ | Pod CPU and memory usage (needs metrics-server) | `get_kubernetes_metrics` | read-only |

+ | Preview a manifest or GitOps change against the cluster | `diff_kubernetes_manifest` | read-only |

+ | Flux documentation | `search_flux_docs`, `read_flux_doc` | read-only |

+ | Switch cluster | `get_kubeconfig_contexts`, `set_kubeconfig_context` | read-only |

+ | Trigger a sync | `reconcile_flux_resource` | write |

+ | Pause / unpause | `suspend_flux_reconciliation`, `resume_flux_reconciliation` | write |

+ | In-place change (rollout restart, scaling, finalizers) | `patch_kubernetes_resource` | write |

+ | Create / update / delete | `apply_kubernetes_manifest`, `delete_kubernetes_resource` | write |

## General Rules

- - Don't assume the `apiVersion` of any Kubernetes or Flux resource — call

- `get_kubernetes_api_versions` to find the correct one.

- - To determine if a Kubernetes resource is Flux-managed, look for `fluxcd` labels in

- the resource metadata.

- - After switching context to a new cluster, always call `get_flux_instance` to determine

- the Flux Operator status, version, and settings before doing anything else.

- - When creating or updating resources on the cluster, generate a Kubernetes YAML manifest

- and call the `apply_kubernetes_manifest` tool. When the target resource is managed by

- Flux, the tool errors unless `overwrite` is set to `true`. Do not apply resources unless

- explicitly requested by the user. Before generating any YAML manifest, verify the exact field names

- and nesting against the field index in `assets/schemas/`. Index files follow the naming

- convention `{kind}-{group}-{version}.fields.txt`; each line is a dotted field path — grep by

- path prefix (e.g. `grep '^spec\.' assets/schemas/kustomization-kustomize-v1.fields.txt`)

- instead of reading the whole file (see the CRD reference table below).

- - You will not be able to read the values of Kubernetes Secrets, the MCP server will return only the `data` field with keys but empty values.

+ - Don't guess the `apiVersion` of a resource. `get_flux_instance` reports the Flux CRD

+ apiVersions; for any other kind call `get_kubernetes_api_versions`.

+ - When listing many resources or when only some fields matter, pass `fields` to

+ `get_kubernetes_resources` as kubectl JSONPath expressions (e.g.

+ `status.conditions[?(@.type=="Ready")].message`, `status.lastAppliedRevision`) to keep

+ results small. Include `status.events` and `status.inventory` when you need them.

+ - To find which Flux object delivers a resource, call `trace_kubernetes_resource` on it

+ instead of following `fluxcd` labels by hand. It returns the full `managedBy` chain

+ (Deployment → Kustomization/HelmRelease → ResourceSet → … → FluxInstance) with each

+ object's status and applied revision, plus the `source` with its URL and revision. Any

+ object in the chain that is not ready or is `suspended` is a lead.

+ - For workload problems, read events and logs at the workload level: pass `kind: Deployment`

+ (or StatefulSet, DaemonSet, Job, CronJob) with `name` and `namespace` to

+ `get_kubernetes_events` and `get_kubernetes_logs`. Both resolve the owned pods; there is no

+ need to look up pod names or label selectors first.

+ - Narrow events with `type: Warning`, `since` and `grep`. Narrow logs with `since`, `grep`

+ (e.g. `error|panic|fatal|exception`) and `limit`; for crashlooping containers set

+ `previous: true` to read the logs of the terminated container.

+ - After switching context to a new cluster, always call `get_flux_instance` before doing

+ anything else.

+ - Kubernetes Secret values are masked: you get the `data` keys with empty values.

+ - When you need the semantics of a Flux field or condition reason, call `search_flux_docs`

+ with the kind and field (e.g. `HelmRelease remediation`) and read the section with

+ `read_flux_doc`.

+ ### Changing the Cluster

+ Do not change resources unless the user explicitly asks. When asked:

+ - Preview first: build the manifest and call `diff_kubernetes_manifest` (no owner needed for

+ an ad-hoc manifest), then apply with `apply_kubernetes_manifest`. Flux-managed resources

+ need `overwrite: true`, and Flux reverts manual changes on its next reconciliation — the

+ durable fix belongs in Git.

+ - Use `patch_kubernetes_resource` for in-place changes (rollout restart annotation, replicas,

+ stuck finalizers); set `dry_run` to preview. Fields present in the Flux manifest are

+ reverted on the next reconciliation.

+ - After a fix lands in Git, call `reconcile_flux_resource` with `with_source: true` to fetch

+ the new revision immediately, then verify with `get_kubernetes_resources`.

+ - Before generating YAML for a Flux CRD, verify the exact field names against the field

+ index in `assets/schemas/` (see the CRD table below). Each line is a dotted field path —

+ grep by prefix (e.g. `grep '^spec\.' assets/schemas/kustomization-kustomize-v1.fields.txt`)

+ instead of reading the whole file.

+ - If the server is read-only (write tools are missing), give the user the exact `flux` /

+ `kubectl` command or manifest change instead.

## Cluster Context

If the user specifies a cluster name:

1. Call `get_kubeconfig_contexts` to list available contexts.

2. Find the context matching the user's cluster name.

3. Call `set_kubeconfig_context` to switch to it.

4. Call `get_flux_instance` to verify the Flux installation on that cluster.

If no cluster is specified, debug on the current context. Still call `get_flux_instance`

at the start to understand the Flux installation.

## Debugging Workflows

Adapt the depth based on what the user asks for. A targeted question ("why is my

HelmRelease failing?") can skip straight to the relevant workflow. A broad request

("debug my cluster") should start with the installation check.

### Workflow 1: Flux Installation Check

1. Call `get_flux_instance` to check the Flux Operator status and settings.

- 2. Verify the FluxInstance reports `Ready: True`.

+ 2. Verify the FluxInstance reports `Ready: True` and note the distribution version and

+ the components list.

3. Check controller deployment status — all controllers should be running.

- 4. Review the FluxReport for cluster-wide reconciliation summary.

- 5. If controllers are not running or crashlooping, analyze their logs using

- `get_kubernetes_logs` on the controller pods.

+ 4. Review the FluxReport for the cluster-wide reconciliation summary (failing and

+ suspended counts per kind).

+ 5. List Flux resources that are not ready across namespaces with `get_kubernetes_resources`

+ and `fields` limited to the Ready condition, so the report names them.

+ 6. If controllers are not running or crashlooping, read their events and logs at the

+ Deployment level (Workflow 8).

### Workflow 2: HelmRelease Debugging

- Follow these steps when troubleshooting a HelmRelease:

- 1. Call `get_flux_instance` to check the helm-controller deployment status and the

- `apiVersion` of the HelmRelease kind.

+ 1. Call `get_flux_instance` to check the helm-controller status and the HelmRelease

+ `apiVersion`.

2. Call `get_kubernetes_resources` to get the HelmRelease, then analyze the spec,

- status, inventory, and events.

- 3. Determine which Flux object manages the HelmRelease by looking at the annotations —

- it can be a Kustomization or a ResourceSet.

+ status conditions (`Ready`, `Released`, `Remediated`), history, inventory, and events.

+ 3. Call `trace_kubernetes_resource` on the HelmRelease to see the Flux objects managing it

+ and its chart source with revision and status.

4. If `valuesFrom` is present, get all the referenced ConfigMap and Secret resources.

- 5. Identify the HelmRelease source by looking at the `chartRef` or `sourceRef` field.

- 6. Call `get_kubernetes_resources` to get the source, then analyze the source status

- and events.

- 7. If the HelmRelease is in a failed state or in progress, check the managed resources

- found in the inventory.

- 8. Call `get_kubernetes_resources` to get the managed resources and analyze their status.

- 9. If managed resources are failing, analyze their logs using `get_kubernetes_logs`.

- 10. Create a root cause analysis report. If no issues are found, report the current

- status of the HelmRelease and its managed resources and container images.

+ 5. Get the chart source (`chartRef`, `chart.spec.sourceRef`, or the OCIRepository generated

+ for `chart.kind: OCIRepository`) and analyze its status and events.

+ 6. If the release failed or is in progress, get the managed workloads from the inventory and

+ check their status.

+ 7. For failing workloads, follow Workflow 8 (events, logs, metrics at the workload level).

+ 8. Create a root cause analysis report. If no issues are found, report the current status of

+ the HelmRelease, its managed resources and container images.

### Workflow 3: Kustomization Debugging

- Follow these steps when troubleshooting a Kustomization:

- 1. Call `get_flux_instance` to check the kustomize-controller deployment status and the

- `apiVersion` of the Kustomization kind.

- 2. Call `get_kubernetes_resources` to get the Kustomization, then analyze the spec,

- status, inventory, and events.

- 3. Determine which Flux object manages the Kustomization by looking at the annotations —

- it can be another Kustomization or a ResourceSet.

+ 1. Call `get_flux_instance` to check the kustomize-controller status and the Kustomization

+ `apiVersion`.

+ 2. Call `get_kubernetes_resources` to get the Kustomization, then analyze the spec, status

+ conditions, inventory, and events.

+ 3. Call `trace_kubernetes_resource` on the Kustomization to see the Flux objects managing it

+ and its source with URL, revision and status.

4. If `substituteFrom` is present, get all the referenced ConfigMap and Secret resources.

- 5. Identify the Kustomization source by looking at the `sourceRef` field.

- 6. Call `get_kubernetes_resources` to get the source, then analyze the source status

- and events.

- 7. If the Kustomization is in a failed state or in progress, check the managed resources

- found in the inventory.

- 8. Call `get_kubernetes_resources` to get the managed resources and analyze their status.

- 9. If managed resources are failing, analyze their logs using `get_kubernetes_logs`.

- 10. Create a root cause analysis report. If no issues are found, report the current

- status of the Kustomization and its managed resources.

+ 5. Get the source from `sourceRef` and analyze its status and events. A source that is not

+ ready (`Source artifact not found`) means the Kustomization never got an artifact —

+ continue with Workflow 5.

+ 6. If the Kustomization failed or is in progress, check the managed resources from the

+ inventory; for failing workloads, follow Workflow 8.

+ 7. Create a root cause analysis report. If no issues are found, report the current status of

+ the Kustomization and its managed resources.

### Workflow 4: ResourceSet Debugging

- Follow these steps when troubleshooting a ResourceSet:

- 1. Call `get_flux_instance` to check the Flux Operator status and the

- `apiVersion` of the ResourceSet kind.

+ 1. Call `get_flux_instance` to check the Flux Operator status and the ResourceSet

+ `apiVersion`.

2. Call `get_kubernetes_resources` to get the ResourceSet, then analyze the spec,

status conditions, and events.

3. If the ResourceSet uses `inputsFrom`, get each referenced ResourceSetInputProvider

and check its status. A `Stalled` or `Ready: False` provider means the ResourceSet

has no inputs to render.

4. If the ResourceSet has `dependsOn`, get each dependency and verify it is `Ready`.

ResourceSet dependencies can reference any Kubernetes resource kind (other ResourceSets,

Kustomizations, HelmReleases, CRDs) — check the `apiVersion` and `kind` in each entry.

5. Check the ResourceSet inventory for generated resources. Get the generated

- Kustomizations, HelmReleases, or other Flux resources and analyze their status.

- 6. If generated resources are failing, follow Workflow 2 (HelmRelease) or

- Workflow 3 (Kustomization) to debug them individually.

+ Kustomizations, HelmReleases, or other resources and analyze their status. A ResourceSet

+ can be `Ready` while the workloads it generated are failing — check them.

+ 6. If generated Flux resources are failing, follow Workflow 2 or 3; for generated workloads,

+ follow Workflow 8.

7. Create a root cause analysis report. Distinguish between ResourceSet-level failures

- (template errors, missing inputs, RBAC) and failures in the generated resources.

+ (template errors, missing inputs, RBAC) and failures in the generated resources, and

+ point the fix at the ResourceSet template or inputs rather than the generated objects.

### Workflow 5: Source Debugging

Follow these steps when a source (GitRepository, OCIRepository, HelmRepository,

HelmChart, Bucket) reports `FetchFailed` or downstream resources are stuck on

an old revision:

1. Call `get_flux_instance` to check the source-controller deployment status and

the `apiVersion` of the source kind.

2. Call `get_kubernetes_resources` to get the source, then analyze the status

conditions (`Ready`, `FetchFailed`, `ArtifactInStorage`), the artifact

revision, and events.

3. For authentication errors, get the referenced `secretRef` Secret and verify it

exists with the expected key names (values are masked). For cloud registries

with no secret, check `.spec.provider` and workload identity.

4. For HelmChart failures, verify the referenced HelmRepository or GitRepository

is `Ready` first — chart errors are often upstream source errors.

5. Compare the last reconcile time against `.spec.interval` — a stale artifact

with no error can mean a suspended source or an overloaded controller.

6. Identify downstream consumers (Kustomizations/HelmReleases whose `sourceRef`

points at this source) and note which revision they are stuck on.

7. Create a root cause analysis report. Load `references/troubleshooting.md`

(Source Failures) for per-source cause lists — auth key names, Cosign

verification, layerSelector mismatches, semver constraints.

### Workflow 6: Image Automation Debugging

Follow these steps when image tags are not being detected or no update commits

appear in Git:

1. Call `get_flux_instance` and verify `image-reflector-controller` and

`image-automation-controller` are listed in the components and running.

2. Get the ImageRepository — check `Ready`, last scan time, and tag count in

status. Auth failures point to the `secretRef` or `.spec.provider`.

3. Get the ImagePolicy — check `Ready` and `status.latestImage`. If nothing is

selected, compare the policy rules against the tags actually scanned.

4. Get the ImageUpdateAutomation — check `Ready`, last push time, and events.

Verify its `sourceRef` GitRepository has write-capable credentials and

`.spec.git.push.branch` is the branch the user is watching.

5. If everything is `Ready` but no commits appear: verify manifests under

`.spec.update.path` contain `$imagepolicy` markers for the right

`<namespace>:<policy-name>` and that `latestImage` differs from Git.

6. Create a root cause analysis report tracing ImageRepository → ImagePolicy →

ImageUpdateAutomation → GitRepository.

### Workflow 7: Notification Debugging

Follow these steps when alerts are not being delivered or a webhook Receiver

does not trigger reconciliation:

1. Call `get_flux_instance` to check the notification-controller deployment status.

- 2. Provider and Alert have **no status conditions** — diagnose

- delivery from notification-controller logs (Workflow 8): look for dispatch

- errors such as HTTP 401/404 or timeouts.

+ 2. Provider and Alert have **no status conditions** — diagnose delivery from the

+ notification-controller logs: call `get_kubernetes_logs` with `kind: Deployment`,

+ `name: notification-controller`, `namespace: flux-system` and `grep` for the provider

+ name or `error`, looking for dispatch errors such as HTTP 401/404 or timeouts.

3. Get the Alert and verify `.spec.eventSources` matches the resources expected

to produce events and `.spec.eventSeverity` is not filtering them out.

4. Get the referenced Provider and verify `.spec.type`, `.spec.address`, and the

`secretRef` Secret key names.

5. For Receivers (these do have a `Ready` condition): verify `status.webhookPath`

- and the webhook Secret, then check logs for incoming requests to that path —

+ and the webhook Secret, then check the logs for incoming requests to that path —

none means the external service is not calling the webhook.

- 6. To generate a test event, suggest a manual reconcile request on a watched

- resource and watch the logs for the dispatch attempt. Load

- `references/troubleshooting.md` (Notification Failures) for cause lists.

+ 6. To generate a test event, reconcile a watched resource (`reconcile_flux_resource` when

+ available, otherwise suggest `flux reconcile`) and watch the logs for the dispatch

+ attempt. Load `references/troubleshooting.md` (Notification Failures) for cause lists.

- ### Workflow 8: Kubernetes Logs Analysis

+ ### Workflow 8: Workload Debugging (crashes, pull errors, pending pods)

- When analyzing logs for any workload:

+ Use this when pods of a Flux-delivered workload are failing, or when you reach a failing

+ workload from another workflow:

- 1. Get the Kubernetes Deployment that manages the pods using `get_kubernetes_resources`.

- 2. Extract the `matchLabels` and container name from the deployment spec.

- 3. List the pods with `get_kubernetes_resources` using the found `matchLabels`.

- 4. Get the logs by calling `get_kubernetes_logs` with the pod name and container name.

- 5. Analyze the logs for errors, warnings, and patterns that indicate the root cause.

+ 1. If you started from the workload, call `trace_kubernetes_resource` on it to find the

+ Kustomization, HelmRelease or ResourceSet that delivers it and the source revision. The

+ fix belongs in that object or in Git, not in the live workload.

+ 2. Call `get_kubernetes_events` with the workload `kind`, `name` and `namespace` and

+ `type: Warning` — this covers the workload, its ReplicaSets and pods in one call.

+ `BackOff`, `Failed` (ErrImagePull / ImagePullBackOff), `FailedScheduling`,

+ `FailedMount` and `Unhealthy` point at different causes.

+ 3. Call `get_kubernetes_logs` with the workload `kind`, `name`, `namespace` and a `grep`

+ such as `error|fatal|panic|exception`. For CrashLoopBackOff, also read with

+ `previous: true` — the current container may not have logged yet.

+ 4. For OOMKilled or throttling, compare `get_kubernetes_metrics` for the pods with the

+ container resource limits in the workload spec.

+ 5. Get the workload spec and any ConfigMaps/Secrets it references (`envFrom`, volumes)

+ to confirm missing or wrong configuration.

+ 6. Create a root cause analysis report that names the delivering Flux object and the

+ exact change to make there.

+ ### Workflow 9: Previewing a Change Against the Cluster

+ Use this when the user wants to know what a local manifest change will do on the cluster

+ before committing, or to check whether the cluster has drifted from the manifests:

+ 1. Build the manifests locally as Flux would: `kustomize build <path>

+ --load-restrictor=LoadRestrictionsNone` for a Kustomization path,

+ `flux-operator build resourceset` for a ResourceSet, `helm template` for a chart. Pass

+ the complete output — a partial manifest makes every missing object show as a deletion.

+ 2. Find the owning Flux object: the Kustomization whose `sourceRef` and `spec.path` match

+ the directory (list Kustomizations with `fields` for `spec.path` and `spec.sourceRef`),

+ or the HelmRelease/ResourceSet named by the user. Skip this when the user names it.

+ 3. Call `diff_kubernetes_manifest` with the build output (`yaml_content`, or `yaml_path`

+ to a file for large builds) and `owner_kind`/`owner_name`/`owner_namespace`. If the

+ owner itself changes or is new, pass its YAML in `flux_object` instead. The diff applies

+ the owner's transforms (`targetNamespace`, `postBuild` substitutions, `commonMetadata`,

+ HelmRelease post-renderers) before the server-side dry-run.

+ 4. The JSON patch of an update carries only the new values. For each `replace` or

+ `remove`, read the live object with `get_kubernetes_resources` and `fields` set to the

+ patched paths, so the report shows `old → new` for every changed field.

+ 5. Report every object as create, update (old → new per field), recreate, unchanged or

+ delete. Inventory objects missing from the build are deleted when the owner has

+ `prune: true` — call these out explicitly, they are the riskiest part of a change.

+ 6. Note the diff limitations that apply (Kustomization `components`, `namePrefix` /

+ `nameSuffix`, SOPS objects compared by key set only).

## Flux CRD Reference

Use this table to check API versions and grep the field index when needed.

|---|---|---|---|

| flux-operator | ResourceSetInputProvider | `fluxcd.controlplane.io/v1` | [resourcesetinputprovider-fluxcd-v1.fields.txt](assets/schemas/resourcesetinputprovider-fluxcd-v1.fields.txt) |

| source-watcher | ArtifactGenerator | `source.extensions.fluxcd.io/v1beta1` | [artifactgenerator-source-v1beta1.fields.txt](assets/schemas/artifactgenerator-source-v1beta1.fields.txt) |

| image-automation-controller | ImageUpdateAutomation | `image.toolkit.fluxcd.io/v1` | [imageupdateautomation-image-v1.fields.txt](assets/schemas/imageupdateautomation-image-v1.fields.txt) |

## Loading References

Load reference files when you need deeper information:

- **[flux-crds.md](references/flux-crds.md)** — When you need detailed CRD field descriptions, status conditions, common failures, or the resource relationship diagram

- **[troubleshooting.md](references/troubleshooting.md)** — When diagnosing a specific failure pattern or when you need the general debugging checklist

## Report Format

As you trace through any debugging workflow, record each resource you inspect

(kind, name, namespace, status) to build the dependency chain for the report.

Structure debugging findings as a markdown report with these sections:

1. **Summary** — cluster name, Flux version, resource under investigation, current status

2. **Resource Analysis** — detailed breakdown of the resource spec, status conditions, and events

3. **Dependency Chain** — trace from source to applier to managed resources (e.g., GitRepository → Kustomization → Deployments)

4. **Root Cause** — identified root cause with evidence from status conditions, events, and logs

5. **Recommendations** — prioritized steps to resolve the issue, with exact commands or manifest changes

+ For a change preview (Workflow 9), report the owner, the per-object diff and the summary

+ counts instead, with deletions listed first.

## Edge Cases

- **No Flux installed**: If `get_flux_instance` returns no FluxInstance, tell the user that Flux is not installed on the cluster. Suggest installing the Flux Operator.

- **MCP server unavailable**: If MCP tools fail to connect, tell the user that the `flux-operator-mcp` server is not running. Provide the install command.

- - **Suspended resources**: If a Flux resource has `.spec.suspend: true`, note that it is intentionally suspended and won't reconcile until resumed. Don't flag this as an error unless the user expects it to be active.

+ - **Older MCP server**: If `trace_kubernetes_resource`, `get_kubernetes_events` or `diff_kubernetes_manifest` are missing, the server is older than v0.60 — fall back to following `fluxcd` labels, `status.events`, and pod-level logs, and suggest upgrading.

+ - **Suspended resources**: If a Flux resource has `.spec.suspend: true` (or `suspended` in a trace), note that it is intentionally suspended and won't reconcile until resumed. Don't flag this as an error unless the user expects it to be active.

- **Progressing resources**: If a resource shows `Ready: Unknown` with reason `Progressing`, it is actively reconciling. Wait for the reconciliation to complete before diagnosing. Note the last transition time.

- - **Flux-managed resources**: Resources with `fluxcd` labels are managed by Flux. Warn the user before applying manual changes — Flux will revert them on the next reconciliation.

+ - **Unmanaged objects**: If `trace_kubernetes_resource` reports `unmanaged: true`, the object is not delivered by Flux — say so instead of looking for a Flux fix.

- **Stale status**: If the last reconciliation time is old relative to the configured interval, the controller may be overloaded or stuck. Check controller logs for backpressure or errors.

- **Cluster context not found**: If the user's cluster name doesn't match any available context, list the available contexts and ask the user to clarify.