Public-ready repository skill

Test suite composition

Composes owned checks into explicit, proportionate execution bundles with clear admission, check depth, prerequisites, cost, result meaning, and recovery. Applies when test discovery, selective CI, change-impact routing, shared setup, selective reruns, or cross-runner coordination becomes difficult.

What this produces

A discoverable route whose selected checks, inputs, environment, cost phases, side effects, outcomes, expansion events, and re-entry conditions are inspectable before execution.

Source and version

Repository path
.agents/skills/test-suite-composition/SKILL.md
Source revision
a5ed640bb0982044d46e6e874867eb8f0e760169
Source SHA-256
3294bc017695ec19aa212d696d7253a8793a20c4d7ba933585f5ac032344df11
Publication standing
Public ready

Included source files

Complete skill source

The Markdown below matches the exact source text. The format link above opens the file on its own.

---
name: test-suite-composition
description: Composes owned checks into explicit, proportionate execution bundles with clear admission, check depth, prerequisites, cost, result meaning, and recovery. Applies when test discovery, selective CI, change-impact routing, shared setup, selective reruns, or cross-runner coordination becomes difficult.
---

# Test suite composition

## Contract

- **What:** A source-owned map and executable composition of existing checks for a named receiving decision.
- **When:** A repository has overlapping commands, several runners, hidden prerequisites, uncertain blast radius, repeated unaffected work, or a slow lane whose expensive phase remains unclear.
- **Boundaries:** Domain owners retain expectations. Runner choice follows demonstrated capability. Required security, accessibility, integrity, publication, live-service, and budget gates remain explicit. Research predictions retain only the authority granted by their protocol.
- **Result:** A discoverable route whose selected checks, inputs, environment, cost phases, side effects, outcomes, expansion events, and re-entry conditions are inspectable before execution.

## Fit and attention

- **Useful when:** The fitting command is unclear to a cold collaborator, several aliases overlap, shared preparation dominates CI, helper duplication changes lifecycle behavior, or a campaign repeats evidence whose source identity remains valid.
- **Poor fit when:** One focused check already answers the question. Direct invocation remains the complete route.
- **Smallest useful dose:** One behavior family, its exact case or command population, and the existing runner that owns it.
- **Foregrounds:** Behavior ownership, discoverability, impact routing, phase cost, safe reuse, failure isolation, and proportional expansion.
- **May under-attend:** A source map establishes intended membership. Actual duration, flake rate, concurrency behavior, cache performance, and live acceptance require observations.
- **Interactions:** `evidence-bearing-test-design` owns an individual oracle. `cost-and-ownership-analysis` owns full-path cost and mutable-state boundaries. Browser, state, security, release, and research skills retain their distinct results.
- **Rest or release when:** The receiver can select, run, interpret, and resume the route with every obligation visible, or one direct command remains the smallest complete owner.

## Inputs, defaults, and output

Begin with source owners, current commands, supported runtimes, activation
settings, required receivers, observed phase timings, and the receiving change.
Use an existing manifest, README table, or runner configuration before adding a
new registry. Repeated selection work may justify a declarative catalog and a
thin plan or dispatch adapter. The adapter calls reviewed commands and leaves
their assertions with their current owners.

A composition record may carry:

- stable ID and behavior owner;
- command and argument vector;
- runtime and observation layer;
- source and dependency edges;
- prerequisites and environment identity;
- side effects and external receivers;
- artifact and checkpoint requirements;
- timeout and budget owner;
- expansion and release events; and
- result, recovery, and evidence scope.

Each field needs a consumer. Unknown cost remains unmeasured until an observed
run supplies the phase and denominator.

For selective CI, identify three choices separately: **admission** determines
whether a job starts, **depth** names the exact population it will execute,
and **preparation** supplies that population's runtime, build, browsers, and
services. Record the defaults for each choice and the owner who can change
them. Missing source or dependency information receives a conservative
affected-family route; missing execution authority receives a ready-to-run
plan with the held action named.

## Rules

### Rule: Organize by behavior owner and observation layer

