# Prose Review

Check that added comments, docstrings, and changelog entries document the code rather...

- Repository: https://github.com/pipecat-ai/pipecat (16982 stars)
- Category: Git and review
- License: BSD-2-Clause
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add pipecat-ai/pipecat --skill prose-review -g -a claude-code -y`
Codex: `npx skills add pipecat-ai/pipecat --skill prose-review -g -a codex -y`
Cursor: `npx skills add pipecat-ai/pipecat --skill prose-review -g -a cursor -y`
Gemini CLI: `npx skills add pipecat-ai/pipecat --skill prose-review -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add pipecat-ai/pipecat`

## Description

Check that added comments, docstrings, and changelog entries document the code rather than narrate the change that produced it

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

Review the prose this work adds, comments, docstrings, changelog entries, against
the "Writing for Future Readers" section of `AGENTS.md`, which is the authority.
This skill is the operational check.

The reader you are writing for has never seen this change. They open the file
months from now and see only the code as it stands. Detail that feels important
while making a change, what the code used to do, why an alternative was
rejected, that the fix was verified, is invisible context to them, and often
actively misleading.

## Scope

| Argument | Diff to review |
| --- | --- |
| `staged` | `git diff --cached -U0` |
| `branch` (default) | `git diff $(git merge-base main HEAD) -U0` |
| `<path>` | `git diff $(git merge-base main HEAD) -U0 -- <path>` |

The `branch` and `<path>` scopes diff against the merge base, so they cover
committed *and* uncommitted work, prose written moments ago still needs review.

Review **added lines only** (`^\+`): comments, docstrings, and any
`changelog/*.md` content. Untouched prose is out of scope. Read the surrounding
code for each hit, the judgment depends on what the code already shows.

## The Test

For each added line, ask: **does this describe the code as it now stands, or does
it narrate the change that produced it?**

Rewrite or delete anything that:

- Describes what the code used to do, or contrasts old behavior with new
- Argues the change is correct, or records that it was tested or verified
- Names an alternative that was considered and rejected
- Only restates what the adjacent code already shows
- Uses shorthand that made sense mid-task but won't to someone reading cold

Rationale survives only when its absence would puzzle a future reader, a
constraint or non-obvious decision the code itself cannot express. Keep those,
and prefer stating the constraint over recounting the discovery.

## Calibration

The rest: https://github.com/pipecat-ai/pipecat/blob/HEAD/.claude/skills/prose-review/SKILL.md