activememory/ctx/ctx-commit

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 <jane@example.com>

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>
└──────────────────────────────────────────