# Workflow Output Quality

Use this standard for workflow/tooling outputs that humans or automation consume directly, including CLI helpers, Telegram messages, workflow summaries, orchestrator handoffs, prompt synthesis output, generated commands, and commit suggestions.

Passing tests is required, but it is not enough. The output must reduce operator friction.

## Operator Sanity Review

QA must inspect representative output when a chunk changes workflow/tooling UX. The review should answer:

- Can a human understand the output without extra ChatGPT explanation?
- Are suggested commands copy-pasteable?
- Are exact commands actual commands, not vague prose?
- Are next actions located where the operator expects them, preferably in a final `## Suggested Commands` or `## Handoff` section?
- Are commit messages concise, sentence-case, and conventionally formatted?
- Are there contradictory next actions or mixed signals?
- Is the output concise enough for terminal and Telegram/mobile usage?
- Does the output reduce back-and-forth rather than create it?
- Does prompt or handoff text point to shared helpers such as `ai/commands/prompt-synthesize.sh` or `ai/commands/workflow-state.sh` when available?
- For assistant final chat responses that close, pause, or hand off a
  chunk/package/orchestration run, does the response include or mirror the
  canonical `Details`, `Good`, `Bad`, `Ugly`, `Validation`, and `Next`
  structure from `ai/standards/runtime-sop.md`, unless the response is a
  repository-approved tiny status-only exception?
- When unresolved carry-forward items are included, does the output distinguish
  blocking debt from non-blocking warnings, advisories, compatibility debt,
  pending enforcement, observations, and follow-ups?
- For YAML packets, reports, exports, dashboards, and detail-mode summaries,
  does carry-forward state come from the registry or Runtime
  scorecard/health projection rather than ad hoc prose parsing?
- For registered local/dev actions, does the output use the trusted daemon
  request/wait workflow and avoid raw Git, direct `run-once.sh`, and Codex
  platform escalation?
- Do blocked states explain what happened, why it matters, and what command or decision comes next?

Canonical handoff command categories live in
`ai/standards/workflow-handoff.md`.

## PASS Examples

- `Prompt Handoff Command: ai/commands/prompt-synthesize.sh qa`
- `Trusted daemon git commit: ai/tools/operator-daemon/request-action.sh --action git_commit --message "Add workflow summary report generator"`
- `Stale QA risk: no - QA pending for latest Developer pass`
- `PROMPT SYNTHESIS BLOCKED` followed by `Reason`, `Recommended Next Action`, and an explicit prompt, review, or transition command category.
- A summary whose final section is `## Suggested Commands` and contains the continuation commands only there.

## BLOCKED Examples

- `Prompt Handoff Command: Use ai/roles/qa.md and review the chunk`.
- `Trusted daemon git commit: ai/tools/operator-daemon/request-action.sh --action git_commit --message "Add workflow Summary Report Generator"`.
- Ready-for-QA output that calls normal pending QA a stale QA risk.
- A prompt review output with nested, ambiguous `Deliver:` sections.
- A blocked state that says only `failed` without the reason or next command.
- Output that lists one next action in the body and a different one in the final command section.
- A chunk-completion or stop-condition final chat response that summarizes work
  ad hoc and omits the canonical summary sections, even though the chunk
  artifact or Telegram `/details` has them.

## Review Requirements

For applicable chunks, QA should record:

- `Operator Sanity: PASS | BLOCKED`
- Exact output commands inspected.
- Any output-quality issues found.
- Whether issues are blocking or follow-up only.
- Whether carry-forward references are registry-backed and classified as
  blocking or non-blocking.
- Whether the final local/chat response shape is compliant when the chunk
  reaches a completion, stop, or approval boundary.

Developer self-check should include the same review before handoff when changing workflow/tooling UX.