Git Conventions

Git Conventions

The Lossless Group's conventions for git commit messages — making history readable, searchable, and useful for future-you.

Status: Initial scaffold (May 2026) — documenting observed patterns from lossless-monorepo.

When to use this skill

• Writing commit messages (any repo)
• Reviewing commits before push
• Teaching commit conventions to collaborators
• User asks "how should I format this commit?"
• User mentions "commit message", "git conventions", "effort grouping"

Core Patterns

1. Header Syntax

Two accepted patterns:

Pattern A: Single effort grouping

{action}({effort-grouping}): {narrative description}

Pattern B: Multiple effort groupings or chained actions

{action}({effort-1}, {effort-2}): {narrative description}
{action}({effort-1}), {action}({effort-2}): {narrative description}

Examples:

feat(theme-system): Add vibrant mode verification checklist
fix(mode-switcher, theme.css): Vibrant mode now dark-based with neon effects
doc(README), skill(astro-knots): Update vibrant mode guidance

2. Common Action Verbs

3. Effort Groupings

What is an effort grouping? The part of the codebase this commit touches — a package, a site, a system, a concern.

Examples:

• skill(theme-system) — changes to theme-system skill
• feat(reach-edu-hub) — new feature in reach-edu-hub site
• fix(mode-switcher, theme.css) — bug fix touching both files/systems
• doc(README, CANDIDATES) — documentation changes in both files

Guideline: Use the most specific grouping that makes sense. If a commit touches multiple unrelated areas, consider splitting into multiple commits.

4. Body Structure (The Important Part)

Rule: Use paragraph spacing to separate concerns. Do not lump.

Structure:

1. First paragraph: Sense-making summary
   Anyone (future-you, a new contributor, a stakeholder) should understand what this commit does and why.

2. Second paragraph: Impact
   What changes does this commit introduce? Focus on what the changes do, not how they're implemented.

3. Third+ paragraphs: Breakdown by concern
   Cluster related changes. One paragraph per cluster. Each paragraph explains a cohesive set of changes.

4. Affected files list
   List files changed that align with the header. Makes git log searchable.

5. "Also included:" section (optional)
   Minor changes, formatting tweaks, riders that aren't worth their own commit. Keeps commit history clean.

Example structure:

fix(mode-switcher, theme.css): Vibrant mode now dark-based with neon effects

Problem: Light and vibrant modes were indistinguishable because vibrant
mode only set effect tokens and inherited light mode's white background.

Solution: Vibrant mode now comprehensively overrides all surface/text/border
tokens. Uses color-mix() for glassmorphic surfaces, multi-color neon gradients
(lime → cyan → blue → violet), and high glow opacity (0.55 vs 0.22 in dark).

CSS changes (theme.css):
- Added named tokens for vibrant palette (cyan-bright, violet-deep, lime-terminal)
- Vibrant mode block now sets background, surface, text, border
- Multi-stop gradient definition for headlines

Mode switcher (mode-switcher.js):
- No changes needed — switcher already supported three modes

Files changed:
- src/styles/global.css
- src/pages/brand-kit/index.astro

Also included:
- Fixed typo in README
- Removed debug console.log from Header.astro

5. Pre-Commit Checklist: Changelogs & Context-v

