/updatespec

description: Refresh the CCF spec (.claude/rules + CLAUDE.md) AND system memory with what was learned this session, so future sessions start fresh and repeat fewer mistakes. Also records new tools with "when to use".
argument-hint: ""
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
model: opus

You are running CCF `/ccf:updatespec`. Distill this session's lessons into **two places** — the project spec (`.claude/`) and Claude Code's system memory — so future sessions start with fresh context and repeat fewer mistakes.

> **Why two places, and what goes where:** > - **Spec** (`CLAUDE.md` + `.claude/rules/`) is loaded as a *user message* tagged "may not be relevant", so it carries lower weight. It suits **project rules**: conventions, architecture, tech stack, tooling. > - **Memory** (`~/.claude/projects/<path>/memory/`) is loaded into the *system prompt* and is not down-weighted, so Claude follows it more strongly. It suits **anti-mistake feedback** and **user preferences** across sessions. > - **No duplication:** anything already in `CLAUDE.md` stays there. When a rule in `CLAUDE.md` keeps getting forgotten, write a `feedback` memory that reinforces it and states why, instead of copying its content.

0a. Style for user-facing text (applies to every step below that writes text for the user)

**Scope boundary:** this rule governs CCF-generated text meant for the human reader (the diff explanation, the "why" line, the plan and task sync notes shown to the user). It does NOT apply to the CCF repo's own source, which stays English per `.claude/rules/components.md` (never translate the repo itself).

• Write in the SAME language the user is using in this conversation; never mix two languages inside one sentence.
• Keep identifiers verbatim (file names, function names, variable names, command names, field names, event names) — translating an identifier makes it wrong.
• Translate a concept when the user's language has a natural equivalent; keep a difficult or ambiguous English term verbatim and add a short parenthetical explanation on first use.
• No em dash; use a comma, colon, or parentheses instead.
• One idea per sentence; split a sentence longer than two lines.
• A language that uses diacritics (e.g. Vietnamese) must keep them; never write bare ASCII when the language needs marks.
• Do not invent abbreviations; if one is used, spell it out on first use.
• Open with the point itself; never with generic filler. End when the content ends; never restate what was just said as a summary.
• Cut adjectives that add no information; a claim earns its adjective with a concrete fact, number, or name.
• Use as many bullets as there are real points, never a rounded count; prefer plain prose when ideas are not parallel.
• Prefer a specific example, number, or name over an abstract description; give one clear recommendation instead of an option list with no conclusion; state uncertainty plainly.
• Vary sentence length; do not repeat the same key phrase within a paragraph.
• No icons or emoji in generated text; review markers use the word set FAIL:/WARN:/PASS:.

Steps

1. Reflect & classify

Review this session for lessons, then classify each as **spec** or **memory**:

• → **Spec**: project conventions and patterns, architecture, tech stack, new tooling — anything derivable from the code or belonging to the repo.
• → **Memory (`feedback`)** — the strongest, most-followed memory type: mistakes you (Claude) made plus their fixes, AND correct approaches the user confirmed. Record both: a losses-only memory makes future sessions timid, so logging the wins keeps confidence calibrated.
• → **Memory (`user`)**: preferences, habits and working style the user expressed (e.g. "always use X", "don't refactor unprompted").
• → **Memory (`project`)**: project constraints not derivable from code or git (deadlines, freezes). Convert relative dates to absolute ones.
• Keep out of memory anything derivable from code, git history, or already in `CLAUDE.md`, and transient task progress — the latter belongs in the plan.

2. Locate the spec

Find every `CLAUDE.md` and `.claude/rules/*` (root + nested). Each lesson belongs to the file closest to cwd; a lesson that applies to one area of the tree goes in a rule with `paths:` frontmatter, which lazy-loads only when a matching file is touched.

3. Update modularly

• Write lessons as **specific, verifiable rules**.
• Keep each rule file < 50 lines on one topic; create a new `.claude/rules/<topic>.md` when none fits, and add a `@.claude/rules/<topic>.md` import line to the relevant `CLAUDE.md`.
• Keep every `CLAUDE.md` < 200 lines. You may delegate the drafting to `ccf-spec-writer` via Task **with `run_in_background: false`**, since Claude Code v2.1.198 an omitted `run_in_background` defaults to background and this step needs the draft back before it can write anything.
• **Show a diff plus a one-line "why"** before writing, then Edit/Write.

4. Record new tools (with when to use)

If this session added a new **skill / MCP server / subagent / tool** (e.g. the user installed the Supabase MCP), record it in `.claude/rules/tooling.md` **with an explanation of WHEN TO USE it**: the specific trigger, input and output, one example. This is the core of context-first — the spec says not just what exists but when to reach for it.

5. Update system memory (cross-session anti-mistake)

Write the lessons classified as **memory** in step 1 into this project's memory directory: `~/.claude/projects/<sanitized-project-path>/memory/`. > **Auto Memory interplay:** Claude Code's `autoMemoryEnabled` (on by default, v2.1.59+) may already have auto-saved notes from this session. This step is the *deliberate curation* pass: review and dedupe what is there, then write the high-signal lessons explicitly rather than trusting the auto-extractor.

• Each memory is **one file holding one fact**, with frontmatter `name` (kebab-case), `description` (one line, used for recall) an