# Sprimo QA and Documentation Workflow

## Purpose

This workflow defines how bug reports, runtime evidence, and documentation updates are
maintained so every issue is auditable from first report to closure.

## Issue Lifecycle

All issues use a single file: `issues/issueN.md`.

Allowed lifecycle states:

1. `Reported`
2. `Triaged`
3. `In Progress`
4. `Fix Implemented`
5. `Verification Passed`
6. `Closed`

Each state transition must include:

- local timestamp (`YYYY-MM-DD HH:MM`)
- actor
- short note
- evidence links when available

## Evidence Requirements

Screenshots are stored under `issues/screenshots/`.

Naming convention:

- before: `issueN-before-YYYYMMDD-HHMMSS.png`
- after: `issueN-after-YYYYMMDD-HHMMSS.png`
- optional checkpoint suffix: `-step1`, `-step2`

For UI/runtime behavior bugs:

- at least one before screenshot is required at report/triage time
- at least one after screenshot is required before `Verification Passed` or `Closed`

Legacy reports may keep `issues/screenshots/issueN.png` as before evidence.

## Verification Gate

Before marking an issue `Closed`, all conditions must be met:

1. Relevant checks/tests are recorded:
- `cargo check --workspace`
- `cargo test --workspace` (or documented rationale for targeted tests)
2. Visual checklist is completed with before/after screenshot references.
3. Docs are synchronized:
- `issues/issueN.md` lifecycle and verification sections updated
- impacted files under `docs/` updated when behavior/spec/status changed

## Documentation Sync Rules

Update these files when applicable:

- `docs/IMPLEMENTATION_STATUS.md` for milestone-level implementation status
- `docs/RELEASE_TESTING.md` when release/manual QA steps change
- `docs/API_SPEC.md`, `docs/CONFIG_REFERENCE.md`, or other contracts if behavior changed

## Command Checklist

Minimum command set for fix validation:

```powershell
cargo check --workspace
cargo test --workspace
just qa-validate
```

Optional runtime/API stress validation:

```powershell
just random-backend-test
```

For runtime behavior issues, include screenshot capture paths in the issue file.

## Definition of Done

An issue is done only when:

- lifecycle state is `Closed`
- verification gate passed
- evidence links resolve to files in repository
- `just qa-validate` passes

## Tauri Runtime Addendum

For `sprimo-tauri` runtime behavior issues, follow `docs/TAURI_RUNTIME_TESTING.md`.

Additional strict requirements:

- include `current_state` and `load_active_sprite_pack` invoke validation notes
- include `runtime:snapshot` event verification notes
- include tauri runtime API verification (`/v1/health`, `/v1/state`, `/v1/command`, `/v1/commands`)
- do not move issue status to `Closed` until all strict-gate evidence in
  `docs/TAURI_RUNTIME_TESTING.md` is present