Explain Lading Config

explain-lading-config

Explain what a lading regression test config does, grounded in lading source code.

Quick Start

# 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:

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.