cf-warm

name	cf-warm
description	Catch up after absence — summarize git history for a specific user. Use when a user returns after time away from a project and needs to understand what happened — e.g. "warm up", "catch me up", "what happened while I was away", "what did I work on", "summarize recent changes", "what changed since I left", "warm up the project".
created	"2026-03-31T00:00:00.000Z"
updated	"2026-07-04T00:00:00.000Z"
state	beta

$cf-warm

CLI Requirement: OPTIONAL — Uses the memory MCP from coding-friend-cli for fast indexed search and storage. Without the CLI: falls back to grep over docs/memory/ and direct file writes. Full functionality preserved, slower memory recall. See CLI requirements.

Catch up after absence. User input: $ARGUMENTS

Purpose

When you return to a project after being away (vacation, sick leave, context switch), you have no idea what happened. This skill summarizes your recent work and everything the team did since your last commit, grouped by topic/area, so you can quickly get back up to speed.

Folder

Output goes to {docsDir}/warm/ (default: docs/warm/). Check .coding-friend/config.json for custom docsDir if it exists.

IMPORTANT — path resolution:

• Use MAIN_REPO_ROOT from the SessionStart bootstrap context (injected via session-init.sh). If absent, fall back to running pwd for $CWD and use $CWD as MAIN_REPO_ROOT.
• Read config from CF_CONFIG_FILE (= $MAIN_REPO_ROOT/.coding-friend/config.json) — do NOT search sub-folders
• Use CF_DOCS_ROOT as the docs base dir (= $MAIN_REPO_ROOT/{docsDir} where docsDir comes from config, default docs)
• Always resolve file_path as an absolute path: {CF_DOCS_ROOT}/warm/{name}.md
• Never use relative paths in write specs — they may resolve incorrectly when the working directory contains nested git repos

Workflow

Step 0: Custom Guide

Custom guide — auto-loaded below (if the raw command shows instead of its output, run it yourself):

bash "${PLUGIN_ROOT}/lib/load-custom-guide.sh" cf-warm

If output is not empty, integrate returned sections: ## Before → before first step, ## Rules → apply throughout, ## After → after final step.

Step 1: Validate & Configure

1. Check git repo — run git rev-parse --is-inside-work-tree. If it fails, tell the user: "This directory is not a git repository. $cf-warm only works inside git repos." and STOP.

2. Read config — check CF_CONFIG_FILE (= $MAIN_REPO_ROOT/.coding-friend/config.json) for:

   • docsDir (default: docs)
   • language (default: en)

Step 2: Resolve User & Arguments

Parse $ARGUMENTS for flags:

• --user <name> — git author name to look up. If not provided, auto-detect via git config user.name.
• --n-commits <N> — number of user's own commits to summarize (default: 10).

If --user is not provided AND git config user.name returns empty, ask the user to provide a name with --user.

Store resolved values as $USER_NAME and $N_COMMITS.

Confirm to the user: "🟢 Warming up as $USER_NAME, looking at your last $N_COMMITS commits."

Step 3: Dry Run — Count Commits

Before fetching full commit data, count how many commits we'll process:

# Get date of user's Nth commit (the cutoff point) — store as $SINCE_DATE
git log --author="$USER_NAME" -n $N_COMMITS --format="%aI" | tail -1

# Count OTHER commits by subtraction (git has no reliable --not-author flag)
# Total commits since date:
git log --after="$SINCE_DATE" --oneline | wc -l
# User's commits since date:
git log --after="$SINCE_DATE" --author="$USER_NAME" --oneline | wc -l
# Others = Total - User's

Display the dry run result:

Showing your last $N_COMMITS commits. Found Y commits by others since $SINCE_DATE.

Safety cap: If Y > 200, warn the user:

⚠️ There are Y commits by others. I'll summarize the most recent 200 to keep the report manageable. Use a more recent --n-commits value to narrow the window.

If the user's name matches zero commits, display a helpful error:

No commits found for author "$USER_NAME". Check git config user.name or use --user "Exact Name" to specify the correct author.

STOP if zero commits found for the user.

Step 4: Gather Commit Data

4a. User's commits — fetch the last $N_COMMITS:

git log --author="$USER_NAME" -n $N_COMMITS --format="---commit---%nHash: %h%nDate: %ad%nSubject: %s%n%b" --date=short

This gives commit hash, date, subject line, and body (description). Do NOT fetch diffs — only use messages and descriptions.

4b. Other commits — fetch all commits since the user's cutoff date, then filter out the user:

git log --after="$SINCE_DATE" --format="---commit---%nHash: %h%nDate: %ad%nAuthor: %an%nSubject: %s%n%b" --date=short

