agentleFS
ahmadrosidahmadrosid/nakama/.agents/skills/adhd-pr-description/SKILL.md

adhd-pr-description

Skill826 starsChanged 12 days agoMITView on GitHub

Write or rewrite GitHub PR descriptions in a scannable ADHD-friendly format: outcome-first lead, two-line before/after, short why-safe list, residual one-liner, tight test plan, and UI proof (a screenshot) when the PR changes the UI. Default for all Nakama PR bodies (agents and humans). Use when writing, improving, or rewriting a PR description, opening a PR via ce-commit-push-pr, or when the user mentions ADHD PR / adhd-pr-description. Prefer this shape over long narrative PR prose.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No diff tourism: Do not list files, line counts as the story, or "also cleaned up exports" unless that *is* the risk.

    line 61
  2. Distinctive:

    Test plan = runnable: Prefer checked commands with pass counts.

    line 62
  3. Very specific:

    Apply with gh: Write body to a temp file.

    line 65
  4. Very specific:

    Read the PR diff / commits (gh pr view, git diff base...HEAD)

    line 105
  5. Very specific:

    If the diff changes UI: capture each changed state in the real app (.agents/skills/verify-bs/SKILL.md), then attach the images

    line 108

≈ “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

ADHD PR description

Default PR body format for this repo. Reviewers should finish the description in one glance. The diff is already on GitHub — do not restate file moves.

Agents: load this skill whenever composing or rewriting a Nakama PR description (including via ce-commit-push-pr). Body shape comes from here; still gather real claims from the diff (outcome, risk, what you verified).

Shape (required)

## Summary

<one line: who does what → result. No jargon fog unless the change is jargon.>

**Before:** <one line — old behavior or cost>
**After:** <one line — new behavior; name the key function/path if it helps risk>

Why safe:
1. <reason>
2. <reason>
3. <reason>   <!-- 2–3 items max; drop #3 if nothing to say -->

Only re-add / follow up if <one residual risk or rollback trigger>.

## Test plan
- [x] <command already run> (<N> pass)
- [ ] <one manual check a human can do in <2 min>

## UI proof
<!-- Required when the PR changes the UI. Delete when no UI changed. -->
**1. <state or step>**

![<short-name>](<uploaded image URL>)

Optional after test plan (keep if the workflow expects Compound Engineering badges):

---

[![Compound Engineering](https://img.shields.io/badge/Built_with-Compound_Engineering-6366f1)](https://github.com/EveryInc/compound-engineering-plugin)
![HARNESS](https://img.shields.io/badge/<MODEL_SLUG>-000000)

Rules

  1. Lead = outcome. First Summary line is the new world, not "This PR removes…".
  2. Before/After = two lines. Bold labels. No paragraph wrapping them.
  3. Why safe = numbered, ≤3. Cap at 5 total bullets anywhere in the body; if more, keep only the decision-changing ones.
  4. One residual. Name the case that would make you undo this. Skip if truly none.
  5. No diff tourism. Do not list files, line counts as the story, or "also cleaned up exports" unless that is the risk.
  6. Test plan = runnable. Prefer checked commands with pass counts; one unchecked manual probe.
  7. Title stays conventional. type(scope): imperative — short. Body carries this shape; title does not need emoji or essays.
  8. UI change → UI proof. A PR that changes what a user sees (apps/web, the desktop app, a channel message layout) must have a ## UI proof section: a screenshot of the changed screen in the real app, or a short video/GIF for a flow, a hover or an animation. Show each state the change touches, with a one-line caption. Add a before image when the change replaces an old screen. A test alone is not proof. Upload with gh pr edit <n> --attach <image>. No UI change → delete the section.
  9. Apply with gh. Write body to a temp file; gh pr edit <n> --body-file … or gh pr create --body-file …. Never --body "$(cat …)".

Golden example

Match this density:

## Summary

Approve an org-memory proposal → bullet goes into `MEMORY.md`. No LLM call.

**Before:** deterministic merge, then optional model rewrite of the whole file.
**After:** deterministic merge only (`applyApprovedOrgMemoryBullet`).

Why safe:
1. Dedup + supersede already live in that function
2. LLM path already failed closed to the deterministic result
3. −230 lines, same approve outcome

Only re-add an LLM rewrite if contradictory bullets start surviving approve.

## Test plan
- [x] `bun test packages/agent/src` (80 pass)
- [x] `bun test apps/server/src/services/org-memory-service.test.ts` (15 pass)
- [ ] Approve one pending proposal (pinned + recent-log) — bullet lands as before

Anti-patterns

Don'tDo
Multi-paragraph SummaryOne outcome line + Before/After + Why safe
"This PR aims to…" / "In order to…"Start with the verb or user action
Nested ### under SummaryFlat ## Summary + ## Test plan (+ ## UI proof for UI changes)
Restating every deleted fileResidual risk only
Vague "tests passed"Exact command + pass count
UI PR with no image, or "see the test"## UI proof with a captioned screenshot of the real app

Workflow

  1. Read the PR diff / commits (gh pr view, git diff base...HEAD)
  2. Name: outcome, before, after, ≤3 why-safe, one residual
  3. Fill the template — cut any sentence the diff already proves
  4. If the diff changes UI: capture each changed state in the real app (.agents/skills/verify-bs/SKILL.md), then attach the images
  5. Apply via --body-file
  6. Reply with the PR URL (plus "say if you want the title tightened" only if useful)

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.