Sprimo/docs/QA_WORKFLOW.md

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:

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

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