scout-diagnose

name	scout-diagnose
description	Use when the user wants cub-scout to INTERPRET what it sees and suggest a next step — the Diagnose verb group. Natural phrasing: "explain this Deployment", "why is this broken?", "what should I do about this?", "is this drift or just slow sync?", "what does this error mean?", "is there a known pattern for this?", "is my GitOps pipeline healthy?", "what events are firing on this Pod?", "give me a suggested remedy for this finding". Load whenever intent is explain / why / what-does-it-mean / what-should-I-do / interpret / diagnose / recommend / suggest-fix over a Kubernetes cluster or a scan finding. Do NOT load for: pure cluster inventory (use scout-observe), comparing intended vs running state at the field level (use scout-compare), field-level provenance (use scout-attribute), or actually applying a fix (cub-scout never mutates — route to cub or kubectl with the user driving).
phase	verify
allowed-tools	Bash(./cub-scout explain *) Bash(cub-scout explain *) Bash(cub scout explain *) Bash(./cub-scout debug *) Bash(cub-scout debug *) Bash(cub scout debug *) Bash(./cub-scout suggest-remedy *) Bash(cub-scout suggest-remedy *) Bash(cub scout suggest-remedy *) Bash(./cub-scout patterns *) Bash(cub-scout patterns *) Bash(cub scout patterns *) Bash(./cub-scout gitops status *) Bash(cub-scout gitops status *) Bash(cub scout gitops status *) Bash(kubectl get *) Bash(kubectl describe *) Bash(kubectl logs *) Bash(kubectl get events *) Bash(argocd app get *) Bash(flux get *)

scout-diagnose

The Diagnose verb group of cub-scout. Five commands that interpret what's in the cluster and produce next-step guidance — without applying any fix.

When to use

Explicit phrasings:

• "Explain this Deployment" / "what does this resource mean?"
• "Why is my Pod CrashLooping?" / "what's wrong with this StatefulSet?"
• "What should I do about this?" / "give me a remediation"
• "Is this drift, or just controller still syncing?"
• "Is there a known pattern that matches this?"
• "Is my GitOps pipeline healthy?" / "what's the state of Flux / Argo?"
• "Show me the recent events on this resource"
• "Suggest a remedy for this scan finding"

Implicit intents:

• The user has already seen something (via scout-observe) and wants to know why it looks that way
• The user wants a concrete next command to run, not just facts
• The user wants pattern-matching against known failure modes, not just raw cluster output

Do not load for

• Pure inventory ("show me what's running") — load scout-observe
• Comparing intended vs running state at the field level — load scout-compare
• Per-field provenance (which controller / which git file set this value) — load scout-attribute
• "Apply this fix" / "edit / patch / sync" — cub-scout never mutates. suggest-remedy describes a fix; it does not execute it. Route to cub, kubectl (user driven), or another tool

Standalone vs connected

• Standalone (cluster only): explain, debug, suggest-remedy, patterns, gitops status all work against your current kubectl context.
• Connected (cluster + cub auth login): explain adds ConfigHub deep-links to the unit / revision URLs the resource came from; three-way disagreement gets a dedicated section.
• Offline (file / bundle only): patterns detect --file <yaml> runs the pattern engine against a manifest; suggest-remedy works against scan findings without a live cluster.

Tool boundary

• Allowed (read-only): all five Diagnose verbs, plus kubectl get/describe/logs/get events, argocd app get, flux get. These are the read-only diagnostic surfaces the skill may invoke for context.
• Not allowed: kubectl apply/edit/patch/delete/exec, argocd app sync/refresh (as mutation), flux reconcile (mutating), cub * create/update/delete, any --dry-run=false carve-out.
• suggest-remedy is read-only: the original command was renamed from remedy in #428; the mutating executor was deleted. The command describes a fix that would resolve the finding — it does not run it. cub-scout no longer has a non-dry-run path.

The verb menu

Question	Verb	Notes
"Explain this one resource"	cub-scout explain <kind>/<name> -n <ns>	Plain-English ownership + lineage + health + drift + next steps. Supports --presentation human|ai|paired and --hint-mode default|beginner|operator.
"Walk me through a GitOps debug"	cub-scout debug	Guided wizard for the common failure modes
"Suggest a fix for this scan finding"	cub-scout suggest-remedy <finding-id>	Read-only — describes the patch, does not apply. Legacy remedy accepted as an alias.
"Match the cluster against known patterns"	cub-scout patterns detect / patterns explain / patterns list	The pattern engine. Works on cluster, file, or bundle.
"Is GitOps healthy?"	cub-scout gitops status	Pipeline health for Flux + Argo: stuck reconciles, source errors, applyset drift

