---
name: vnv-sprint-prep
description: V&V (Validation and Verification) sprint preparation — check cross-platform parity on the dev board, clone sprint stories to the V&V board, validate them against requirements and test cases, drive them through scenario review, and write the approved scenarios into TestRail as test cases.
disable-model-invocation: true
---

# /bc:vnv-sprint-prep — V&V Sprint Preparation

Walk a sprint's dev stories through the V&V team's pipeline: platform-parity check → clone to the V&V
board → validate against requirements and test cases → high-level scenarios → reviewer approval → TestRail
test cases.

The workflow is **resumable**. Run it once to start a sprint, then re-run it as the dev team answers your
questions and the reviewer approves your scenarios — each run picks up where the last left off and advances
only the tickets whose blocking condition has cleared.

**Plugin root:** two folders above this skill's base directory, which is `<plugin root>/skills/vnv-sprint-prep/`. Every file these instructions name — `howtos/…`, `providers/…`, `scripts/…`, `com.github.copilot/agents/…` — is a path from the plugin root, and so is every file those files name.

## Usage

```
/bc:vnv-sprint-prep                          # Dry run — report what would happen, write nothing
/bc:vnv-sprint-prep --apply                  # Perform the writes, after one batch confirmation per phase
/bc:vnv-sprint-prep --board <url>            # Use a different V&V board for this project, and save it
/bc:vnv-sprint-prep PROJ-123                 # Restrict the run to one story (and its platform counterpart)
```

## Arguments

The text the user typed after the command:

- **Scope** (optional): a story key to restrict the run to. Default: every story in the dev board's current sprint.
- **Flags**:
  - `--apply`: perform the writes. **Without it nothing is created, commented, or labelled** — the run reports the full plan and stops.
  - `--board <url>`: the V&V board link. Without it, the first run asks for the link — the one question this command adds — and later runs use the saved board.

Anything else the user says about the plan — `reviewer is Jane`, `V&V issues carry the label vnv` — changes it, is
saved, and the plan is shown again.

## Safety Posture

This workflow writes to tickets other people own. Three rules hold at all times:

1. **Dry run is the default.** A plain `/bc:vnv-sprint-prep` performs reads only. Every intended write is printed as a plan line.
2. **`--apply` still confirms.** Each phase (clone / comment / label / description / test cases) shows its batch and asks once before executing. Never execute a phase the user has not confirmed in this session.
3. **Reads are always allowed.** Re-reading dev-story comments to see whether your questions were answered happens on every run, dry or not — that is how the workflow knows a ticket can advance.

## Execution

1. Follow `howtos/load-settings.md` with `--need board,vnv_board --reads test_cases` — or `--need board --reads test_cases` when `--board` gave the link. The dev sprint can't be read without a verified dev board, so an unverified one stops the run; a project with no board or no V&V board is asked for the link on the spot.
2. Run the V&V sprint agent's steps in this session: follow `com.github.copilot/agents/vnv-sprint-prep-agent.agent.md`, passing the scope, the flags, and the project folder.

## The Seven Phases

| # | Phase | What it does | Writes? |
|---|---|---|---|
| 1 | **Board** | Take the V&V board link, refuse the dev board, and work out what puts an issue on the V&V board and who approves scenarios — the person running it, unless they name someone. Both show in the plan | settings only |
| 2 | **Sprint + parity** | Fetch the dev board's current-sprint stories; group by the `OS` field; flag any story whose platform counterpart is missing or unlinked | no |
| 3 | **Clone** | Create a matching story on the V&V board for each in-scope dev story, carrying summary, description, a `src-<DEV-KEY>` back-reference, and label `pending-validation` | yes |
| 4 | **Validate** | Check each clone against requirements and test cases for gaps, conflicts, and contradictions. Concerns → comment on the **original dev story**, label the clone `pending-questions` | yes |
| 5 | **Scenarios** | Write high-level scenarios into the V&V ticket's description; label `pending-scenario-validation` | yes |
| 6 | **Ready** | Once the designated reviewer approves in a comment, relabel `ready-for-test-case-creation` | yes |
| 7 | **Test cases** | Turn each approved ticket's scenarios into TestRail cases in the configured suite folder, with `refs` pointing back at the requirements and the dev story, then comment the case links onto the V&V ticket. When approved scenarios are revised later, refresh the cases that nobody has edited since | yes |

Phase 7 writes **skeleton** cases — title, preconditions, one step per Given/When/Then — for the V&V team to
expand. It creates nothing from a scenario that traces to no requirement, and nothing from a scenario phase 5
already marked as covered by an existing case. It skips itself with a visible line when
`test_cases.authoring` is unconfigured, because the template alone decides which body fields a case has and
guessing it writes the steps into a field nobody reads. `/bc:setup` fills it in.

