agentleFS
nshopiknshopik/dream-team/skills/scope-mr/SKILL.md

scope-mr

Skill2 starsChanged 19 days agoMITView on GitHub

Writes MR/PR descriptions: why, how, root cause, behaviour. Use when writing or editing an MR/PR description (`glab mr create`, `gh pr create`, `gh api …/pulls`, `-f description=`). Commit messages: use `scope-commit` instead.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write each part in prose, - bullets, or a table.

    line 18
  2. Distinctive:

    Never list and Length rules still apply.

    line 28
  3. Distinctive:

    Never narrate step-by-step control flow.

    line 45
  4. Distinctive:

    Only a cause you verified.

    line 52
  5. Distinctive:

    Never pad a short description toward either number.

    line 106
  6. Distinctive:

    Commit body = permanent history.

    line 120

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

MR description is review-facing. Different text from the commit body. Never --fill.

mr-style

Reviewer has the diff open and ten minutes. They read code, not your session.

Shape

  • Parts, in order: why, how, root cause, behaviour.
  • Write each part in prose, - bullets, or a table.
  • Two or more commands or snippets → one fenced block, a # comment per case; never inline code in bullets.
  • Three or more numbers a reviewer would compare → one table, a row per case; never prose.
  • Each part after why is optional.
  • Nothing to say for a part → omit it.
  • Under ~50 changed lines → one or two sentences. Anything else goes to the user.
  • One fix repeated at several sites → a short why paragraph, then a short how paragraph.
  • Four parts is the ceiling, never the target.
  • Bugfix and feature share this shape; a feature has no root cause.
  • An upstream repo's PR template, or the shape of its recent PRs, wins over this shape; the Never list and Length rules still apply.

Why

  • Always first.
  • One or two sentences.
  • Bugfix: open with what the code did wrong, not where it happens or what it caused.
  • Feature: name what it adds and what it buys.
  • Docs: name what was undocumented.
  • Link the issue it closes.
  • Commits already say everything → that one line is the whole description.

How

  • What the change does to resolve the why.
  • Bullets when several independent pieces; one clause each.
  • Big or multi-file diff → name the spot to read first, inside this part.
  • Never narrate step-by-step control flow.

Root cause

  • Bugfix only.
  • Why already names the cause → omit this part; never say it twice.
  • Why the bug happened, in one or two sentences.
  • Only a cause you verified. Unverified → omit this part; a guessed cause reads as a finding and outlives the guess.

Names

  • Describe behaviour in plain words; a backticked code name is the exception.
  • User-facing name (flag, config key, metric, exit code, error string) → no limit.
  • Code name (function, type, field — own code or library) → at most five distinct names in the whole text; repeating one costs nothing.
  • Detail that locates a site or person (city, address, coordinates) → leave it out unless the work depends on it.
  • Issue, MR or repo the target forge's readers cannot open → describe it in plain words, or drop it.

Behaviour

  • The part a reviewer cannot read off the diff.
  • Bugfix leans here on the behaviour delta; feature on the user-facing surface and compat.
  • A new or changed config, default, flag, output, or stat counter.
  • A consequence the diff cannot show: breaking change, migration, security fix, revert.
  • Data that starts or stops flowing.
  • An interaction or precedence rule between the new knob and an existing one.
  • Existing behaviour this change does not alter → not a part; tell the user it was left out.
  • A decision worth questioning, written as behaviour — "when both set, whichever fires first wins", not "Decision worth challenging: ...".

Never

  • A rung rubric as a heading or lead-in: "Look at first", "Where to look first:", "Decision worth challenging:", "Blast radius:", "Riskiest part:".
  • The ladder picks what to write; its rung names never appear in the text.
  • A "deferred" or "left out" section → that item is an issue, not a description line.
  • A bare content tag ("Default:", "Deferred:") names the thing, not the rubric — allowed.
  • Per-commit summaries.
  • Restatements of the diff.
  • Restatements of a commit body, except its why, how, or root cause.
  • A single-commit MR may use that commit's body as the description.
  • A sentence the title already says: "this adds / documents / fixes X".
  • Verification logs, test counts.
  • Background already on the issue → link it, don't repeat it.
  • Addressing the reader.
  • Narrating your order of work.
  • What you tried first, rules you rejected, follow-up ideas → issue.
  • Risk-grading words: "riskiest", "dangerous", "be careful", "watch out".
  • Mid-sentence bold.
  • * bullets — use -.
  • Hard-wrapped lines — one line per paragraph or list item.
  • Generated with Claude Code or any other AI-attribution line, unless the user asks for one.

Length

  • Most descriptions fit well under 150 words.
  • 300 hard cap.
  • Fenced blocks and table rows do not count toward the cap.
  • Never pad a short description toward either number.
  • A small diff binds tighter than the ceiling: the budget scales with the change.
  • Longer than the diff → cut parts, not words.

rung-four

  • In-diff and fine: a knob inside the changed lines, a next step this change stops short of.
  • Off-diff and not fine: an audit finding, a rule you rejected, a follow-up idea — however deliberate the omission.
  • An off-diff item reads as scope the reviewer must evaluate; it is not in front of them.
  • Fix: move it to an issue and cite the issue, or drop the line.

fill

  • Commit body = permanent history. Why the change exists.
  • Description = review-facing. What to look at first.
  • They coincide often enough that --fill looks harmless. That is how it stops the question being asked.
  • Commits genuinely say everything → one line is a fine description. Write that line.

Examples

❌ rubric headings, and sentences the diff already covers

Closes #39.

## What it does
- withRecover reports whether it panicked

## Look at first
flushDesignated.

## Challenge
whole-batch no_sink accounting.

✅ bugfix — why, how (bullets fine), behaviour; no rubric headings

A recovered panic in a flush worker was swallowed with no accounting, so
one bad frame could drop a whole batch while every alert stayed green.

`withRecover` now reports the panic, and the flush, spill, and best-effort
workers each charge the lost batch to their own drop counter. The crux is
`flushDesignated`, the shared durable-path helper both flush arms call.

Under a multi-primary config the whole batch is charged to `no_sink` even
when an earlier primary already succeeded; the single-primary default
never hits it.

Closes #39

✅ feature — why, then the user-facing behaviour to know

Adds an opt-in `client-wait-timeout` directive: a client waiting on
recursion longer than the limit gets SERVFAIL while recursion continues
in the background, so the cache still fills. Default `0` (disabled), no
existing behavior changes.

When both `client-wait-timeout` and `serve-expired-client-timeout` are
set, whichever fires first answers. A new `num.queries_client_wait_timeout`
counter reports how often it triggered.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.