# Reporting And Communicating With The User

How agents report progress and results. Always in force, every host. The test of
a good report: a non-expert teammate understands what happened and what's next
**without decoding any ID**.

## Plain language first

- Lead with a short, plain-English summary: what you did, what it means, and what
  happens next — in normal words.
- **Do not open with ID codes.** `REQ-*`, `TRK-*`, `ARCH-DEC-*`, `IMP-PHASE-*`,
  `IMP-TASK-*`, `BR-Q-*`, `PRD-REQ-*` and the like are bookkeeping, not the
  message. Mention an ID only when it adds something the words don't.
- Put dense traceability / ID detail **after** the summary — in a short "Details"
  section or a collapsed block — never as the headline. A wall of codes up top is
  a failed report even if every code is correct.

## Human-readable UI

This applies to interfaces an agent designs, implements, reviews, or describes,
not only to status reports.

- Use an available human-readable name, title, summary, or label as the primary
  UI text. System IDs are behind-the-scenes identifiers, not primary button
  labels, headings, navigation text, notifications, or table values.
- Never replace readable text with a bare ID. Show an ID only when the user asks
  for it or it is needed for disambiguation, support, or audit; then keep it
  secondary and copyable beside the readable name.
- If no readable name exists, derive a useful fallback label and explain the ID
  rather than exposing unexplained machine syntax as ordinary user content.

## Match the autonomy tier when you report

- In `autonomous`, report completed work and keep going. **Do not end a completed
  step with "shall I proceed?" / "which would you prefer?"** — continuing the
  planned work *is* the work, not a decision to escalate. Offering a pause is fine
  only as a one-line P.S., never as a blocking question.
- Ask a real question only when the next action hits the consent floor or the
  configured tier genuinely requires a check (see `project-decision-policy`). Then
  ask it inline, in plain words — not as a menu of jargon options.

## Never nag the user to stop

- **Session length and context pressure are not reasons to stop.** Never suggest
  wrapping up, handing off, closing the session, or "picking it up fresh" because
  the session has been long or your context is filling. The harness summarizes
  context automatically and continues — wrapping up early invents a problem the
  system already solves. Keep working until the task is done or the user stops you.
- **Bookkeeping is silent, not a nag.** Any tracking/changelog/state updates that
  are genuinely needed happen inline as part of the work (or via the auto-write
  hooks). Never tell the user to run session-close or end a response with wrap-up
  ceremony. `project-session-close` / `/prd-close` is something the **user**
  invokes when *they* decide to close — the agent does not push it.

## No fake precision

- No time / duration estimates — use complexity + confidence
  (`.prd_plugin/method/estimation.md`).
- Don't claim done without fresh evidence (`.prd_plugin/method/completion-gate.md`).