quatico-solutionsquatico-solutions/agent-skills/skills/commit-notation/SKILL.md

commit-notation

Skill2 starsChanged 4 months agoMITView on GitHub

Format git commit messages using Quatico's notation (Arlo's v1 with extensions). Use when: committing changes, making commits, creating commits, writing commit messages, reviewing commits, or analyzing git log. Triggers: commit, make commit, create commit, git commit, commit this, commit message, commit notation, Arlo notation.

In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adopt-agentic-workflowSkill
- branch-and-commitSkill
- byeSkill
- commitSkill
- dedicated-browserSkill
- handling-pull-requestsSkill
- jest-testing-conventionsSkill
- markdownSkill
- pnpmSkill
- reality-checkSkill
- schweizer-schreibweiseSkill
- show-your-workSkill
- test-driven-developmentSkill
- triage-ticketSkill
- typescript-strict-patternsSkill
- working-with-bitbucket-apiSkill
- working-with-bitbucket-webSkill
- working-with-jira-webSkill

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Validated (UPPERCASE): Test-verified - ran tests, all pass.
line 49
Very specific:
Check branch name: Look for pattern like XXX-123
line 113
Distinctive:
Check recent commits: If not in branch name, check commits not yet merged to main:
line 118
Distinctive:
Ask user: If still not found, ask:
line 123

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Commit Notation

Source of truth: QuaticoCommitNotation (GitHub) SYNC REQUIRED: Changes here MUST stay consistent with the canonical repo. Changes incomplete without sync.

Quatico uses Arlo's Commit Notation v1 with extensions (T, E).

Quick Reference

Risk Level	Format	Example
Known Safe	`x`	`r Extract method getData`
Validated	`X`	`R: Extract method getData`
Risky	`X!!`	`R!! Rename across files`
Broken	`X**`	`F** WIP: new feature`

Intentions

Core

Letter	Name	Use When
F	Feature	Adding or changing behavior
B	Bugfix	Fixing broken behavior
R	Refactoring	Changing implementation, not behavior
D	Documentation	Non-code documentation changes

Extensions

Letter	Name	Use When
T	Test-only	Alter tests without altering functionality
E	Environment	Dev setup, tooling, non-code changes
WIP	Unknown	Mixed changes, just checking in

Risk Level Guidelines

Known Safe (lowercase): Provable correctness - tool-verified refactoring, type-checked renames. Validated (UPPERCASE): Test-verified - ran tests, all pass. Risky (XX!!): Attempted but not fully verified. Broken (XX)**: WIP, may not compile, no verification.

Commit Message Format

X: Summary in active voice

TICKET-123

Rules:

Separator: : or nothing (e.g., F: Add feature or F Add feature)
Voice: Active ("Add feature") not progressive ("Adding feature")
Length: Subject < 75 chars
Ticket: Last line, blank line before, NO # prefix (git treats # as comment)

Writing Commit Messages

Determine intention: F, B, R, D, T, E, or WIP
Assess risk level: How verified is this change?
Find ticket number: See below
Format: [prefix] Summary with ticket on last line

Keep changes small: Features/bugfixes should be ≤8 LoC for Validated level.

What the subject should name

A fix names the defect. A feature names the outcome.

These pull in opposite directions, and applying one rule to both produces euphemism. The outcome of a fix is "it works again", which tells a reader nothing.

	Weak	Strong
`B`	`B: Unblock the build that the new check stopped`	`B: Stop the license check failing every build on the docs package`
`B`	`B: Ship types a consumer can compile against`	`B: Export the parser types that consumers need to type-check`
`F`	`F: Add a script that writes the exports map`	`F: Generate the exports map from the barrel directories`

The tell in a weak fix subject is an abstract subject carrying a relative clause — "unblock the build that …", "ship the files that …". It reports that something improved without naming what was broken.

Someone scanning git log for the cause of a red build should find it in a subject line. Name what fails, where, and how widely.

Quick Checklist

Copy and track progress:

Intention identified (F/B/R/D/T/E/WIP)
Single intention per commit
Risk level assessed (lowercase/UPPER/!!/**)
Active voice summary
A fix names the defect; a feature names the outcome
Subject < 75 chars
Ticket on last line (if applicable)

Ticket Numbers

Finding the Ticket

Check branch name: Look for pattern like XXX-123
- FOO-123-my-bugfix → FOO-123
- bugfix/FOO-123-description → FOO-123
- feature/BAR-456-new-feature → BAR-456
Check recent commits: If not in branch name, check commits not yet merged to main:
```
git log origin/main..HEAD --oneline
```
Ask user: If still not found, ask:
- Is this an infrastructure change (leave empty)?
- What's the ticket number?

When to Omit Ticket

Infrastructure changes may omit tickets:

CI/CD pipeline fixes
Development environment setup
Release version bumps
Dependency updates
Code formatting/linting

Examples

F: Add user authentication endpoint

FOO-123

B!! Fix race condition in event handler

BAR-456

r Extract method calculateTotal

FOO-123

D: Update CI pipeline documentation

See REFERENCE.md for full notation details and risk level criteria.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free