ctx-commit

name	ctx-commit
description	Commit with context persistence. Use instead of raw git commit to capture decisions and learnings alongside code changes.

Commit code changes, then prompt for decisions and learnings worth persisting. Bridges the gap between committing code and recording the context behind it.

When to Use

• For ALL commits. This is the only way to commit in this project. Raw git commit bypasses spec enforcement and violates CONSTITUTION.
• When the user says "commit", "commit this", "ship it", "let's commit": always use this skill, never raw git commit.

When NOT to Use

• When nothing has changed (no staged or unstaged modifications)

Usage Examples

/ctx-commit
/ctx-commit "implement session enrichment"
/ctx-commit --skip-qa

Process

1. Check CONSTITUTION for commit rules

Read .context/CONSTITUTION.md (if it exists) for commit-specific rules. Common project rules to look for and enforce:

• Spec-per-commit: Add a Spec: trailer, verify a spec file exists in specs/ before proceeding. If no spec exists, stop and offer to run /ctx-spec to scaffold one.
• DCO sign-off: every commit needs a Signed-off-by: trailer. Commit with git commit -s so it is appended from the configured git identity; do not hand-type it. Never add a Co-Authored-By: or any agent/tool sign-off: it is prohibited even if a harness default suggests one. See CONSTITUTION "Process Invariants" (the commit DCO / trailer rules), and mirror the trailer convention you find in git log -5 --format=%B before your first commit.
• Other trailers: Honor any project-specific trailer requirements.

Read CONSTITUTION fully and apply all relevant rules before proceeding to pre-commit checks.

2. Pre-commit checks

Unless the user says --skip-qa or "skip checks":

• Run git diff --name-only to see what changed
• Run the project's build and lint commands to verify nothing is broken. Check for a Makefile, package.json, or equivalent. If you cannot identify the build/lint commands, ask the user before proceeding.
• If the build or lint fails, stop and report: do not commit broken code

Verify before claiming ready: map each claim to evidence. "Tests pass" requires test output with 0 failures. "Build succeeds" requires exit 0. "Lint clean" requires linter output with 0 errors. Run commands fresh; never reuse earlier output. Before proceeding to stage, answer these self-audit questions:

1. What assumptions did I make?
2. What did I NOT check?
3. Where am I least confident?
4. What would a reviewer question first?

If any answer reveals a gap, address it before staging.

3. Close matching tasks

Every commit closes work. Before staging, check TASKS.md for tasks that this commit completes:

• Read .context/TASKS.md
• Identify the spec being committed (the Spec: trailer value)
• Find open tasks ([ ]) whose Spec: field matches
• If no spec match, search by keywords from the commit subject
• Mark matching tasks [x]
• If uncertain whether a task is fully done, ask the user
• Stage the updated TASKS.md alongside the code changes

This is the closure point in the plan→spec→task→commit chain. Skipping it causes task rot: completed work stays open, future sessions waste time re-triaging stale items.

4. Stage and commit

• Review unstaged changes with git status
• Stage relevant files (prefer specific files over git add -A)
• Craft a concise commit message:
  • If the user provided a message, use it
  • If not, draft one based on the changes (1-2 sentences, "why" not "what")
• Add the Spec: trailer, and commit with git commit -s so the Signed-off-by: DCO trailer is appended automatically (see format below). Never add a Co-Authored-By: / agent sign-off.

5. Context prompt

After a successful commit, ask the user:

Any context to capture?

• Decision: Did you make a design choice or trade-off?
• Learning: Did you hit a gotcha or discover something?
• Neither: No context to capture: we're done.

Wait for the user's response. If they provide a decision or learning, record it using the appropriate command:

ctx decision add "Use PostgreSQL" \
  --session-id abc12345 --branch main --commit 68fbc00a \
  --context "Need a reliable database" \
  --rationale "ACID compliance and JSON support" \
  --consequence "Team needs training"

ctx learning add "Go embed requires files in same package" \
  --session-id abc12345 --branch main --commit 68fbc00a \
  --context "..." --lesson "..." --application "..."

6. Reflect

After every commit, run /ctx-reflect to capture the bigger picture before moving on. This is mandatory: Skipping reflection is how context gets lost between sessions.

Commit Message Format

Follow the repository's existing commit style. Draft messages that:

• Focus on why, not what (the diff shows what)
• Use lowercase, no period at the end
• Scale detail to match scope: a one-file fix gets 1-2 sentences; a multi-package change gets a summary paragraph plus a bulleted list of what changed and why
• Include any trailers required by CONSTITUTION (e.g., Spec:, Signed-off-by:)

Example:

complete journal-recall merge wiring and cross-cutting cleanup

Wire journal commands through journal/core packages instead of
recall/core. Move importer, lock, unlock, sync cmd packages from
recall/cmd to journal/cmd.

Changes:
- journal/core/{plan,execute,query} are now canonical
- sourcefm/sourceformat renamed to source/frontmatter, source/format
- Magic numbers extracted to config/stats constants
- state.StateDir renamed to state.Dir across 26 callers
- splitLines moved to parse.ByteLines
- /ctx-commit skill generalized to be language-agnostic

Spec: specs/journal-merge-completion.md
Signed-off-by: Jane Doe <[e-mail]>

Commit Discipline

• Spec trailer is mandatory: identify the spec that covers this work and include Spec: in the commit message. If CONSTITUTION also requires it, this is non-negotiable.
• Confirm the message with the user before committing (or use their provided message)
• Always present the context prompt: this is the whole point of the skill
• Always reflect: even a one-sentence reflection prevents context loss
• Check for secrets (.env, credentials, tokens) in the diff before staging

Quality Checklist

Before committing, verify:

• Spec exists and is referenced in the commit message
• Build and lint pass
• Matching tasks marked [x] in TASKS.md
• Commit message is concise and explains the why
• Spec: and Signed-off-by: trailers are present (the latter added via git commit -s, not hand-typed)
• No Co-Authored-By: or agent/tool sign-off in the message
• No secrets or sensitive files in the staged changes
• Specific files staged (not blind git add -A)

After committing, verify:

• Context prompt was presented to the user
• Any decisions/learnings provided were recorded
• Reflection was completed

Human Relay

After every successful commit, relay a structured summary to the human verbatim:

┌─ Commit Summary ─────────────────────────
│ Spec: specs/<name>.md
│ Tasks closed: <list or "none">
│ Files changed: <count>
│ Message: <first line of commit message>
└──────────────────────────────────────────