Skip to content
cccskills
FreePublished on GitHub

adr-review

Review and rewrite architecture decision records, documents that explain design choices, from a newcomer’s perspective. Identify missing context, buried decisions, and temporary details, then reorganize each document so future readers can follow the reasoning.

OriginalShow the original description

Review one or more ADRs with fresh eyes (as a team member without prior context), identify narrative and structural issues, then rewrite them. Use when the user asks to review, improve, rewrite, or take a fresh-eyes pass on an ADR or a set of ADRs (Architecture Decision Records).

prisma/orm
See how to install

Good for

  • Reviewing design decisions from a new team member’s perspective
  • Making an ADR’s decision and reasoning easier to follow
  • Removing temporary project context from long-lived records
  • Reviewing and rewriting several ADRs individually

Files included (1)

  • SKILL.md2.6 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Reviewing and Rewriting ADRs

Read each ADR with fresh eyes. Pretend you're a member of the team who doesn't have all the context the author has. The goal is to find places where the document assumes context the reader doesn't have, buries the decision, or carries baggage that won't make sense to a future reader.

This skill applies whether you're working on a single ADR or a batch. Treat each ADR independently — do the analysis and rewrite per document — even when several are in scope at once.

Workflow

  1. Analyze first, in chat. Before touching any file, list the issues you found and explain them. Do not rewrite silently. When multiple ADRs are in scope, group your analysis per ADR so the user can react to each one before rewrites land.
  2. Then rewrite each document to address the issues you identified.

What a good ADR looks like

  • Starts with a clear grounding example. Give the reader something concrete to pin understanding to before the abstract reasoning starts.
  • Has a strong narrative that builds the topic up bit by bit, explaining clearly throughout. Don't compress; let ideas breathe.
  • Leads with the decision. State what's being decided up front. The reader should know the conclusion before working through the reasoning.
  • Ends with alternatives considered. Put rejected options last so the reader isn't loaded down with information about paths the document is making irrelevant.

What an ADR must NOT contain

ADRs are long-lived documentation. They should not contain:

  • References to Linear tickets, GitHub issues, or other ticket trackers.
  • Milestones from the project that produced the ADR.
  • States the system passed through during or preceding a refactor that will never be seen again — interim names, deprecated wrappers being removed, "current" qualifiers, "we used to" framing.

If a piece of context only makes sense to someone who lived through the change, cut it or rewrite it as a fact about the system as it is.

Output shape

When invoked:

  1. Read the ADR (or ADRs) in scope.
  2. Write your analysis in the chat — what's missing, what's buried, what's transient, what's unclear to a fresh reader. Be specific; quote or cite the parts you're flagging. For multiple ADRs, label each block clearly.
  3. Then rewrite each file end-to-end so it follows the structure above.

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Comments are published right away. Do not include personal information such as email addresses or phone numbers. Up to 2 URLs.

0 / 1,000 characters

This form is protected by reCAPTCHA, and the Google Privacy Policy and Terms of Service apply.

More skills from this repository

ast-visitor-pattern

FreeSummary

Refactor TypeScript code that handles several variants in multiple places using frozen classes and a Visitor interface, which defines a handler for each variant. This helps type checking expose missing handlers when new variants are added.

  • Refactor a union type with repeated switch statements
  • Design commands or nodes that need several kinds of processing
  • Catch missing handlers when adding a new variant
prisma/orm47.7KUpdated Oct 17, 2026

bumping-biome

FreeSummary

Update Biome packages with pnpm, align configuration filenames and schema versions across the repository, and run the configured checks and fixes. Receive a report of remaining issues, with optional further fixes subject to agreement.

  • Updating Biome to a specified version
  • Aligning configuration files after dependency updates
  • Checking for issues introduced by a Biome update
prisma/orm47.7KUpdated Oct 17, 2026

contrib-pr

FreeSummary

Prepare and open a pull request for an external contribution to prisma/orm. Check contribution rules, change scope, tests, and contributor signoffs, then draft the title and explanation for approval before submitting from a fork.

  • Submitting a Prisma contribution from a fork
  • Checking tests and scope before requesting review
  • Verifying contributor signoffs on every commit
prisma/orm47.7KUpdated Oct 17, 2026

create-pr

FreeSummary

Create GitHub pull requests for Prisma 8 with Linear ticket IDs in their titles. Turn branch changes into a clear description covering concrete examples, design decisions, behavior changes, and testing evidence for reviewers.

  • Submitting branch changes for review
  • Linking a pull request to a Linear ticket
  • Explaining design decisions and behavior changes
prisma/orm47.7KUpdated Oct 17, 2026

draft-release-notes

FreeSummary

Draft Prisma 8 release notes from merged PRs since the previous published release. Select user-facing changes, put breaking changes first, link migration guidance and PR evidence, and mirror the notes in CHANGELOG.md.

  • Draft notes for a stable or RC release
  • Summarize changes since the previous published release
  • Explain breaking changes with migration guidance
prisma/orm47.7KUpdated Oct 17, 2026

github-review-iteration

FreeSummary

Coordinate GitHub pull request reviews by assigning comment triage and code changes to dedicated sub-agents. Repeat the process, track decisions and progress, and reply to and resolve threads as fixes are completed.

  • Work through outstanding pull request review comments
  • Separate required fixes from items outside the pull request scope
  • Repeat review and implementation until actionable items are cleared
prisma/orm47.7KUpdated Oct 17, 2026

See all skills by prisma

Report a problem with this skill