Before you commit, CONSIDER (don't assume) two things:

Should a changelog be written?

When to write a changelog:

• At the conclusion or final stages of a coherent flow of work
• When implementing a spec or completing a sequence of related prompts
• When something of substance changed that matters to humans, the team, or users

Frequency expectations:

• 1 or fewer per day = meeting expectations
• Up to 5 per day on heavy shipping days
• It depends on the coherence of the commit set

Why this matters:

• Changelogs are a trust-reinforcing rhythm
• They're breadcrumbs on progress/decisions/changes of substance
• They're for humans, not machines

Common mistake: Rushing to commit without considering if a changelog is needed, then having to make a tiny "oops(changelog): add missing entry" commit or amend+force-push. Causes drag.

Do README or context-v files need updating?

Not a hard rule, but worth considering:

• Has the project's purpose shifted? Update README.
• Did we make decisions that should be documented? Update context-v/ files.
• Are specs, blueprints, or prompts now stale? Flag or update them.

Why this matters:

• Keeps context-v/ accurate to current thinking and practice
• Prevents future confusion about why decisions were made
• Reduces "wait, why did we do it this way?" conversations

Common mistake: Same as changelogs — rushing to commit, then realizing context is stale, then making an "oops(context-v): update stale spec" commit.

Do NOT bump the parent pseudomonorepo's submodule pointer

Not per commit. Not per push. Once, at wrap-up.

Committing in a submodule dirties the parent's recorded gitlink immediately. It is tempting to "tidy" that by committing the parent too — resist it. On a working day with twenty child commits, that habit produces twenty parent commits whose entire content is a pointer moved, burying the handful of parent commits that actually say something.

The working rhythm:

1. Work in the child repo. Commit and push there as often as the work warrants.
2. Leave the parent's M <submodule> dirty. This is the expected mid-session state, not a problem to fix.
3. At wrap-up — end of session, end of day, or when handing off — bump the parent pointers once, in a single chore(submodule): bump <names> commit.

When this does not apply: if someone else is working the same parent concurrently, their clone resolves whatever pointer you last pushed, so a stale pointer can hand them a checkout that does not match the work you described. Bump more eagerly when collaborating. The once-at-wrap-up rhythm assumes a single operator on the tree, which is the common case here.

Corollary for agents: do not offer to commit parent pointers mid-session, and do not treat a dirty gitlink as an error worth reporting. Mention it at wrap-up or when asked.

The discipline: Pause before git commit. Ask:

1. Is this the end of a coherent flow of work? → Consider changelog.
2. Did we make decisions or changes that shift context? → Consider updating context-v/ or README.

If yes to either, do it in the same commit or before committing. Don't rush.

6. Key Principles

Sense-making first: The first paragraph should explain what and why in plain language. Assume the reader knows nothing about the context.

Impact over implementation: Explain what changes, not how you changed it. "Vibrant mode now dark-based" (impact) before "Changed --color-surface value" (implementation).

Paragraph spacing matters: Blank lines between concerns makes commits scannable. Lumped paragraphs are hard to parse.

List riders explicitly: If you're sneaking in unrelated changes (typo fix, debug cleanup), list them under "Also included:" so they don't pollute the main narrative.

Affected files consistency: Files listed should match the effort groupings in the header. If the header says (mode-switcher, theme.css), those files should appear in the body.

Pre-Commit Anti-Patterns

❌ Rush to commit without considering changelog:

git commit -m "feat: implement new feature"
# Later: "Oh, I should have written a changelog"
# Now: Either make tiny oops commit or amend+force-push

✅ Pause, consider, include if needed:

# Write changelog entry if this completes coherent work
vim changelog/2026-05-04_02.md
git add changelog/
git commit -m "feat: implement new feature

See changelog/2026-05-04_02.md for details."

❌ Rush to commit with stale context-v:

git commit -m "refactor: change approach"
# Later: "The spec is now wrong"
# Now: Either update separately or amend

✅ Update context-v in same commit:

# Update stale spec while making the change
vim context-v/specs/Feature-Spec.md
git add context-v/
git commit -m "refactor: change approach

Updated spec to reflect new implementation strategy."

Common Mistakes (Headers & Bodies)

❌ Vague headers:

fix: updates
feat: changes to theme

✅ Specific headers:

fix(mode-switcher): Vibrant mode toggle now persists to localStorage
feat(theme-system): Add two-tier token architecture reference

❌ Lumped body:

Fixed vibrant mode and also updated docs and added new tokens and fixed a typo in README and changed the mode switcher and...

✅ Paragraph-spaced body:

Fixed vibrant mode by making it dark-based instead of light-based.

Theme changes:
- Added cyan-bright, violet-deep, lime-terminal named tokens
- Vibrant mode block now sets all surface/text/border tokens

Documentation:
- Updated setup playbook with vibrant verification checklist
- Added examples to quickstart guide

Also included:
- Fixed typo in README

Push-output gotchas

GitHub's Dependabot banner is unreliable — don't surface it as actionable

When git push completes, GitHub may print a remote: banner like GitHub found N vulnerabilities on <repo>'s default branch. Treat this as noise, not signal. Observed on lossless-group repos:

• The banner count is computed independently of the Dependabot alerts UI and drifts from it; counts stay pinned for weeks after the underlying lockfile entries are gone.
• It fires even when Dependabot is disabled for the repo.
• Walking through the listed advisories with Claude Code and resolving the lockfile entries has not moved the banner count in practice.

Don't raise it to the user as a follow-up action on an unrelated push (e.g. a marketplace-compliance push). If the user is actively working on dependency hygiene, that's a different conversation.

Cross-skill ties

• changelog-conventions — commit messages often become changelog entries
• context-vigilance — commit message structure mirrors document frontmatter discipline

Commit messages also serve four audiences

Commit messages surface publicly via the GitHub commits view, via push-time release notes, via the parent pseudomonorepo's rolled-up changelog feed, and via search engines indexing the commit pages. They carry the same four-audience discipline that changelog-conventions codifies for README.md, changelog entries, and release narratives:

1. General audience — the header has to land in two seconds (a passer-by reading the repo's commits page should grok what shipped)
2. Nerds passing by — the first body paragraph should explain what changed and why it matters, in human terms (not just a file-diff narration)
3. Nerds paying close attention — subsequent paragraphs name specific files, behaviors, edge cases, and any non-obvious decisions
4. Internal team — the tail can carry SHAs, Co-Authored-By, ticket numbers, follow-up notes

Same principle as the long-form docs: sequence the content from broadest to most-specific so each reader gets dropped at the right station. The pre-commit checklist (§5) and the body-structure conventions (§4) already encode much of this in mechanics; the audience cascade is the framing that makes the why legible.

For the full framing (including the "long files are fine if you stamp a TOC" rule that applies to release narratives), see the changelog-conventions skill, section "These are marketing artifacts, not internal documentation".

What's Not Here Yet (TBD)

• references/header-patterns.md — comprehensive action verb + effort grouping catalog
• references/body-structure.md — deep dive on paragraph spacing and impact-first writing
• references/examples.md — 10+ real commit messages from lossless repos annotated
• templates/commit-message-template.txt — boilerplate for git commit.template

Development Notes

This skill is being extracted from commit history across:

• lossless-skills repo
• astro-knots monorepo
• Individual site repos (reach-edu-hub, fullstack-vc, etc.)

Observed patterns will be documented incrementally.

See also

• Changelog conventions skill (similar structured writing discipline)
• Context-vigilance skill (frontmatter structure parallels commit headers)