# Issue-Level Completion Report Guidance

- This guidance applies during `workflow_closing`, after planned source issue work appears complete and before the source issue is closed.
- Treat closing as an issue-level audit, not another execution step. Compare the latest user instructions, source issue body, execution contract, workflow plan, step results, PR or merge result, current tracker state, and available evidence before deciding whether the source issue can close.
- Do not treat "all steps are marked complete" as enough by itself. The source issue can close only when the user's requested outcome is honestly delivered or the issue explicitly asked only for a report, feasibility check, blocker inventory, or bounded evidence.
- If the issue-level result is unsafe, broken, false, lacks completion evidence, has unmet `doneWhen`, or still requires downstream phases inside the main request, do not close through follow-up. Choose same-issue replanning, independently tracked blocker work, human handoff, or failure according to the decision contract.
- If the source issue can close, make `result.resultSummary` one short issue-level result sentence suitable for Canonical State. Do not reuse the final step summary unless it already summarizes the whole source issue.
- Write `result.humanComment` as the completion report that will be shown to the user under a control-plane completion heading. Do not start with a generic "Completed" heading; start with the concrete outcome in one or two plain sentences, then add only the sections that help the user decide whether the work is done.
- Prefer a compact Markdown structure adapted to the actual work:
  - `## What changed` only when repository, PR, tracker, or external state actually changed.
  - `## What I checked` for verification evidence, especially read-only or report-only work.
  - `## Where to review` for files, PRs, issue comments, generated reports, or external records the user should inspect.
  - `## Remaining items` only when something remains outside the completed scope or is tracked separately.
- For read-only, report-only, or answer-only work, avoid implying that code or files changed. Say plainly that no repository files were changed when that is part of the evidence.
- Use plain user-facing language. Avoid internal execution terms such as runner, workflow, continuation, token file, or environment unless the user already used them or the term is unavoidable. When a technical term is unavoidable, explain it briefly.
- Keep commands, paths, issue refs, pull request refs, API names, and exact evidence when they help the user verify the result. Do not paste long logs or implementation minutiae into the completion report.
- For pull request work, describe the PR or merge result in user terms. Do not invent host URLs; the control plane may add PR links such as a files tab link when it publishes the comment.
- For report-only or answer-only issues, the completion report itself may be the delivered result. Use `result.humanComment` for the complete answer when it fits the field limit. Use the configured issue notes path only when the report is too long, needed by later workflow steps, or explicitly requested. Create durable repository documentation only when the issue asks for project knowledge to be persisted.
- Build follow-up recommendations from the same audit as the completion report. Do not report follow-up work as completed current scope, and do not use follow-up to hide incomplete source issue work. Mention follow-up only as separately tracked next work when that helps the user understand what will happen after close.
- Put observable proof in `result.evidence`, not only in prose. Evidence should be concrete command results, file or API state, tracker state, PR or merge state, child issue results, or named validation checks that prove the issue-level result.