Keep family meaning visible while distinguishing source/schema, unit,
integration, artifact, workflow, browser interaction, visual/media, carrier,
live receiver, and research evidence. These dimensions compose according to
the change and receiver; they form a routing lattice rather than a compulsory
staircase.

### Rule: Planning, discovery, execution, and acceptance stay distinct

A metadata plan establishes intended selection. Importing discovery establishes
the admitted test population and may execute module initialization. Runner
output establishes executed, failed, skipped, or cancelled cases. A named
receiver establishes acceptance. Record the effect actually observed at each
stage.

### Rule: A plan explains the selected population

Enumerate checks before expensive work when the runner supports plan-only
selection. Explain which changed owner or dependency reopened each check.
Unknown dependency edges receive owner review and a conservative affected-
family route. A shared dependency, cross-family contract, release candidate, or
explicit acceptance receiver supplies the expansion event for broader proof.

### Rule: Admission precedes expensive preparation

Evaluate optional job admission before allocating its runner and services when
the platform supports that boundary. Make manual run/skip choices explicit and
keep automatic triggers, repository activation settings, draft handling, and
required-check policy consistent. A skipped dispatch preserves an active run
whose evidence is still required. Selecting fewer cases is a depth decision;
withholding execution is an admission decision. Each has its own result.

### Rule: The smallest adequate route runs first

Use a focused source or unit check for a local behavior owner, add family
integration when an adapter or generated twin changes, add a browser when the
material behavior depends on a browser, and run the complete accepted suite
when shared closure or release acceptance makes it the smallest adequate
receiver. A full suite is a deliberate evidence route with its own cost and
result meaning.

### Rule: Reuse preserves independent meaning

Share environment setup, local serving, telemetry, byte capture, artifact
publication, and teardown where contracts match. Keep expected values and
source-owned assertions independent of the implementation being checked.
Migrate one caller at a time when lifecycle, network, or recovery policy differs.

One compatible job can install once, build once, and run several selected
checks against that source. Fresh test contexts, deterministic fixtures,
resource ownership, and cleanup preserve isolation inside the shared
environment. A reusable action shares instructions across jobs; its callers
still prepare their own runners. Cached dependencies accelerate preparation;
they carry no new behavior result.

### Rule: Equivalent selection is a migration condition

Before replacing a command, compare case identities, scenarios, modes,
fixtures, source closure, failure standing, artifacts, skips, and side effects.
Equal counts leave membership and meaning unresolved. Preserve a compatibility
or rollback route until the receiving owner accepts the new command.

### Rule: Phase ownership precedes optimization

Measure environment provisioning, test execution, artifact compilation,
publication, queueing, and cleanup separately. Optimize the phase that owns the
observed delay. A long browser job whose setup dominates receives an
environment route; a browser-execution phase that consumes its budget receives
family or state segmentation. Preserve the behavior population while changing
preparation.

### Rule: Reuse binds evidence identity

Reuse a checkpoint or artifact when its trusted case definition, source and
dependency identities, runtime, environment, observation contract, and required
artifacts still match. The checkpoint writer preserves earlier completed
evidence with its original scope when a later phase fails. Final validation and
telemetry precede publication. The owned teardown handler remains callable
after partial initialization; a hard cancellation records cleanup as
`incomplete` when that handler cannot finish.

### Rule: An investigation boundary leads to a phase decision

When a full job reaches its agreed ceiling, the suite owner reads the last
completed phase and the work still pending. Compare equivalent engine and
case populations, then choose the smallest preparation or execution change
that addresses the measured delay. A budget change goes back to its owner
with cold recovery cost, wall time, total runner time and the behavior the
extra time would establish.

### Rule: Results retain population and standing

Return separate counts or identities for source files, runtime cases, browser
launches, skipped cases, reused cases, and generated artifacts. Distinguish
executed pass, failure, skip, blocked, incomplete, cancelled, and reuse.
Treat a zero-match selector as a named outcome with an owner decision. When a
case is required to establish the selected claim, a skip leaves that route
`incomplete` and identifies the prerequisite or owner that can admit it.

### Rule: Hosted activation and prediction retain independent authority

