explain-lading-config

# explain-lading-config Explain what a lading regression test config does, grounded in lading source code. ## Quick Start ```bash # 1. Verify the lading checkout exists and is on a known branch bash .agents/skills/explain-lading-config/scripts/validate-lading-checkout.sh # 2. Resolve $ARGUMENTS to a lading.yaml path (exact/substring/glob/path) bash .agents/skills/explain-lading-config/scripts/resolve-lading-config.sh "$ARGUMENTS" # 3. Read the resolved file, then ground every field in lading source # (see references/source-reading.md for the full strategy). # 4. Write up the explanation following references/explanation-template.md. ``` Defaults must be resolved to concrete values, not function names. Full workflow below. ## Step 1: Validate lading checkout Run `.agents/skills/explain-lading-config/scripts/validate-lading-checkout.sh`. - Exit 0: script prints the current branch on stdout. If it is not `main`, warn the user that explanations are grounded in a non-main branch, then continue. - Exit non-zero: the script prints a suggested `git clone` command on stderr. Relay that to the user and stop. Override the checkout location with `LADING_DIR` if needed. ## Step 2: Determine target file Use `.agents/skills/explain-lading-config/scripts/resolve-lading-config.sh` to avoid ad-hoc matching. The script enumerates experiments under `test/regression/cases/` (active) and `test/regression/x-disabled-cases/` (disabled). Each experiment is a `<case>/lading/lading.yaml` addressed by its case-directory name; disabled rows are flagged with a trailing `(disabled)` column in the listing. `ebpf/cases/` (split-mode) and `ebpf/config-only/cases/` are intentionally out of scope; if a user asks about one, tell them this skill doesn't cover it yet. The script handles path-like inputs, substring case names, and shell globs (`*`, `?`). **If `$ARGUMENTS` is provided:** run `resolve-lading-config.sh "$ARGUMENTS"`. - Exit 0: stdout is the resolved absolute path; read it. - Exit 3 (ambiguous): stderr lists candidates. - **≤ 4 candidates:** use `AskUserQuestion` to pick one, then read that path. - **> 4 candidates** (a broad substring like `i` can match 20+): do not try to force them into `AskUserQuestion`. Print the experiment names as a short bulleted list and ask the user to narrow the query and re-invoke `/explain-lading-config <name>`. - Exit 2 (not found): stderr may include "did you mean?" suggestions — if present, offer the suggestions to the user via `AskUserQuestion` (up to 4 options) or as a short list; if not, relay the error and stop. - Exit 4 (wrong repo): the script is being run from outside the agent repo. Relay the error verbatim and stop — the user needs to `cd` into the repo. **If the resolved path contains `/x-disabled-cases/`**, flag this explicitly in the explanation — the experiment exists on disk but is not currently executed by SMP. Otherwise a user may assume it's live. **Reading very large configs:** multi-sender configs (e.g. `uds_dogstatsd_20mb_12k_contexts_20_senders`, ~870 lines) are usually block-copies of one template with a few fields varying (typically only `seed`). Before a full `Read`, check size and duplication: ```bash wc -l <path> # scale check grep -c '^ - ' <path> # top-level list entries yq '.generator | length' <path> 2>/dev/null # if yq is present ``` For highly-duplicated configs, `Read` only the first block (plus the blackhole/target_metrics sections) and report the generator as "N identical copies, seed differs" instead of walking every block. Spot- check one later block to confirm uniformity. **If `$ARGUMENTS` is omitted:** run `resolve-lading-config.sh` with no argument. It emits `<experiment>\t<path>` lines for every discovered config. Print the experiment names as a plain bulleted list to the user (preserving the `(disabled)` markers) and ask them to type the name (or re-invoke the skill with `/explain-lading-config <name>`). ## Step 3: Read the lading codebase for context Before explaining, read the lading source files that ground the populated sections of the config. The detailed strategy (variant-to-module mapping, grep-before-Read invariants, fallback for renamed files) lives in `references/source-reading.md` — read it now. ## Step 4: Explain the config Write the explanation following the structure in `references/explanation-template.md` (generator summary, aggregate load, blackhole sinks, target metrics, source references). Read it now.