Skip to content

Favor structured PR descriptions and review comments #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
letsrokk merged 1 commit into from
Sep 7, 2026
Merged

Favor structured PR descriptions and review comments #44

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions plugins/read-the-room/skills/make-it-make-sense/references/version-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,17 @@ Use the contract for the requested artifact:

- **Commit:** Use a conventional single-line subject. Apply a required ticket prefix when repository instructions or the branch establish one. Add a body only for context a future maintainer cannot recover from the diff.
- **Pull or merge request title:** State the delivered outcome in the repository's established form. Keep required ticket prefixes exact.
- **Pull or merge request description:** Present the delivered behavior, why it changed, verification evidence, and material risks or areas reviewers should inspect.
- **Review comment:** Lead with the finding or requested change. Give precise evidence, impact, and the reason for the request. When reporting a response to feedback, state the action taken and its result. State whether the finding blocks. Use a plain approval when there is no finding.
- **Pull or merge request description:** Use short sections such as Summary, Verification, and Risks when relevant, with concise bullets for delivered behavior, necessary rationale, checks, and reviewer concerns. Follow repository templates; omit empty or unnecessary sections.
- **Review comment:** Lead with the finding or requested change and whether it blocks. For findings needing explanation, use concise bullets for evidence, impact, and the requested action rather than several prose paragraphs. When responding to feedback, state the action taken and its result. Use a plain approval when there is no finding.
- **Discussion reply:** Answer the point raised with the decision, evidence, fix, or remaining blocker.

## Structure

- Prefer sections and bullets over long paragraphs in PR/MR descriptions and reviews. Keep one point per bullet; avoid turning paragraphs into long bullet items.
- Use tables when comparing alternatives, before/after behavior, or several checks with the same fields. Do not force narrative explanations or a single finding into a table.
- Group multiple findings under descriptive headings. Keep a simple comment or reply to one or two sentences when extra structure would add noise.
- Use brief prose only where connected reasoning makes the point clearer. Do not repeat the same information in prose, bullets, and tables.

Before drafting a pull or merge request description, read the diff. Do not inventory changed files or methods, repeat rationale already documented in code, recount commit history, or assess the work's quality. Include rationale only when it affects review or is not recoverable from the diff.

Describe delivered work. Mention a rejected option only when it explains a material constraint a reviewer would otherwise encounter.
Expand Down
Loading