antithesis-k8s-onboarding-assistance

What this skill does

# Antithesis K8s Onboarding Assistance

## Purpose and Goal

Help customers running on Kubernetes minimize their production manifests down to a form `antithesis-setup` can use to construct an Antithesis test environment. The output is a structured analysis report — not modified YAML.

Success means:

- `antithesis/scratchbook/k8s-minimization.md` is a stable, reviewable report describing the components, dependencies, stub strategies, and decisions setup will need to construct the test environment for a k8s-based SUT
- `antithesis/scratchbook/k8s-minimization-work/working.md` captures the live decision history across passes — including reversals, defaulted decisions, and open assumptions
- The customer has either (a) finished work on this skill with the final report ready for setup, or (b) an escalation packet ready to share with their Antithesis engagement team

This skill applies only to customers running on Kubernetes. Customers using Docker Compose directly skip this skill and go straight from `antithesis-research` to `antithesis-setup`.

Note: `antithesis-setup` currently builds Docker Compose harnesses. Setup-side k8s support is a separate effort. When that effort lands, this skill's final report becomes setup's input for k8s customers; until then, the report is a structured handoff to the Antithesis engagement team rather than a direct setup input. The skill produces the same artifact regardless of which path the consumer takes downstream.

## Prerequisites and Scoping

Before this skill can do useful work, it needs scope information about what's being tested: SUT identity, test boundary, and success criteria for the app running correctly.

Two ways to get that information:

- **Read it from a prior research artifact.** Look for `antithesis/scratchbook/sut-analysis.md`. If it exists, read the SUT identity from it.
- **Interview the customer.** Ask what they're testing. Capture SUT identity, test boundary, and success criteria from the conversation.

Either source is fine. The working file records the origin so it's clear later where the scope information came from.

If neither path produces enough scope to proceed (no `sut-analysis.md`, and the customer can't articulate scope), that's a blocker — not a workflow redirect. Explain that the skill needs to know what's being tested before it can do useful work, and offer the escalation packet path so the customer can loop in their Antithesis engagement team.

This skill collects substantial additional context regardless of where the scope information came from — the customer's k8s artifacts, ops contact, sensitive-data handling preferences, success criteria detail. Scope is the gate to start; intake supplies the rest.

This skill never runs `kubectl`, `helm`, `kustomize`, `docker`, `kind`, `k3d`, or any other cluster-touching command. Customers may run commands themselves and paste the output back; the skill reads pasted output but does not execute.

## Definitions and Concepts

- **SUT:** System under test (term inherited from `antithesis-research`)
- **Horizontal minimization:** Deciding which components in the customer's manifests are part of the test scope at all (SUT, dependency, or out-of-scope)
- **Vertical minimization:** For a component that is in scope, stripping platform/cloud/observability cruft so it can run in a single-node test environment
- **Single-node test environment:** Antithesis explores timelines deterministically against a small, fixed deployment. Multi-node distributed-system features (cross-node consensus, cluster autoscaling, real load balancers, network policies enforced by a CNI) don't add value in this environment — they add state space and non-determinism. "Single-node" doesn't mean Antithesis can't test distributed-system correctness; it means the test deployment runs as one Antithesis-managed environment, with multiple replicas or services co-located rather than spread across real nodes.
- **Working file:** Live, growing artifact across passes (`antithesis/scratchbook/k8s-minimization-work/working.md`)
- **Final report:** Stable snapshot of the working file's current state, generated when handoff readiness passes (`antithesis/scratchbook/k8s-minimization.md`)
- **Landmine:** A platform-layer construct that is commonly minimized away, with a known recipe (Istio, cert-manager, external-secrets, etc.)
- **Status field:** Each entry in the working file has a status of `Confirmed`, `Defaulted`, or `Open`. Handoff readiness fails if any `Open` entries remain.

## Documentation Grounding

Use the `antithesis-documentation` skill to ground Antithesis-specific terminology.

This skill does not have its own dedicated Antithesis documentation pages — it bridges between `antithesis-research` and `antithesis-setup`. For any Antithesis-domain concept (SUT, properties, scratchbook conventions, deployment topology), defer to those skills' documentation grounding.

## Core Principles

**No archaeology.** Default direction is minimize. The bar to keep something is "we have a reason to believe the app needs this." The bar to drop is "this looks like platform/cluster concerns." Optimize for rate-of-customers-reaching-success, not correctness-on-each-decision. The two error modes are not symmetric:

- *Drop something we shouldn't*: caught at setup or runtime, recoverable in minutes.
- *Ask too many archaeology questions*: customer gives up. Unrecoverable.

Lean toward the first.

**Defaults are aggressive; the customer always overrides; every decision is visible.** Record what was decided and why in the working file. The customer can scan it and push back on any decision without justifying themselves. Reversals are first-class — when a prior decision is overturned, show the reversal explicitly in history rather than silently rewriting.

**Skill never runs cluster commands.** This is non-negotiable. Customer's machine, customer's kubeconfig, customer's cluster — the skill describes commands and reads pasted output, never executes.

**Never tell the customer "no."** When the work hits a wall — ops unresponsive, a hard architectural problem, customer is stuck — produce an escalation packet for the Antithesis engagement team. Dead ends become warm handoffs.

**Fidelity vs. speed is a calibrated tradeoff, surfaced explicitly.** When applying a landmine default that has a meaningful fidelity impact (e.g., dropping Istio when the customer tests with Istio in prod), state the fidelity cost and let the customer choose. Don't silently optimize for speed when the customer cares about fidelity.

**Keep the customer in the loop on what's about to leave their environment.** When generating the escalation packet, prompt for sensitive data review before producing the document, even if the customer already gave a sensitive-data preference at intake. Different audience, different stakes.

## Skill Flow

Eight phases. On each invocation, read the working file first to determine where you are. The working file's frontmatter records `current_phase`, so you can resume cleanly across sessions.

1. **Confirm prerequisites.** Look for `sut-analysis.md` or interview the customer for research-equivalent scope. If neither path produces enough scope to proceed, treat as a blocker and offer the escalation packet path. (See *Phase Guidance → Confirm prerequisites*.)

2. **Greeting / expectation-setting.** First-contact only. Set the frame: multi-pass, aggressive cuts, fidelity-vs-speed tradeoff, customer can override, ops-questions are the work, escalation exists. (See *Phase Guidance → Greeting*.)

3. **Intake.** Conversational with internal checklist. Cover: sensitive-data handling first, then `helm`/`kustomize` rendering if needed, then ops contact, artifact form, customer comfort level, app success criteria. (See *Phase Guidance → Intake*.)

4. **Horizontal classification.** Classify each component as SUT / dep-real / dep-stub / out-of-scope. Built from research scope + call graph from manifests. (See `referenc