human-collaboration

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.