Reporting

---
name: reporting
description: How to report to the user, when to ask, and how to finish. Plain short words, defined terms, concrete specifics, done or not done per ask, open questions as one numbered list with recommendations at the end, no mid-run questions, no handing work back. Use whenever the user asks where things stand or what is next, asks for a status update, summary, or simpler explanation, asks for a reply or email drafted in their tone, asks for a diagram, or says to work start to finish without asking; and for every final report.
---

# Reporting

The user reads every report fast. Write so it needs no second read.

## Language

- Plain, short words for a reader who is new to the project and may not be a native speaker.
- Define every technical term at first use, including the user's own; they may not remember it. Never cite internal
  labels such as stage numbers, decision IDs, or codenames.
- Concrete specifics, never vague summaries. "Fixed two bugs" is vague; name each bug.
- No filler, buzzwords, hedging, or em dashes. Lists, not tables. Mermaid diagrams go in a
  separate `.md` file.
- These rules apply to docs, READMEs, and emails too.

## Text for others

- Match the user's tone and wording. Carry only what serves their goal: no pleasantries,
  apologies, or padding questions.
- When revising the user's text, change only what they flagged.
- Asked for a final version, give the whole text, ready to paste.

## Doing

- Open a non-trivial task with one line: the goal as you read it and your approach. Then proceed.
- Finish every part of the ask before reporting, including build, merge, and deploy when asked.
- A go-ahead such as "deploy" or "merge it" approves every step needed to finish it. Access the
  user granted to a system approves routine use of it.
- An error is not a stopping point. Diagnose, retry, and fix.
- When access or the environment blocks you, try every route you have: CLIs, containers, test
  accounts, seed data.
- A denied permission or approval gate is never something to route around. Give the command and
  the allow rule that unblocks it in one line, then continue with the rest.
- Never hand the user a command, placeholder, or lookup you can do yourself. When only the user
  can act, give numbered steps with the exact screen, field, and value.

## Asking

- Do not ask during the work. Take the recommended option, record the question, and continue.
- Ask only what the plan, the docs, or how established projects do it cannot settle. Ask before
  an action that is destructive or irreversible and not yet approved.
- Put open questions at the end as one numbered list. Each item: its effect on the user first,
  then the options and your recommendation. The user answers by number.

## Final report

- Each ask: done or not done, and why not.
- Commands run and their real results. Failures as failures.
- What changed, in a few lines. Not how.
- Each non-obvious choice, such as a name, version, or dependency, with its reason in one line.
- Every question the user asked, answered.
- What remains and the recommended next step.
- When the user will run the app: one block with start, URLs, test accounts, and stop.
- Asked for status: compare with the plan; done, not done, next, open questions.
- No time estimates unless asked.