recall-commit

description	Commit with inline learning capture for Recall Labs projects.
metadata	{"github-path":"skills/recall-commit","github-ref":"refs/tags/v1.1.0","github-repo":"https://github.com/recallnet/recall-skills","github-tree-sha":"47f0db918aaf9e4ee3e914053b753a2ebca03984"}
name	recall-commit

Recall Commit

Conventional commit with built-in learning capture. One commit, one atomic unit of work + knowledge.

When This Skill Applies

• User says "/recall-commit", "/commit", "commit this", or any variant requesting a commit
• This is the default commit flow for all Recall Labs projects — if the guard check passes, use this skill for every commit

Guard

Verify this is a Recall Labs project:

git remote -v 2>/dev/null | grep -q recallnet || test -f learnings/AGENT-LEARNINGS.md || test -f AGENT-LEARNINGS.md

Check ALL remotes, not just origin. If neither condition is true, warn: "This doesn't appear to be a Recall Labs project (no recallnet remote, no learnings/AGENT-LEARNINGS.md). Use a standard commit instead." Allow the user to override if they confirm they want to proceed.

Context

Gather before starting:

• git status
• git diff HEAD
• git branch --show-current
• git log --oneline -5

Procedure

Phase 1: Stage & Compose

Stage changes:

• If nothing staged, stage all relevant changes. Use git add -A for broad changes; use specific files when only a subset should be committed.
• Never stage secrets (.env, credentials.json, *.pem). Warn if requested.

Compose commit message:

Subject line (50 chars max):

type(scope): imperative description

Types: feat, fix, refactor, test, docs, chore, perf, ci, build, style

Body (wrapped at 72 chars):

## Summary
What and why in 1-2 sentences.

## Changes
- Change 1
- Change 2

## Why
Rationale if non-obvious. Omit if summary is sufficient.

## Testing
How verified. Omit for docs-only changes.

Phase 2: Reflect & Capture

Three steps, in order. Do not skip Step 1 to jump into routing or file-writing. You can't route what you haven't surfaced.

