# Writing UAT Reports

**When to use:** After completing a phase, feature, or release and you need to document what was tested and the outcomes.

## Prerequisites

- Completed UAT testing session
- Access to test results and logs
- Understanding of what was in scope

## Quick Start

```bash
# Create a UAT report following the template
cp uat/how-to.md uat/{feature}-{date}.md

# Edit with your results
# File naming: uat/phase6-distributed-2026-02-02.md
```

## Report Structure

Every UAT report follows the template in `uat/how-to.md`:

1. **Header** — Date, phase/feature, tester, overall status
2. **Summary** — 1-2 sentences on what was tested
3. **Scope** — What was and wasn't tested
4. **Environment** — Rust version, OS, commit
5. **Test Results** — Tables with Expected/Actual/Status
6. **Issues Found** — Severity, status, description
7. **Fixes Applied** — Changes made during UAT
8. **Recommendations** — Future improvements
9. **Sign-Off** — Checklist for release readiness

## File Naming

```
uat/{feature-or-phase}-{YYYY-MM-DD}.md
```

Examples:
- `uat/phase6-distributed-2026-02-02.md`
- `uat/skeptic-endpoint-2025-12-15.md`
- `uat/go-sdk-v2-2026-01-20.md`

## Test Result Tables

Use consistent formatting:

```markdown
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
| Build | Compiles | Compiled in 36s | PASS |
| Health endpoint | 200 OK | 200 OK | PASS |
```

## Issue Severity Levels

| Severity | Meaning |
|----------|---------|
| Critical | Blocks release, data loss risk |
| High | Major functionality broken |
| Medium | Functionality degraded but workaround exists |
| Low | Minor issue, cosmetic, or edge case |

## Sign-Off Checklist

Before marking a UAT complete:

- [ ] All critical tests pass
- [ ] No blocking issues remain
- [ ] Documentation updated
- [ ] Ready for release

## Troubleshooting

### Test results are inconsistent

Check the environment section — version mismatches cause false failures. Re-run in a clean environment.

### Can't reproduce an issue

Document what you tried and mark the issue as "intermittent" with reproduction steps attempted.

## Related

- [Testing Guide](.claude/guides/local/testing.md)
- [Quality Checks](.claude/guides/local/quality-checks.md)
- [UAT Template](uat/how-to.md)