agent-report-style

SKILL.md

---
name: agent-report-style
description: Use for every reply that reports on work — proposing changes before editing, reporting what was changed, summarising findings, or asking the user to decide something. Enforces short, key-points-only reports and a propose-then-wait workflow before any file edits.
---

# Agent Report Style

## Overview

Report like a terse colleague, not a narrator. The user wants the key points and the decisions they need to make — nothing else.

**Core rules:**

- **Propose before editing.** Summarise intended changes and wait for approval. Never edit first.
- **Key points only.** One line per item. No "what I checked" sections, no background, no restating the request.
- **Only ask what blocks you.** Put open questions last, as short bullets.
- **Touch only what was approved.** Do not extend changes to sibling files unless the user says so.

## Proposing Changes

Before any edit, list each change as one line: **what** changes, then a short **why**.

```
Proposed changes to run_benchmark.sh:

1. **Set `--account=ludwig.prj`** — currently empty; Slurm will reject the job.
2. **Add `--bind /gpfs3/well,/well`** — with `--contain`, the container likely can't see project files.
3. **Remove `-n`** — it's a dry run; nothing actually executes.

Questions:
- Apply the same to the other two scripts?
```

- Numbered list, bold change, dash, reason in a single clause
- Optional items are marked `(optional)` inline — not given their own section
- Questions are bullets, one per decision, max ~3

## Reporting Completed Work

After editing, report in 1–3 lines:

- What changed, with a file link
- What was deliberately left alone (only if the user asked for it)
- Whether it was run or tested — say plainly if not
- The next command to run, if there is one

```
Updated run_benchmark.sh: account set to `ludwig.prj`, bind added to both `apptainer exec` calls.
`-n` kept, other scripts untouched. Not run yet — test with `sbatch Scripts/run_benchmark.sh` from the project root.
```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Editing, then explaining | Propose first, edit after approval |
| "What I checked" preamble | Drop it; mention a finding only if it justifies a change |
| Multi-sentence reasons | One clause per reason |
| Caveats section | Keep a caveat only if it changes what the user does next — one line |
| Extending the change to similar files | Ask; don't assume |
| Re-listing unchanged items | Say only what changed |
| Recap that repeats the proposal | Point back briefly: "Done as proposed." |