skills.rest
brandonarbini
brandonarbiniCOMMUNITY
Explore all skills by this author →
GitHub

decision-comments

Writes code comments, READMEs, and commit messages that record decisions and rationale.

Updated Jan 12, 2026
Search Tags:#code review#documentation#commit messages#maintainability#readme#code comments#decision records
One-click install
npx skills add https://github.com/brandonarbini/arbini.family --skill decision-comments-brandonarbini
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: decision-comments
Source: https://github.com/brandonarbini/arbini.family/tree/main/.agents/skills/decision-comments
Command: npx skills add https://github.com/brandonarbini/arbini.family --skill decision-comments-brandonarbini

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Code comments often restate what the code already says, while the real reasons behind workarounds, version pins, and magic numbers get lost — leaving future maintainers unable to reconstruct why a line exists or afraid to change it. ## Core Features & Use Cases - Decision-focused commenting: Guides you to document why a line exists, name the rejected alternative, and record the symptom (error strings, environments) so future searches hit the comment. - Load-bearing invariant documentation: Helps you state which rules are non-negotiable, where they are enforced, and what breaks if they are relaxed. - Single-sourcing authority documents: Prevents drift by quoting specifications verbatim instead of paraphrasing them, and locking selections with tests. - Use Case: A reviewer asks "why is this retry here?" — use this Skill to write a comment naming the rejected alternative, the production-only failure symptom, and what breaks if the line is removed. ## Quick Start Ask the AI to review this workaround and write a comment explaining why it exists and what breaks if it is removed.

Frequently Asked Questions about decision-comments

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a good code comment for a workaround?▼

A good workaround comment names the rejected alternative and why it failed, records the symptom (error string, environment, production-only behavior), and states what breaks if the line is removed. Place it directly at the decision site, not in a distant README.

What should a commit message include?▼

A commit message should say why the change was made and what would otherwise go wrong. The diff already shows what changed, so repeating the mechanism in the message adds no value.

When should I delete a code comment instead of keeping it?▼

Delete a comment when a competent reader who has not seen the failure would not undo the line it describes. If the code is self-evident, the comment is noise and removing it improves the file.

Should I summarize a specification in a README or comment?▼

No — a paraphrase beside a specification becomes a second authority that drifts invisibly. Instead, quote the authoritative document verbatim, omit irrelevant parts, and lock the selection with a test so renames fail loudly.

What belongs in a subsystem README?▼

A subsystem README explains the shape and reasoning: what the pieces are, which decisions are load-bearing, and what will surprise a newcomer. It should not enumerate files, since the directory listing already does that and quickly goes stale.

Related Skills

Explore More Software Engineering Skills→
ambroviaambrovia

lore

Capture and index architectural decisions via @lore annotations.

Official
Intermediate
istinataFTSistinataFTS
2

caveman-commit

Generate Conventional Commits messages with concise imperative subject lines.

Community
Intermediate
hsliuustc0106hsliuustc0106
84

vllm-omni-review

Review vllm-omni PRs for code quality, tests, and security issues.

Community
Advanced
videojsvideojs
931

write-design-doc

Writes compact Video.js architecture and decision records with non-inferable rationale.

Official
Basic