| name | human-collaboration |
| description | Write agent output for the accountable human reviewer — route narrative by audience and lifespan, lead with a budgeted summary, keep detail collapsed, and plan before building. Use when writing PR or issue descriptions, commit messages, or code comments, when addressing or resolving PR review comments, when deciding whether to raise an issue or where work-narrative belongs, or when scoping a non-trivial change before generating code. |
Human Collaboration
A human reviewer approves every change and is accountable for understanding it. Their
attention is the scarce resource, not the agent's output. Optimise for one thing:
the reviewer's time to a confident approval. That single goal bounds verbosity and
decides what to surface versus hide.
Route output by audience and lifespan
Where an artifact lives decides who is forced to read it and how fast it rots. Put each
kind of content where it belongs:
- Code comments and docstrings — the code must speak for itself through naming and
structure. Add a comment only for the cases
python-code-style allows (third-party
smells, pinned-version reasons, genuinely opaque logic); never narrate what the code
does or why you wrote it — comments are re-read on every future pass and rot faster
than code. This project uses no module- or class-level docstrings (per
python-code-style): don't add them, keep function docstrings only and short, and put
a CLI's usage narrative in its command/argument help (e.g. Typer), not a module
docstring.
- PR description — the reviewer's entry point. Write it in full yourself: a concise
agent-drafted summary conveys the change better than a terse hand-written stub. Lead
with the conclusion, then what changed, why, risk, and where to focus review.
Put investigation, dead-ends, and long reasoning in a collapsed
<details> block so
they don't block the read.
- Issues — raise one only when it's actionable (a real bug, decision, or task), not
to log noise. Treat the description like a PR's: lead with the problem and the ask,
then the detail, with logs and long repro steps collapsed. The reading-cost budget
applies to issue bodies too.
- Commit messages — concise conventional-commit subjects. Keep the agent's
Co-Authored-By: trailer (its name and email) on commits Claude wrote, so
AI-assisted contribution stays measurable.
- Durable decisions (why X over Y, a constraint, a trade-off that outlives this PR)
— belong in a durable, human-owned decision log (an ADR doc, a wiki, a Notion
database — whatever you keep for this project), not buried in code or PR prose where
it's unfindable later. Surface the decision there rather than deciding on your own
initiative.
- Ephemeral working notes (exploration, scratch state across a long task) — keep in
a scratchpad; never commit them into a reviewed artifact.
Lead with a budgeted summary
Use progressive disclosure: a short must-read summary on top, detail collapsed or linked
below. The reviewer reads the 10% they must and expands the rest by choice.
-
Keep the must-read summary of a PR or issue tight (aim ≤ 250 words); push everything
else into <details> or a linked doc.
-
Favour concision: more length or structure doesn't add understanding, so don't pad —
a tight, substance-first summary beats a long one.
-
Measure a draft PR/issue body before posting:
gh pr view <n> --json body -q .body \
| uv run --script skills/human-collaboration/scripts/reading_cost.py -
It reports reading time, prose-vs-code split, and flags an over-budget summary or
body. Advisory — use it to trim, not as a gate.
Plan before building
Generating the wrong thing quickly is worse than generating nothing. For any non-trivial
change:
- Scope the work and confirm direction before writing code, not after.
- Prefer small PRs sized for a tired reviewer to hold in their head; split at natural
seams rather than shipping one large diff.
- Checkpoint with the human at decision points where the approach could fork.
Resolve review comments quietly
Review threads are reviewer attention too. When you address a comment, fix it and
resolve the thread — don't post a "done" reply. Reserve replies for comments you are
declining (state why, briefly), and resolve those as well. Every extra reply is more
for the reviewer to read.
Prefer measured rules over asserted ones
You cannot reliably introspect what content helps a future agent session. When a claim
about that drives a rule, test it — fan out cold-start readers over content variants and
score their comprehension against a withheld key.
Set the rule from the data, not the assumption.
