AGENTS/.pi/gsd/workflows/audit-uat.md

<gsd-version v="1.12.4" />

<gsd-arguments>
  <settings><keep-extra-args /></settings>
</gsd-arguments>

<gsd-execute>
  <shell command="pi-gsd-tools">
    <args>
      <arg string="audit-uat" />
      <arg string="--raw" />
    </args>
    <outs>
      <out type="string" name="audit-data" />
    </outs>
  </shell>
  <shell command="pi-gsd-tools">
    <args>
      <arg string="state" />
      <arg string="json" />
      <arg string="--raw" />
    </args>
    <outs>
      <out type="string" name="state" />
    </outs>
  </shell>
</gsd-execute>

## Audit Data (pre-injected)

**UAT Audit:**
<gsd-paste name="audit-data" />

**State:**
<gsd-paste name="state" />

<purpose>
Cross-phase audit of all UAT and verification files. Finds every outstanding item (pending, skipped, blocked, human_needed), optionally verifies against the codebase to detect stale docs, and produces a prioritized human test plan.
</purpose>

<process>

<step name="initialize">
Run the CLI audit:

```bash
AUDIT=$(pi-gsd-tools audit-uat --raw)
```

Parse JSON for `results` array and `summary` object.

If `summary.total_items` is 0:
```
## All Clear

No outstanding UAT or verification items found across all phases.
All tests are passing, resolved, or diagnosed with fix plans.
```
Stop here.
</step>

<step name="categorize">
Group items by what's actionable NOW vs. what needs prerequisites:

**Testable Now** (no external dependencies):
- `pending` - tests never run
- `human_uat` - human verification items
- `skipped_unresolved` - skipped without clear blocking reason

**Needs Prerequisites:**
- `server_blocked` - needs external server running
- `device_needed` - needs physical device (not simulator)
- `build_needed` - needs release/preview build
- `third_party` - needs external service configuration

For each item in "Testable Now", use Grep/Read to check if the underlying feature still exists in the codebase:
- If the test references a component/function that no longer exists → mark as `stale`
- If the test references code that has been significantly rewritten → mark as `needs_update`
- Otherwise → mark as `active`
</step>

<step name="present">
Present the audit report:

```
## UAT Audit Report

**{total_items} outstanding items across {total_files} files in {phase_count} phases**

### Testable Now ({count})

| #   | Phase   | Test        | Description | Status                      |
| --- | ------- | ----------- | ----------- | --------------------------- |
| 1   | {phase} | {test_name} | {expected}  | {active/stale/needs_update} |
...

### Needs Prerequisites ({count})

| #   | Phase   | Test        | Blocked By | Description |
| --- | ------- | ----------- | ---------- | ----------- |
| 1   | {phase} | {test_name} | {category} | {expected}  |
...

### Stale (can be closed) ({count})

| #   | Phase   | Test        | Why Stale |
| --- | ------- | ----------- | --------- |
| 1   | {phase} | {test_name} | {reason}  |
...

---

## Recommended Actions

1. **Close stale items:** `/gsd-verify-work {phase}` - mark stale tests as resolved
2. **Run active tests:** Human UAT test plan below
3. **When prerequisites met:** Retest blocked items with `/gsd-verify-work {phase}`
```
</step>

<step name="test_plan">
Generate a human UAT test plan for "Testable Now" + "active" items only:

Group by what can be tested together (same screen, same feature, same prerequisite):

```
## Human UAT Test Plan

### Group 1: {category - e.g., "Billing Flow"}
Prerequisites: {what needs to be running/configured}

1. **{Test name}** (Phase {N})
   - Navigate to: {where}
   - Do: {action}
   - Expected: {expected behavior}

2. **{Test name}** (Phase {N})
   ...

### Group 2: {category}
...
```
</step>

</process>