/updatespec

description: Use when a session ends with code or decisions the spec does not reflect yet, or after /ccf:check passes to mark a task done. Refreshes 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, AskUserQuestion
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

Before step 1, run `node "<plugin-root>/scripts/spec-budget.mjs" --dir <project root>` and keep its `total` as the **before** figure for the Closing. The script is read-only and prints JSON: every file `CLAUDE.md` loads through recursive `@import` (at most four hops), with its bytes, lines and depth, plus `total`, `claudeMdOver` and `missing` imports.

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**.
• **Separate rules from narrative before writing.** A rule is one sentence a reader can check against the repo or a command's output ("hooks exit 0 on malformed stdin"). Everything else is narrative: how a rule was found, measurements, incident history, "observed in task NNN". Narrative goes to `.claude/plan/ARCHIVE.md` (the iteration's `## Closed` note) when it records what shipped and why, or to a `feedback`/`project` memory (step 5) when it guards against a repeat mistake. Keep it out of `CLAUDE.md` and the `@import`ed rules, because every byte there is paid on every session; leave at most a pointer to where the narrative lives.
• 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