issues-to-outcomes git:20261021.61c15fbA

Immutable. This exact content never changes and is served at /api/v1/blob/f06c0256cf4e870f.

---
name: issues-to-outcomes
description: "Load before writing any report of work: a status update, an end-of-day or session summary, a handoff, a 'what landed' or 'what did you do' answer, or any reply built from a list of issues, PRs or commits. Also load when the reader says a report means nothing to them, asks what they experience, or asks for it at a high level. Turns issue and PR titles into outcomes the reader notices: how much of the work shows in the product, each visible change as before and now, and the invisible work as what was stuck or silently wrong and no longer is. Ships a checker the draft must pass before it is sent."
short_description: "Turn a list of issues into the outcomes the reader notices."
allow_implicit_invocation: true
metadata:
  when: "writing a progress report"
  situation: Reports and pages
---

# Issues to outcomes

A report of finished work answers one question for its reader: what is
different for me now? An issue number and its title answer a different one:
what did the tracker call it? Titles are written for whoever implements the
work. The reader of a report was not there and should not need the codebase in
their head to understand it.

## Who the reader is

Write for the person who uses the product and pays for the work. They notice
two things: what the product does when they use it, and what they or their
agents can or cannot get done while working on it. Everything in the report is
one of those two, or it is left out.

## The shape

Write the report in this order.

1. **How much of this can you see.** Open with one honest sentence on how much
   of the work shows up in the product. When the answer is "almost nothing",
   say exactly that and say what the work was instead. Do not open with a
   count of issues closed or PRs merged.

2. **What changed in the product.** One item for each change the reader can
   see, hear or do. Describe the situation they are in, what happened before,
   and what happens now. A change that is real but shows nothing yet says so,
   and says what it makes possible later.

3. **What was stuck and is not any more.** The rest of the work, named by its
   consequence: what could not be done, or what was quietly wrong, and what is
   true now. When the reader is already seeing an effect of it, connect the
   two for them.

4. **What you will still run into.** Only when something the reader will hit
   is still broken or unfinished. Leave the section out when nothing is.

Group related work into one item. Five fixes to the same failure are one line
about that failure, not five lines.

## Writing each item

- Start from the reader's situation, never from the code. "A looped ability
  sound no longer gets stuck on forever when part of the effect fails to
  load", not "fix cue leak on partial load failure".
- Give the before and the now. A fix the reader cannot picture before and
  after is not yet described.
- Use the words the reader uses for the product. Leave out type, function,
  file and rule names unless the reader has to open, run or search for them.
- Keep the proportions true. Plumbing is reported as plumbing. Do not dress a
  refactor as a feature, and do not pad a short list of visible changes.
- A reference goes at the end of its sentence, as a link, for the reader who
  wants the detail. It never opens a line and never stands in for the
  description.

## Example

A report that means nothing to its reader:

~~~md
- #1407 test harness raises only real engine events
- #1417 full verification works on the declared runner image
- #1422 and #1423, two cue leaks
- #1445 a cancelled ability tells its cues it was cancelled
- #1447 project code-style rules judge code again
~~~

The same work as what the reader notices:

~~~md
What you can see in the game from today's work: almost nothing. Nearly
everything that landed was plumbing.

Two things did change in play, both small:

- A looped ability sound no longer gets stuck on forever when part of that
  ability's effect fails to load. Before, it kept playing with no way to stop
  it. The same fix covers an effect put on several targets where one of them
  fails ([#1422](https://example.com/1422), [#1423](https://example.com/1423)).
- A cancelled ability now ends its effects as "cancelled" instead of
  pretending it finished normally. Nothing looks different yet; it lets
  effects fade differently on cancel later ([#1445](https://example.com/1445)).

The rest was getting unstuck, which you don't see but which was blocking
everything else:

- Nothing could be verified at all on the current test machines. It can now
  ([#1417](https://example.com/1417)).
- The project's own code-quality checks were silently switched off for every
  agent. They are back on, which is why agents keep getting sent back with
  real findings tonight ([#1447](https://example.com/1447)).
~~~

## Before you send it

Run the draft through the checker that sits beside this file:

~~~sh
python3 <folder of this SKILL.md>/scripts/check_report.py <<'REPORT'
<the draft>
REPORT
~~~

It prints every line that opens with a tracker reference and exits non-zero
while any remain. Rewrite those lines and run it again; send the report once
it exits zero.

The checker cannot tell whether a line describes something the reader would
notice. That part is your judgment: read each item as someone who has never
seen the code and ask whether they could say what changed for them.