### Revising approved scenarios

Approved scenarios can change after their cases exist, and phase 7 keeps the cases in step:

- **Re-review** — move the V&V ticket back to `pending-validation` in Jira. The next run re-validates it,
  redrafts the scenarios, and waits for the reviewer to approve **the new draft**: an approval comment left on
  the earlier draft does not count.
- **Hand edit** — edit the scenario block on the approved ticket, keeping its `### S1 — Title` and bullet
  structure. The next run notices the change and treats the edited block as the approved scenarios, because
  the ticket still carries the approved label.

Either way, the next run refreshes the cases: a case still exactly as the plugin generated it is updated to
match, a revised scenario with no case gets a new one, and a case the V&V team has edited by hand is **never
overwritten** — it is listed for manual review instead. Nothing is ever deleted, and a requirement link a
revised scenario dropped is flagged rather than removed.

## Resuming

Re-running is the normal mode of operation. On every run, before doing new work, the agent re-reads the
tickets already in flight and advances the ones that can move:

- **`pending-questions`** → re-read the comments on the **original dev story**. If the dev team answered the
  concerns raised, fold the answers in, re-validate, and if nothing is outstanding, move the ticket on to
  phase 5. If the questions are still open, report how long they have been waiting and leave it.
- **`pending-scenario-validation`** → re-read the comments on the **V&V ticket**. If the designated reviewer
  approved — in a comment newer than the current scenarios — relabel to `ready-for-test-case-creation`.
- **`ready-for-test-case-creation`** → terminal for the label pipeline: never relabelled or redrafted. Phase 7
  still checks it every run, creating its cases the first time and refreshing them when its approved
  scenarios are revised (see above).

- **`pending-validation`** → cloned but never reviewed, because a previous run stopped there or was a dry
  run. Goes into validation on this run.

### The label convention

Every V&V ticket carries **exactly one** of these four at any time — they are mutually exclusive, and each
transition removes the previous one rather than stacking:

| Label | Meaning | Set at |
|---|---|---|
| `pending-validation` | Cloned, not yet reviewed | Phase 3 |
| `pending-questions` | Concerns posted on the dev story, waiting on answers | Phase 4 |
| `pending-scenario-validation` | Scenarios written, waiting on the reviewer | Phase 5 |
| `ready-for-test-case-creation` | Approved — terminal | Phase 6 |

Rename any of them in `jira.vnv_workflow.labels` in the project's `.buddy-council/sources.json`; the workflow reads
the settings, never the hardcoded strings. Clones additionally carry a permanent `src-<DEV-KEY>` label and their
platform (`ios` / `android`) — those are not pipeline states and are never stripped, and neither is any
label a human adds.

State lives in `.buddy-council/vnv-progress.json` in the project folder, alongside the onboarding log, saved by
`scripts/bc_run.py` so it never prompts. Jira
labels remain the source of truth — if someone changes a label in Jira, the next run follows Jira, not the
local file, and repairs the file. A ticket found with no pipeline label is treated as `pending-validation`;
one found with several is repaired to the furthest-along, and the repair is reported.

## Known Platform Limits

Scenarios go into the V&V ticket's description rather than an attached `.md`. That is a choice, not a limit:
`mcp-atlassian` can upload files (`jira_update_issue` takes local paths in `attachments`), but the description
is always present, readable by reviewers in Jira, and editable through `jira_update_issue`.

Issue links **do** work (`jira_create_issue_link`), so each clone is linked to its dev story as well as
carrying the `src-<DEV-KEY>` label. If a site restricts link creation the clone still succeeds and the run
reports which pairs are label-only, so someone can link them in the UI in one pass.

## Error Handling

- **Dev board not verified** → stop; `/bc:setup` checks it again. A project with no dev board is asked for its link.
- **V&V board missing** → ask for its link, or accept `--board`.
- **V&V board id equals the dev board id** → stop and explain; this is a configuration error, not something to work around. A shared *project* is supported — see the discriminator below.
- **V&V board shares a project with the dev board and no discriminator is known** → derive one by sampling both boards. If the samples settle nothing, the plan shows that as the default, warns that clones may surface on the dev board, and says how to change it (`stamp label vnv`) — never a question.
- **No `OS` field on the project** → phase 2 falls back to the title prefix and says so loudly; parity results are marked lower-confidence.
- **No active sprint** → report it and stop. There is nothing to clone.
- **401 / 403 from Atlassian** → 401 means the key saved for the Jira site is wrong or expired: ask for a new one and save it (`howtos/load-settings.md`); 403 means the account lacks permission on that project, or an IP allowlist is blocking the request.