Local composition leaves hosted workflow activation, Actions budget, live
receiver use, publication, and deployment with their named owners. A predictive
selection experiment binds its event, window, eligible population, reviewed
model or classifier, and outcome rule. Deterministic required checks continue
through their standing gates until a separately reviewed adoption decision
changes them.

## Operating sequence

1. **Inventory:** Classify maintained source, generated projections, retained examples, local experiments, and external receivers.
2. **Map:** Connect each check to its behavior owner, dependency edges, runner, prerequisites, cost phases, and evidence claim.
3. **Select:** Choose the smallest adequate composition and state the event that expands it.
4. **Plan:** Return admission, depth, exact IDs, commands, environment needs, side effects, holds, expected population, and result meanings before dispatch.
5. **Consolidate:** Reuse mechanics where ownership matches and preserve independent domain expectations.
6. **Exercise:** When authorized, compare membership and outcomes through one passing path and one consequential failure, interruption, or fallback path.
7. **Measure:** Separate preparation, execution, compilation, publication, and total elapsed time using a comparable source and population.
8. **Receive:** Preserve rollback and accepted evidence, return the bounded result, and update the single source-owned map.

## Decisive scenarios

### Scenario: A Python parser joins a browser family

- **Given:** Python validates exact authored bytes while Chromium observes rendered table behavior.
- **When:** The family receives a common composition.
- **Then:** Both runners and their distinct failure meanings remain visible; parser success stays separate from scroll, focus, and paint evidence.

### Scenario: A media lane approaches its time ceiling

- **Given:** Phase receipts show dependency preparation consumes most of the lane while browser behavior completes in seconds.
- **When:** The team considers decomposition, caching, or a prebuilt runner.
- **Then:** Preparation receives the first optimization, the media and browser population remains intact, and browser segmentation stays tied to measured browser-execution cost.

### Scenario: One command already serves the question

- **Given:** One focused command observes the changed behavior with a sufficient independent oracle.
- **When:** A repository-wide adapter is proposed for that single use.
- **Then:** The focused command remains the route until another consequential receiver demonstrates coordination value.

### Scenario: A valid checkpoint survives interruption

- **Given:** Case definition, dependencies, runtime, observation contract, and required artifacts still match.
- **When:** A campaign resumes after interruption.
- **Then:** The receipt identifies reused evidence and its original scope; new launches and checks describe only the additional work.

### Scenario: An optional run is explicitly skipped

- **Given:** A manual workflow exposes run/skip separately from focused/full selection.
- **When:** The operator chooses skip while an admitted release check remains active.
- **Then:** The optional job allocates no runner or service, preserves the active check, and reports withheld execution. Its successful platform conclusion supplies no new behavior evidence; release acceptance continues through the active receiver.

## Conditional context

Load [selective CI admission, check depth, and preparation reuse](references/selective-ci-admission-and-check-depth.md)
when run/skip controls, automatic activation, focused/full selection, combined
jobs, or browser choice changes the execution route. The receiving team’s delivery procedure owns execution and recovery.

Load [CI provisioning and runner efficiency](references/ci-provisioning-and-runner-efficiency.md)
when environment preparation, dependency transfer, runner image selection,
cache identity, or prebuilt tooling materially affects the lane. Load the
[runtime provisioning cards](references/runtime-provisioning-cards.md) when
Node, Python, browser, system-package, container, database, or release-history
identity changes the safe preparation and reuse route. Load the
receiving repository's own suite map and workflow policy for exact commands,
budgets, activation, and release gates.

## Recovery and re-entry

When a composition obscures failure meaning, changes population silently, or
requires a complete campaign for a local behavior, return to the owned focused
commands and refine the map. Re-enter after a new behavior family, shared
dependency, runtime, environment, hosted receiver, or release boundary changes
selection or result meaning.

## Completion

A cold collaborator can plan and interpret the selected route, including its
prerequisites, exact population, phase costs, fallback, partial outcomes, and
expansion event. Each behavior owner retains its checks and assertion meaning;
the composition evolves through observed cost or missed coverage as their
routing layer.