commit-messages
Commit messages
When suggesting or writing commit messages for this repo, follow these rules.
Format
- Use Conventional Commits. Prefer the form
type(scope): descriptionortype: description. Keep the type to a set that tools like Release Please recognise:feat,fix,docs,style,refactor,perf,test,build,ci,chore. Scope is optional; use it when it helps (e.g.feat(graphql):,fix(data-sourcing):). - Subject line: Imperative mood, lowercase after the colon. Write it so it would make sense in a changelog on its own (e.g.
feat: add whitelisting_rules querynotfeat: added whitelisting_rules queryorfeat: Adding the whitelisting rules query). - Jira/ticket refs: Only reference a ticket (e.g.
SIM-652) in the subject or body if this commit fully resolves that ticket. Otherwise omit. - Merge commits: Leave merge commit messages as-is; do not rewrite them.
Body
- When to add a body: Only for non-trivial commits. Small, obvious changes do not need a body.
- Style: Prefer short, concise bullet points. Focus on what matters to the end user or to the project’s architecture; avoid narrating every file or line changed.
- Length: Keep the message reasonable. Nobody wants to read an essay.
Examples
Good (subject only):
feat(graphql): add whitelisting_rules queryfix: upgrade OpenSSL in Docker images to fix CVE-2025-69421chore: add dependency on ddtrace
Good (with body for non-trivial change):
refactor(graphql): split schema into domain modules
- common.py: GlobalID, Blob, PageInfo, Connection, decode_id
- culling.py: CulledDocument, get_culled_documents, WhitelistingQuery
- documents.py: Document, Filters, DocumentsQuery
- schema.py: composes Query, schema, graphql_app
Public API unchanged.
Avoid:
- Past tense or sentence case in subject:
Added foo,Updates the bar - Ticket ref when the commit doesn’t close the ticket
- Long, story-style bodies for trivial changes
- Capitalised word after the colon (except proper nouns)
- Do not mention that a commit was co-authored by Cursor in the commit message or trailer.
More from michael-f-bryan/skills
long-running-agent-harness
Plans and structures large-scale work for AI agents across many sessions. Human and AI iterate to produce a design doc; run an Initializer sub-agent once to create feature list, runbook, and backlog in _working/; then repeatedly run a Coding sub-agent until all features pass. At milestones (e.g. end of a work-unit group), pause for human check-in, re-run Initializer, then continue. Prompts are passed to sub-agents when spawning (no copying into .cursor/rules). Use when planning multi-session agent work, long-horizon coding from a design, or handoff between coding sessions.
31doc-coauthoring
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
23working-docs
Use when handling multi-step tasks, investigations, or long sessions where working notes, interim findings, and scratch planning are needed to keep context and handoffs clear.
22test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
19code-like-michael
Write, refactor, and review code in Michael's style; explicit contracts, thin entrypoints, practical boundaries, anti-ceremony abstractions, deterministic tooling, and architecture that scales from function internals to repository shape.
14wikilinks
When generating or editing markdown content, actively look for existing pages to link to and incorporate relevant wikilinks so content is interconnected. Use when writing notes, docs, or any .md content.
13