backthread

Add Reasoning To Prs

Name: Add Reasoning To Prs
Author: backthread

Git community

SOURCE https://github.com/backthread/add-reasoning-to-prs

Description

Claude Code hook that writes a forward-only why-block (decisions, trade-offs, assumptions, limitations) into your PR description or commit message at PR-create / direct-push time.

Installation

This entry records only its repository, not the path inside it, so there is no exact command to give. Open the source below and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

README

**English** · [简体中文](docs/i18n/README.zh-CN.md) · [繁體中文](docs/i18n/README.zh-TW.md) · [日本語](docs/i18n/README.ja.md) · [한국어](docs/i18n/README.ko.md) · [Español](docs/i18n/README.es.md) · [Português](docs/i18n/README.pt-BR.md) · [Русский](docs/i18n/README.ru.md)

add-reasoning-to-prs

**Self-documenting PRs.** A [Claude Code](https://docs.claude.com/en/docs/claude-code) hook that writes the *why* — decisions, trade-offs, assumptions, limitations — into every pull request, automatically. Composed by your own agent, on your own machine.

[![npm](https://img.shields.io/npm/v/add-reasoning-to-prs.svg)](https://www.npmjs.com/package/add-reasoning-to-prs) [![CI](https://github.com/backthread/add-reasoning-to-prs/actions/workflows/ci.yml/badge.svg)](https://github.com/backthread/add-reasoning-to-prs/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-8A63D2.svg)](https://docs.claude.com/en/docs/claude-code)

![Before and after: a PR titled "update auth flow" with an empty description, next to the same PR with a generated Decisions / Trade-offs / Assumptions / Limitations block.](assets/demo.gif)

AI writes your code. Nobody writes down *why*. Three weeks in, your git history is a pile of decisions you technically own but never actually made — the diff says *what* changed, `git blame` says *who*, and the reasoning is just… gone.

This is a hook that fixes that at the source: right before your agent opens a PR (or lands a commit on your default branch), it writes a short **"why" block** — the decisions it made, the trade-offs it weighed, what it assumed, and what it knowingly left — straight into the description. From the actual session. Not the diff.