From this output, exclude commits where Author matches $USER_NAME (the LLM filters by comparing the Author field). Apply the 200-commit safety cap on the remaining "other" commits if the dry run showed > 200.

Step 5: Analyze & Cluster

5a. Summarize user's commits:

For each of the user's commits, write a brief 1-2 sentence summary based on the commit message and description. Group related commits together if they're part of the same feature/fix.

5b. Cluster other commits by topic/area:

Read through all other commit messages and group them into logical topics. Use the commit subjects and descriptions to infer the topic — do NOT look at diffs unless a commit message is too vague to classify.

Typical topic groups:

• Feature area (e.g., "Authentication", "API", "Frontend", "Database")
• Type of work (e.g., "Bug Fixes", "Refactoring", "Infrastructure", "Documentation")
• Module/package name (for monorepos)

For each topic group, write:

• Topic name (short, descriptive)
• Summary (2-3 sentences covering what changed)
• Key commits (list the most important 3-5 commits with hash + subject)
• Authors involved

Use the language setting from config for the report language.

Step 6: Write Report & Display Summary

6a. Delegate to cf-writer agent:

Construct a write spec and invoke the cf-writer agent by spawning the cf-writer custom agent.

WRITE SPEC
----------
task: create
file_path: {CF_DOCS_ROOT}/warm/warm-YYYY-MM-DD.md
language: {language from config}
content: |
  ---
  title: "Warm-up: $USER_NAME — YYYY-MM-DD"
  description: "Catch-up report for $USER_NAME after absence, covering N own commits and M team commits"
  tags: [warm-up, git-history, catch-up]
  created: YYYY-MM-DD
  ---

  # Warm-up Report: $USER_NAME

  **Generated:** YYYY-MM-DD
  **Period:** $SINCE_DATE → today
  **Your commits:** $N_COMMITS | **Team commits:** $M

  ## Your Recent Work

  <Summarized user commits, grouped by feature/fix if related>

  ## What the Team Did

  ### <Topic 1>
  <Summary>
  - `abc1234` — commit subject (Author)
  - `def5678` — commit subject (Author)

  ### <Topic 2>
  <Summary>
  - ...

  ## Quick Orientation

  <2-3 bullet points highlighting the most impactful changes the user should be aware of>
readme_update: false
auto_commit: false
existing_file_action: create

6b. Display terminal summary:

After the file is written, display a concise summary directly in the terminal:

## 🔥 Warm-up Complete

**You ($USER_NAME):** <1-2 sentence summary of your work>

**Team highlights:**
- <Topic 1>: <one-line summary>
- <Topic 2>: <one-line summary>
- ...

**⚡ Key things to know:**
- <Most impactful change 1>
- <Most impactful change 2>

📄 Full report: {docsDir}/warm/warm-YYYY-MM-DD.md

Step 7: Index in Memory

After the report is written, call memory_store MCP tool to index it:

• title: "Warm-up: $USER_NAME — YYYY-MM-DD"
• description: "Catch-up report after absence: N own commits, M team commits grouped by topic"
• type: "fact"
• tags: ["warm-up", "git-history", "catch-up", "$USER_NAME"]
• content: the full markdown content
• importance: 2
• source: "conversation"
• index_only: true

If MCP tools are unavailable, log a warning but do NOT fail — the file was already written.

Show the user a 2-line summary:

• Markdown file: {docsDir}/warm/warm-YYYY-MM-DD.md (created)
• Memory DB: indexed ✓ — or: MCP unavailable, file only

Interpreting $ARGUMENTS

$ARGUMENTS is optional. It can contain:

• --user <name> — git author name (uses substring matching via git log --author)
• --n-commits <N> — number of user's own commits to show (default: 10)
• Free text is ignored (reserved for future use)

Examples:

• $cf-warm — auto-detect user, show last 10 commits
• $cf-warm --user "John Smith" — look up commits by John Smith
• $cf-warm --n-commits 20 — show last 20 of your commits
• $cf-warm --user "Jane" --n-commits 3 — Jane's last 3 commits

Rules

• Git only — this skill requires a git repository. Stop immediately if not in one.
• Messages only — use commit messages and descriptions, NOT diffs. Only inspect actual changes if a commit message is too vague to understand.
• Dry run first — always count commits before fetching to warn about volume.
• Safety cap — maximum 200 "other" commits. If more exist, take the most recent 200 and note the truncation.
• Respect language — write the report in the configured language setting.
• No duplicate reports — each report gets a unique date-stamped filename. Multiple runs on the same day overwrite the same file.
• Be concise — summaries over exhaustive lists.
• Group related commits — don't list every commit individually if they're part of the same feature.