# Expansion Prompt — docs/generated/tests bundles

You are being asked to **expand** an existing test bundle —
`docs/generated/tests/<bundle-key>/` — because a nightly coverage measurement
ranked it as under-covering its `coverage_targets`. The expansion loop
exists so that doc-anchored testing deepens in the areas where it is
visibly thin.

## The hard rule

You receive **no source-line information**. You do not see uncovered
lines, file diffs, percentages, or any data about which branches of
`slangc` are unexecuted. The operator gives you only:

- the bundle name,
- the bundle's `README.md` and existing `.slang` files,
- the bundle's `source_doc`, and
- the per-section prompt + `_common.md`.

The reason for this restriction: if a test were written against a
source line we observed to be uncovered, that test would codify
implementation rather than specification, and the suite's value (every
test maps to a documented claim) would erode. See
`docs/generated/tests/_meta/prompts/_common.md` for the full statement of this
contract.

## What to do

1. **Re-read the source doc carefully.** Do not skim. Look for
   behavioral claims you can find evidence for in the doc but that the
   existing bundle does not test (or tests only superficially).
   Examples of claims worth catching on a re-read:
   - implicit corollaries of a documented rule (e.g. "X is permitted
     only when Y" implies a negative test for "Y absent");
   - explicit examples in the doc that the bundle did not turn into a
     test;
   - error / diagnostic claims (e.g. "this produces error E1234")
     that are not covered;
   - target-specific behavior the doc enumerates (HLSL vs SPIR-V vs
     CUDA emit) where the bundle only tests one target;
   - parameter-shape variations the doc mentions (scalar / vector /
     matrix / array; precision modes; capability gates).

2. **Cross-check the README.md `## Functional coverage` table.** If a claim row's
   `Tests` cell is thinner than peer claims under the same anchor, that
   is a strong signal of where to expand. If the doc supports a claim
   the table does not yet describe, add a new row for it (one row per
   unique claim — never duplicate).

3. **Add new `.slang` files** to the bundle, following the
   `//META` block contract in `_common.md`. Mark every new test with:

   ```
   //META: intent=expansion
   ```

   Every new test must declare at least one matcher
   (`filecheck=NAME` / `filecheck-buffer=NAME` / `diag=NAME`) and
   carry at least one matching `// NAME:` pattern (or the FileCheck
   variants `NAME-DAG:` / `NAME-NEXT:` / etc.). Lint rejects tests
   that run but verify nothing. **Verify locally before commit** with
   `regenerate.py verify <bundle>` (see the `## Verify before
   committing` section in `_common.md` for the contract). Tests
   targeting backends your runtime doesn't have (`-target dxil`,
   `-target dx12`, GPU-runtime execution) come back as `ignored`;
   that's fine — commit them and CI validates. Tests that come back
   as `FAILED` must be fixed before commit.

4. **Do not modify existing tests.** Bootstrap tests are stable. If
   you find a flaw in an existing test, write the finding into
   `README.md` under `## Bootstrap test issues observed` and let the
   review/remediation loop handle it.

5. **If the doc legitimately does not describe the under-tested
   behavior**, the right output is **not** a synthesized test. The
   right output is a new **row** in the `## Doc gaps observed` table
   in `README.md`, classified per the controlled `Kind` vocabulary
   in `_common.md`. Doc gaps are a first-class output of the
   expansion loop — they are aggregated by `regenerate.py doc-gaps`
   and fed back into the doc-regeneration workflow. Write the
   **Suggested addition** cell as an actionable instruction so the
   doc-regen agent can act on it verbatim.

## Update README.md

After adding new tests:

- Bump `generated_at` and `model` in the front-matter.
- Recompute `watched_paths_digest` and `source_doc_digest` only if the
  source side has actually changed since the bundle was last produced.
- Add new rows to the **Coverage** table — one row per unique claim
  (matching the new test's `//META: purpose=...`), preserving the sort
  order (by anchor, then by claim). If a new test shares an identical
  purpose with an existing claim row, append its filename to that
  row's Tests cell instead of creating a duplicate row.
- Add rows to the **Doc gaps observed** table for anything you turned
  away from. Use the controlled `Kind` vocabulary from `_common.md`
  and write the **Suggested addition** cell as an actionable
  instruction.

## Caps

The manifest's `size_cap_files` is a soft cap. If an expansion would
push the bundle past the cap, prioritize:

1. negative / diagnostic tests for claims that have only positive
   tests;
2. additional targets for claims that are currently tested on only one
   target;
3. additional parameter shapes (vector/matrix/array) for claims that
   are currently tested only on scalars.

If you must cut, cut depth before breadth: it is more valuable to have
one test per claim than three tests for one claim and none for the
next.

## Verify

Run, in order:

```bash
python3 docs/generated/tests/_meta/regenerate.py lint <bundle>
python3 docs/generated/tests/_meta/regenerate.py verify <bundle>
python3 docs/generated/tests/_meta/regenerate.py mark-fresh <bundle> --model <your-id>
```

`verify` runs `slang-test` against the bundle and reports
pass / ignored / FAILED counts. Every FAILED test must be fixed
before `mark-fresh`. Tests reported as `ignored` (e.g. `-target
dxil` with no DXC, GPU-runtime tests with no driver) are fine to
commit — CI nightly validates them.

Fix any lint errors by re-reading the source doc, not by adjusting the
tests to silence the linter.