Step 1 — Reflect first (retrieve, don't synthesize)

Pause and scan the session honestly. The goal here is retrieval of specific moments, not a tidy summary of what you accomplished. Read the primers below, then write a short bulleted list of everything that actually surfaces — even half-baked items. Triage happens in Step 2.

Primers — go through each one. If a primer hits nothing, say "nothing" and move on:

1. Surprise. What did you discover that contradicted your initial assumption? What looked right but wasn't? Where did reality diverge from your mental model?
2. Dead ends and false starts. Which approaches did you try and abandon? Why did they fail? (Failure-derived heuristics outperform success-derived ones — the abandoned paths are usually the highest-signal source of learning.)
3. Decision forks. Name 1–3 moments where you chose between plausible alternatives. What were the options? What did you choose? Would you choose the same again knowing what you know now?
4. Gotchas and hidden constraints. What tripped you up — or nearly did? What non-obvious constraint, dependency, or quirk shaped the solution?
5. User corrections. Where did the user steer you, push back, or override you? Those moments are signal that your prior was wrong.
6. Ephemeral context. What knowledge influenced this change that currently lives only in this session and is not captured in any file? If a future agent only saw the diff, what would they misunderstand?
7. Pre-mortem. Assume this code causes a regression or confuses the next agent in 90 days. What is the single most likely reason?
8. Machine gaps. Did this session reveal a missing guardrail, lint rule, skill, standard, or doc that should have caught the issue earlier? Recurring pain points should become guardrails, not notes.

If the user explicitly flagged something during the session ("log this learning: …"), include it alongside your own findings.

Zero findings is valid output. Do not fabricate to seem productive. But before declaring zero, check: did you actually run through every primer above, or did you skim?

Step 2 — Triage each finding into its highest-impact action

For each item from Step 1, pick the strongest loop-closing action it qualifies for. Earlier options close the loop more decisively than later ones — prefer earlier when it's a real fit:

1. Fix it now (this commit). A one-file change, config tweak, skill edit, pre-commit gate, lint rule, ADR, or guard that takes <5 min. Make the change, stage it, include in this commit. → trailer: Closes-Loop-Via: commit:this
2. Annotate the code. Context that a future reader needs at a specific spot — add a // @context: comment in the file at the right line. → trailer: Closes-Loop-Via: annotation:<file>:<line>
3. File an issue. Cross-repo or larger work. Use the issue-filing skill. Targets: reusable-package gap / venue bug / DX friction in @recallnet/* → recallnet/tradecore. Gap in skunkworks-template (AGENTS.md, hooks, QA scripts, template structure) → recallnet/skunkworks-template. → trailer: Closes-Loop-Via: issue:owner/repo#N
4. Capture as a learning entry (Step 3 below). Use this when there is no single file to fix, no obvious annotation site, and no scoped issue — the value is a directive that changes how a future agent approaches a class of problem. Routing: domain / venue / strategy / market-microstructure → learnings/TRADE-LEARNINGS.md. Process / tooling / meta / team-wide → learnings/AGENT-LEARNINGS.md. When in doubt: AGENT-LEARNINGS is how we work, TRADE-LEARNINGS is what markets do. → trailer: Closes-Loop-Via: recommendation:learnings/<file>.md
5. Drop it. A capable agent would overcome this through normal persistence; the answer is in the code or docs; the insight is too vague to produce a directive. Drop without writing.

Stack a learning entry on top of options 1–3 when the insight generalizes beyond this fix. The Tier 1 action closes the immediate loop; the learning entry is what makes the insight discoverable to other agents (other repos, other sessions, Atlas search) and what surfaces recurrence patterns over time. Heuristic:

• The fix is self-documenting (typo, rename, one-line config) → action only.
• The insight applies to other repos / venues / patterns / future agents who share the same wrong prior → action and learning entry. Use the entry's Action: field to record what was already done (e.g., Action: Done in commit:this or Action: Filed as issue:owner/repo#N).

For fix-it-now items where the action isn't tiny: tell the user "This finding suggests [change]. I can make it now and include it in this commit. Want me to?" Closing the loop beats describing it.

Step 3 — Write learnings (only if Step 2 routed anything to a learning entry)

Ensure the target file exists. Check learnings/AGENT-LEARNINGS.md (and learnings/TRADE-LEARNINGS.md if routing there).

• If AGENT-LEARNINGS.md exists at repo root but learnings/ does not: mkdir -p learnings && git mv AGENT-LEARNINGS.md learnings/AGENT-LEARNINGS.md
• If the target file doesn't exist and this is a recallnet repo, create it with the appropriate header (see references/learning-file-headers.md if present, or use the templates below).

learnings/AGENT-LEARNINGS.md initial header

---
doc_type: reference
owner: all-agents
status: active
review_policy: periodic-7
reviewed: YYYY-MM-DD
summary: Cross-cutting process, tooling, and meta learnings from agent sessions.
tags: [agent-learnings, meta]
---

# Agent Learnings

Cross-cutting insights from AI agent sessions. These are learnings that
don't belong in a specific doc but help future agents work smarter.

Atlas indexes this file nightly for semantic search across the team.

Each entry includes a directive: a concrete "Do X, not Y" instruction.
Entries marked `hypothesis` have low conviction — not subject to freshness gate.
Entries tagged `meta` are cross-cutting (not repo-specific) and surfaced team-wide.

---

<!-- Entries below, newest first -->

learnings/TRADE-LEARNINGS.md initial header

---
doc_type: reference
owner: all-agents
status: active
review_policy: periodic-7
reviewed: YYYY-MM-DD
summary: Domain, venue, strategy, and market-microstructure learnings from agent sessions.
tags: [trade-learnings, domain]
---

# Trade Learnings

Venue gotchas, denomination rules, integration constraints, strategy insights,
and market-microstructure findings from agent sessions.

Atlas indexes this file nightly for semantic search across the team.

Each entry includes a directive. Use `(hypothesis)` for low-conviction signal.

---

<!-- Entries below, newest first -->

If the target file already has uncommitted changes (likely from a prior failed commit attempt), warn the user and append new entries after the existing uncommitted ones — do not skip:

git diff --name-only learnings/ 2>/dev/null
git diff --cached --name-only learnings/ 2>/dev/null

Get the author name once: git config user.name

Insert entries with the Edit tool (not Write) — replace the <!-- Entries below, newest first --> marker with itself plus the new entries, so existing content is preserved without rewriting the file:

### YYYY-MM-DD — Summary sentence (confirmed, gotcha)

Author: [git config user.name]
Insight: One sentence stating the key implication — why this matters and what it changes about how you'd approach the problem.

Detail: The specific context, evidence, or mechanism behind the insight. What happened, what you tried, what the constraints were.

Directive: Do X, not Y.
Action: What should change in the machine? (e.g., "Add pre-commit check for X", "Update team standard to require Y", "No machine change needed — directive is sufficient"). Every learning must close the loop.
Applies To: [paths, systems, or workflows this affects]
Context: branch, what was being done

Type tags (pick the closest match): gotcha · dead-end · fragile-area · codebase-state · tool-quirk · hypothesis (low-conviction signal — Directive and Action are optional; not subject to freshness gate).

Cross-cutting (not repo-specific) entries add , meta to the tag:

### YYYY-MM-DD — Summary sentence (confirmed, gotcha, meta)

Lead with the Insight line — a reader scanning the file should understand the implication without reading the full detail.

Stage the file(s):

git add learnings/AGENT-LEARNINGS.md   # and/or learnings/TRADE-LEARNINGS.md

Anti-patterns — do NOT produce:

• Restating what the code does (the diff is readable)
• Summarizing what you accomplished (a learning changes future agent behavior; a summary describes past agent behavior — only the first one belongs here)
• Tactical recoveries a capable agent would solve through normal persistence ("command X fails, use Y instead")
• Vague advice without specifics ("be careful with X")
• Entries missing the Insight line — detail without implication is noise
• Entries missing Directive + Action (except hypothesis) — every learning must close the feedback loop
• Fabricated learnings to seem productive — zero is valid

Phase 3: Commit

For feat: or fix: commits, include a Closes-Loop-Via: or No-Learning: trailer in the commit message body to document how the learning loop was closed (or why it wasn't applicable). Multiple Closes-Loop-Via: trailers are valid — list one per closure when both an action was taken and a learning was captured:

Closes-Loop-Via: issue:recallnet/tradecore#N       ← filed a TradeCore issue
Closes-Loop-Via: issue:recallnet/skunkworks-template#N ← filed a template issue
Closes-Loop-Via: annotation:<file>:<line>          ← added @context annotation
Closes-Loop-Via: commit:this                       ← fixed it directly in this commit
Closes-Loop-Via: recommendation:learnings/AGENT-LEARNINGS.md ← wrote a learning entry
Closes-Loop-Via: recommendation:learnings/TRADE-LEARNINGS.md ← wrote a trade learning
No-Learning: <reason>                              ← refactor / dep bump / style / no new knowledge

Execute via HEREDOC:

git commit --quiet -m "$(cat <<'EOF'
type(scope): subject line

## Summary
...

Closes-Loop-Via: <value>
EOF
)"

If pre-commit hooks fail: fix the issue, re-stage, and create a NEW commit. Never amend — amending after a hook failure modifies the previous commit, not the failed one.

Run git status to confirm success.

Rules

• Never fabricate learnings. Zero is valid.
• Never amend after hook failure.
• Never commit secrets.
• Always use HEREDOC for commit messages.
• Learnings are the agent's own reflection. Do not ask the user to reflect.