cub-scout

cub-scout (umbrella router)

This skill is the cross-cutting entry point. It picks the right verb-grouped skill for a user's question and explains the cub-scout / cub boundary. For specific tasks, load the scenario skill directly.

When to use

• "Can cub-scout do X?" / "what can cub-scout observe / diagnose / compare?"
• "How does cub-scout differ from cub / kubectl / Argo / Flux?"
• "Should I use cub-scout or [other tool] for this?"
• Anything in this repo where the verb group isn't obvious from the prompt
• General capability-assistant or demo conversations

Do not load for

• A specific verb-grouped task — load the corresponding scout-* skill directly:
  • scout-observe — see what's running
  • scout-diagnose — interpret + recommend
  • scout-compare — intended vs actual
  • scout-attribute — provenance of field values
  • scout-ingest — adopt existing config into ConfigHub with preview first
  • scout-govern — connected governance signals
  • scout-mcp — MCP gateway + context-pack
  • scout-verify — typed, fingerprinted evidence receipts
• ConfigHub authoring or any mutating workflow — load confighub/confighub-skills skills (cub-mutate, cub-apply, etc.)
• Live cluster mutation — cub-scout never mutates; route to kubectl (user driven) or a cub skill

Capability map (verb groups → skills)

Group	Skill	Status
Observe	scout-observe	shipped (batch 1)
Diagnose	scout-diagnose	shipped (batch 1)
Compare	scout-compare	shipped (batch 1)
Attribute	scout-attribute	shipped (batch 1)
Govern	scout-govern	shipped (batch 2)
Adopt Existing Config	scout-ingest	shipped (batch 2)
Integrate	scout-mcp	shipped (batch 2)
Verify	scout-verify	shipped (batch 2, consuming the #446 receipt capability)

See skills/README.md for the full plan including controller observer skills (observe-argocd, observe-flux, observe-sveltos, observe-modelplane, observe-helm, observe-crossplane, observe-kro), workflow scenario skills (triage-unhealthy-workload, investigate-drift, audit-fleet-conformance, etc.), and shared references.

Pilot–cub-scout integration scenarios (#444)

The consumer-side complement: same cub-scout verbs framed around Pilot (the acceptance judge) rendering verdicts from cub-scout's evidence. Load one of these instead of a scout-* skill when the user's prompt is shaped as "Pilot, decide ..." or "render the verdict ...". #444 is complete: 9 scenarios shipped across batches A and B.

Scenario	Skill	Pilot consumes	Pilot decides
Pre-deploy CD gate	pilot-cd-gate	compare source-truth --strategy <s> + optional receipt verify --fail-on any-non-pass	PASS / WATCH / ASK / BLOCK on the release
Fleet-wide conformance	pilot-fleet-conformance	compare three-way --view + per-resource source-truth + fleet outliers	Fleet verdict + per-resource breakdown
Drift classification	pilot-patch-and-drift	attribution evidence (cause / managerHint / gitSource / bindingSource)	revert / quarantine / accept-as-canonical / ASK
Real-time watch response	pilot-watch-alert-response	cub-scout watch / cub-scout bot event stream with --emit-receipt-on inline receipts (v2 #463)	Per-event PASS / WATCH / ASK / BLOCK
Incident close-out	pilot-incident-evidence	trace + explain + compare + bundle + history + audit + chained receipts (--input-attestation, v2 #463)	Incident verdict + immutable evidence pack
Rollback decision	pilot-rollback-decision	history + impact + per-candidate receipt verify --at-commit <sha> chained into chosen-target receipt	Rollback target SHA + safety verdict
Promotion gate	pilot-promotion-gate	compare three-way per variant + bindingSource graph diff + chained variant-A receipt	Cross-variant PASS / WATCH / ASK / BLOCK with diff reasons
Compliance audit	pilot-compliance-audit	scope-wide source-truth + scan + audit list + per-resource saved receipts	Compliance report (Compliant / with-caveats / Non-compliant / Insufficient-evidence) + fingerprinted evidence inventory
Release verification	pilot-release-verification	gitops status --with-confighub + compare three-way + history --since <deploy-time> + receipt evidence; summary.agreement and deliveryEvidence drive convergence signals	Post-deploy PASS / WATCH (wait) / BLOCK / ASK

Product value in one breath

cub scout observes and explains; it never decides. It is the read-only Kubernetes and GitOps observer — it surfaces evidence about ownership, health, drift, and provenance, but it never mutates the cluster and never makes authority calls about what should be true. ConfigHub (driven by cub) is the authority; cub-scout is the witness.

cub scout is the preferred documented form. In this repo, use ./cub-scout ... for exact local commands.

Tool boundaries

Use cub scout for

• Observe — doctor, map, trace, tree, scan, graph, snapshot, watch, bot, status
• Diagnose — explain, debug, suggest-remedy, patterns, gitops status
• Compare — compare drift, compare three-way, compare source-truth, compare <kind>/<name>
• Attribute — read cause / managerHint / gitSource / bindingSource on compare and explain JSON
• Adopt Existing Config (preview first) — import --dry-run, import --from-bundle, import --git-path, import parse-repo, import argocd, import cluster-aggregator
• Govern (connected) — history, impact, fleet outliers, summary, views resolve, audit list, bundle inspect/diff/timeline, catalog list
• Integrate — mcp serve, context-pack, bot
• Verify — receipt verify / show / validate / list (typed, fingerprinted evidence; receipt verify <kind>/<name> --with-confighub can freeze object-correlated delivery evidence under predicate.evidence.deliveryEvidence)

Use cub for

• ConfigHub intended-state workflows
• spaces, units, targets, workers
• cub variant upload (load already-rendered resources as units)
• cub link list / get (the data feed for cub-scout's connected attribution layer)
• Any mutation — cub is the writer side of the triad

Do not blur these

• cub-scout import --git-path is a local structure / import-preview flow — it does not render manifests or upload to ConfigHub
• cub variant upload ingests already-rendered resources and writes them as units — it renders nothing, and cub gitops discover / cub gitops import no longer exist (removed from cub 2026-07-25, #573)
• SDK renderers are an implementation detail for cub, not an implied cub-scout feature
• Attribution evidence on compare / explain JSON is read-only enrichment — never implies a write

High-signal shipped capabilities

• Attribution layer (#435 — A1+A1.5+A2 in #437, C1 in #438, C2 in #439, stage B in #440): cause + managerHint + gitSource{repoUrl,revision,path,file,line} + bindingSource on every field mismatch. See scout-attribute.
• Source-truth contract (#393 + #418): compare source-truth with Phase 1 + Phase 2 strategies (9 total).
• Views integration (#391): views resolve, views open, views project --with-reality, compare three-way --view.
• doctor / explain with --presentation and --hint-mode.
• MCP gateway (mcp serve): standalone + connected tool sets, including gitops_status for GitOps delivery and controller-coverage evidence.
• ConfigHub delivery evidence: gitops status --with-confighub, doctor --with-confighub, map activity --with-confighub, trace --with-confighub, explain --with-confighub, and single-resource receipt verify --with-confighub add bounded release history, unit events, live-status freshness, and event-consumer health. doctor adds a scope-level delivery rollup, map activity renders the evidence as timeline rows, and receipts freeze object-correlated snapshots as fingerprint-covered supporting evidence.
• Controller-family coverage: gitops status emits controllerCoverage[] for Flux, Argo CD, ConfigHub, Sveltos, and Modelplane so absence and RBAC/API omissions stay distinguishable.
• Stage B back-resolution (#440): compare three-way --source-path <local-checkout> populates gitSource.file:line for raw YAML manifests.
• Receipt capability (#446 — v1 complete; #454 + #455 + #456): typed, fingerprinted, immutable evidence artifacts wrapping cub-scout evidence into an in-toto Statement v1 envelope. Three predicates: applied-matches-spec, source-truth-pass, no-manual-edits-since. verify / show / validate / list + local store with immutable canonical filenames. See scout-verify.

Read first (for capability-assistant work)

1. AI-README-FIRST.md — cold-start guide, current shipped capabilities, current open queue
2. HANDOVER.md — latest execution snapshot
3. README.md § "Capability Map" — the eight verb groups
4. docs/reference/commands.md — exact command surface
5. docs/reference/json-contracts.md — JSON shapes
6. references/capability-assistant.md (in this directory) — the original capability-assistant profile, kept for back-compatibility

Verification rule

Do not invent command surfaces.

Verify from local help before claiming capability. help <command> is the auto-approved form. <command> --help is not: a wildcard grant for it would also admit import -y --audit-reason --help, where --help is the flag's value and the import runs:

./cub-scout --help
./cub-scout help doctor
./cub-scout help explain
./cub-scout help compare three-way
./cub-scout help compare source-truth
./cub-scout help import
./cub-scout help views
./cub-scout help mcp serve

When the workflow crosses into ConfigHub:

cub variant upload --help
cub k8s --help
cub link --help
cub link list --help

Safety rule (read-only triad lock — #410 / #428)

• cub-scout is cluster read-only by default
• connected import writes inventory / state to ConfigHub, not cluster manifests
• prefer preview or dry-run paths first
• attribution evidence is enrichment, never mutation
• suggest-remedy describes a fix; it does not apply it (the executor was removed in #428)

Authoring guidance for new skills

When adding skills under skills/, follow:

• skills/SKILL_TEMPLATE.md — the canonical template (cub-scout, read-only variant)
• The read-only-triad invariant — no mutating patterns in allowed-tools, ever
• Standalone-first worked examples; connected-mode is the enrichment
• CI-tool-neutral wording — no GitHub Actions / GitLab CI / Jenkins-specific syntax committed