All five verbs emit --format json for agents.

The loop

1. Identify intent. The user is starting from a symptom (broken resource, scan finding, slow sync) and wants an interpretation + a recommended next step.
2. Gather context. If the user names a specific resource, lead with cub-scout explain <kind>/<name> -n <ns>. If they have a scan finding ID, lead with cub-scout suggest-remedy <id>. If they're at "something feels off across the cluster", lead with cub-scout doctor (from scout-observe) and then drill in.
3. Read the structured hints. explain and doctor both emit nextSteps[] — each hint has an actionType (read-only / waiting / human-decision; mutating is rejected on emit) and a nextCommand. Use those hints to drive the next invocation.
4. Pattern-match if needed. If the symptom is well-known (CrashLoop, image pull error, kustomization unhealthy), cub-scout patterns detect produces a structured match against the 46 built-in patterns.
5. Hand off. When the diagnosis points at a change the user wants to make, refuse to act and route them: ConfigHub-authored fixes go to cub skills in confighub/confighub-skills; direct manifest fixes go to kubectl edit with the user driving; if the divergence might be drift vs reconciliation, route to scout-compare for the connected three-way view.

Worked example

User: "deploy/api in prod is CrashLooping. What's going on?"

Standalone mode (cluster only)

$ cub-scout explain deploy/api -n prod --hint-mode operator
Deployment/api in prod:
  Owner:        Argo CD (Application: payments-api, source: https://github.com/org/repo @ apps/prod/api)
  Source:       Git
  Deployed via: argocd-controller
  Health:       Degraded (1/3 replicas Ready)
  Risks:        CrashLoopBackOff on container "api" (3 restarts in last 5m)
  Drift:        Not checked (standalone mode)
  Notes:
    - Recent events: Warning BackOff (3x, 5m) kubectl: Back-off restarting failed container

Try next (read-only):
  → cub-scout patterns detect --resource Deployment/api -n prod
  → kubectl logs -n prod deploy/api --previous --tail=100

The user can follow the structured hints — both read-only — without ever needing to apply, edit, or sync.

Connected mode adds three-way disagreement detail

When cub auth login is set up, the same explain command also includes a THREE-WAY STATUS block:

THREE-WAY STATUS (connected)
  ConfigHub revision 42 → controller revision 42 → cluster revision 42 (agreed)
  Conclusion: not a drift problem. Investigate the workload itself.

This disambiguates "is this CrashLoop a workload bug, or is the controller still rolling out an old revision?" — connected mode tells you the revisions agree, so the failure is in the workload, not the GitOps loop.

For agents:

$ cub-scout explain deploy/api -n prod --format json | jq '.nextSteps[]'
{
  "actionType": "read-only",
  "reason": "CrashLoop suggests application-level failure, not drift; inspect logs",
  "nextCommand": "kubectl logs -n prod deploy/api --previous --tail=100",
  "nextSurface": "kubectl"
}

Output evidence

• Primary artifact: structured explanation JSON or human-readable ASCII
• nextSteps[] with actionType ∈ {read-only, waiting, human-decision}. Mutating actionType is rejected at every cub-scout emit point.
• Three-way disagreement section (connected mode only) when ConfigHub / controller / cluster disagree

References

• Capability map: README.md § Diagnose
• Command details: docs/reference/commands.md
• Phase-aware hint design: #367 (Argo phase hints), #370 (structured nextSteps)
• Triad lock (read-only suggest-remedy): #410 / #428

Constraints

• suggest-remedy describes; it does not apply. If a user asks to run the suggested fix, refuse and route them to the appropriate skill (cub for ConfigHub-authored changes; kubectl with the user driving for direct edits). The original remedy executor was deleted in #428.
• Hint actionType: mutating is structurally impossible — the emitter rejects it. Any "next step" from this skill is safe to read and follow without risk of accidental mutation.
• If the diagnosis is evidence-missing (no managedFields, no controller spec, no ConfigHub link), explain returns the evidence gap honestly rather than guessing. Don't synthesize a recommendation from absence.