agentleFS
desbmadesbma/agent-skills/review-docs/SKILL.md

review-docs

Skill1 starsChanged 16 days agoMITView on GitHub

Review Jujutsu revision changes from jj show and report documentation and comments out of sync with the code.

23 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use create-vercel-ai-issue, dev-auth-bypass and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • FranciscoMorettiSkill

    create-vercel-ai-issue

    Create a well-formed GitHub issue in vercel/ai using the gh CLI. Use when reporting an AI SDK bug or preparing an issue body that contains logs, code blocks, versions, reproduction steps, and shell-sensitive text.

    Also in 3 projects that use this

  • FranciscoMorettiSkill

    dev-auth-bypass

    Authenticate a browser against a local ChatJS app without OAuth. Use for development login, local auth bypass, authenticated browser or Playwright testing, and the /api/dev-login route.

    Also in 3 projects that use this

  • +10 more from FranciscoMoretti

The file

We split this skill into the rules it gives an agent

1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 21 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow the common review instructions: @../review-common.md

    line 12

“Common” is measured: kept by at least 6 in 10 of the 21 edited versions of this file we could read. “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

Review documentation of Jujutsu changes

Review the Jujutsu changes for the target revision, and report documentation that no longer matches the code.

Follow the common review instructions: @../review-common.md

Scope

Documentation covers:

  • AGENTS.md, README.md, and any other documentation file
  • diagrams and schemas
  • code comments and docstrings

Main goals

Find documentation that:

  • contradicts the code: stale command, renamed item, removed option, changed default or behavior
  • describes something the change deleted
  • is missing for something the change introduced, and that a reader could not guess
  • lists cases where a term covering them all would serve the reader as well, above all when the change grew it by appending its own case

Also report comments and docstrings that break the rules of the "Comment and docstring style" section of AGENTS.md.

Guidelines

  • Quote both the code and the documentation that contradict each other
  • Fix documentation that is out of sync, only delete it when what it describes is gone
  • When documentation lists cases and the change adds one, reword it around a term that covers them all rather than append the new case; keep the list only where the reader needs each case named, such as a reference of options, and never trade precision the reader needs for a vaguer term
  • Be sparing with new documentation, do not propose any for its own sake
  • Stay on documentation: correctness, readability and test coverage are covered by other review domains

Severity

Anchor severity to what the documentation makes its reader do:

  • critical — following it destroys state or costs work that cannot be recovered
  • major — it contradicts the code and sends the reader down a path that does not exist
  • minor — a style rule break, an enumeration a general term would replace, or documentation missing where the code already says it

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.

Reviews can't be read right now.

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.