---
name: experimental-code-coverage-verification-prep
description: >-
  Prepares a Gerrit CL for code coverage verification try jobs. Adds dummy
  comments to trigger builds, optimizes builder configs by isolating test
  suites, and commits all changes.
---

# Prep Verification Build

This skill modifies workspace files to ensure LUCI builders run, isolates target
test suites in builder Starlark files for speed, and uploads a Work-In-Progress
(WIP) Gerrit CL. It is used to prepare both experimental branches with fixes and
clean baseline branches.

## When to Use This Skill

- After making potential configuration fixes and needing to run a verification
  build.
- To create a "Baseline" CL on a clean branch, with only the necessary
  modifications to trigger and speed up the build.

## Inputs (Read from scratch/triage_state.json)

This skill reads its primary inputs directly from `scratch/triage_state.json`.
The only dynamic selector passed in the subagent prompt is `role` (`"Control"`
vs. `"Fix"`):

- `target_files`: A list of file paths that need a dummy comment to ensure
  they are included in the build's affected files.
- `builders_of_concern`: A list of target builder names (e.g. `["linux-rel"]`).
  To locate the `.star` Starlark configuration file for each builder, reference
  [builder_star_map.json][star_map].
- `test_suites`: The test suite names to isolate in the builder
  configurations.
- `bug_id`: The issue ID for context in the CL description.
- `control_branch_name` / `fix_branch_name`: The git branch to check out. If
  `role` is `"Control"` (or `"control"`), check out `control_branch_name`. If
  `role` is `"Fix"` (or `"fix"`), check out `fix_branch_name`.

## Workflow

1. **Checkout Branch**:

   Read `scratch/triage_state.json` and check out `control_branch_name` (if
   `role` is `"Control"`) or `fix_branch_name` (if `role` is `"Fix"`).

   ```bash
   git checkout {{selected_branch_name}}
   ```

2. **Add Dummy Comments**:

   - Iterate through each file in `target_files` (from
     `scratch/triage_state.json`).
   - Append a unique dummy comment to each file (e.g.,
     `// Verification run for b/{{bug_id}}`).

   ```bash
   # Example for one file
   echo "// Verification run for b/{{bug_id}} $(date)" >> {{file_path}}
   ```

3. **Optimize Builder Configurations**:

   - For each builder in `builders_of_concern` and its `.star` file:
     - Locate the builder definition.
     - Modify the test suite declarations to *only* include the target suites
       from `test_suites` (from `scratch/triage_state.json`).
     - **Example Modification**: Change existing test bundles to:
       ```python
       # Example for a builder's test targets
       targets = targets.bundle(targets = {{test_suites}})
       ```
     - After modifying the `.star` file(s), regenerate configuration artifacts
       directly from the repository root:
       ```bash
       lucicfg generate infra/config/main.star
       ```
       This updates the underlying JSON build specifications.

4. **Commit Changes**:

   - Stage all modified tracked files in the workspace using `git add -u`. This
     stages the dummy comments and updated builder configurations while safely
     ignoring any untracked scratch files or local skills.

   ```bash
   git add -u
   ```

   - Create a commit using the structured naming format. Note that the commit
     title must explicitly state `(Control)` or `(Fix)` based on `role`. If
     `test_suites` contains multiple test suites, join their names or list them.
   - **Commit Message**:
     ```text
     Verify Code Coverage Change for {{test_suites}} ({{role}})

     This was generated by the Code Coverage Debugging Agent.

     Role: {{role}} Verification
     Target Files: {{ target_files }}

     {{ summary of applied GN/Starlark/recipe fixes or trimming }}

     Bug: {{bug_id}}
     ```

   ```bash
   git commit \
     -m "Verify Code Coverage Change for {{test_suites}} ({{role}})" \
     -m "This was generated by the Code Coverage Debugging Agent." \
     -m "Role: {{role}} Verification" \
     -m "Target Files: {{ target_files }}" \
     -m "{{ summary of applied GN/Starlark/recipe fixes or trimming }}" \
     -m "Bug: {{bug_id}}"
   ```

5. **Upload to Gerrit**:

   - Upload the CL as a Work-In-Progress (WIP).
   - Do **NOT** pass `--cq-dry-run` to the upload command.

   ```bash
   git cl upload -f --bypass-hooks -o wip
   ```

6. **Update State File**:

   - Update `scratch/triage_state.json`: write the uploaded CL URL into
     `control_cl` (if `role` is `"Control"`) or `fix_cl` (if `role` is `"Fix"`).

## Output

- The URL of the uploaded Gerrit CL.
- Confirmation that `scratch/triage_state.json` (`control_cl` or `fix_cl`) has
  been updated.

## References

- [lucicfg Reference Manual][lucicfg_ref]

[star_map]: ../experimental-cq-debugger/references/builder_star_map.json
[lucicfg_ref]: https://chromium.googlesource.com/infra/luci/luci-go/+/HEAD/lucicfg/doc/README.md