update

/update — Update knowledge base

Precipitate this session's work into documents and reusable knowledge. Execute four phases in order: document update, quality review, context consolidation, and pattern extraction.

Division of labor with /pr :/update is responsible for knowledge precipitation,/pr is responsible for git output. They can be combined when needed: first /update then /pr。

Manifest format (shared by Steps 1-5)

Hand off between steps using two manifests, replacing semantic judgment of "should be fine" with count comparison.

Change Manifest(created in Step 1, verified in Step 2):

#	Expected document update	Status	Description
1	docs/api.md	✅ PASS	Has correctly reflected the X API addition

Knowledge Write Manifest(created in Step 3, updated in Step 4, verified in Step 5):

#	Item summary	Target knowledge base	Status
1	[Decision] Reason for choosing A over B	docs/decisions/	Pending write

Both manifests use the difference set of expected_count - verified_count to determine omissions; verified must always use actual grep/glob verification results, and must not be assumed as "should all be done" based on impression alone.

Step 1: Update documents

Scan this session's changes and update relevant documents.

1. Execute git diff --name-only HEAD to get the list of files changed in this session
2. If there are no uncommitted changes, use git diff --name-only HEAD~3..HEAD to get the files involved in recent commits
3. If there are still no changes at all, use AskUserQuestion to ask: specify files / full scan / only do knowledge extraction (skip to Step 3) / end
4. Based on the changes, update docs/、docs/CODEMAPS/、README.md and other affected documents

HITL (required): Before updating, first list the "files planned for update", and use AskUserQuestion to confirm: confirm and continue / adjust the list / skip.

Document library/knowledge base ambiguity: When the context mentions "document library" or "knowledge base", first confirm whether it refers to docs//research/(project documents),~/.claude/projects/.../memory/(Claude memory store), or ~/.claude/skills/(skill library); do not assume on your own.

Agent(subagent_type="general-purpose", model="sonnet")

Execute according to the definition of agents/doc-updater.md (for path resolution and invocation conventions, see agents/README.md; if the definition file cannot be found, treat it as an incomplete installation and follow the inline flow of this Step 1): the prompt must explicitly require scanning this session's file changes according to the above fallback logic, updating the corresponding documents, and outputting a "Change Manifest" (format as above, consistent with the Manifest format of agents/doc-updater.md ).

Main model verification (required, cannot be omitted): After the agent reports completion, the main model must personally git diff verify each claimed change item by item — this type of agent has a track record of fabricating modification records, so it cannot be trusted based only on its own account.

At the end of Step 1, hand the "Change Manifest" to Step 2.

Step 2: Review document quality + security gate

Use a fresh-context agent to review the updates from Step 1 and cross-check against the manifest.

Agent(subagent_type="general-purpose", model="sonnet")

Execute according to the definition of agents/doc-reviewer.md (document review checklist; for path resolution and invocation conventions, see agents/README.md): The prompt must ask for fault-finding rather than endorsement: give PASS/FAIL + source item by item, check whether the content accurately reflects code changes, whether there are outdated or inconsistent descriptions, whether the format conforms to project conventions, and whether important information is missing; and check item by item against the "Change Manifest" for expected vs actual, and compute the difference set.

Security gate (parallel delegation, trigger gate based on rules/security-guidance/skill-integration.md）：

Determine whether the changes in this session touch security-sensitive surfaces (authentication/input/endpoint/DB/deserialization/file/shell/SSRF/DOM/encryption):

• Touched → in parallel with the above review agent paralleldelegate the built-in /security-review(Mechanism A), and have the review prompt include ~/.claude/claude-security-guidance.md as the criterion (Mechanism B):

  Skill(skill="security-review")
  

  findings are merged into the output table below; CRITICAL/HIGH go through the existing AskUserQuestion handling flow
• Not touched → explicitly state "no security-sensitive surfaces, skipping security review", do not run in vain

Output format (required):

Severity	Item	Description
CRITICAL	Content errors	The document description does not match the actual code behavior
HIGH	Important omissions	Missing descriptions of key features or APIs
MEDIUM	Format issues	Inconsistent structure, non-uniform terminology

When there is CRITICAL or HIGH, ask via AskUserQuestion: fix and continue (fix → show result → confirm → enter Step 3) / skip and continue directly.

Step 3: Conversation context organization

Review the entire conversation and extract valuable context:

Extraction item	Purpose
Technical decision rationale, abandoned options, investigation/comparison results, architecture evolution, bug root cause analysis, industry standard references	Knowledge base
Cross-project reusable technical patterns	learned skills (hand off to Step 4)
User preference corrections ("do not do this")	MEMORY.md

Extraction trigger signals:"Considered X but...", "finally chose Y because...", "according to RFC/OWASP/...", explicit before/after comparisons, user corrective behavior.

The knowledge base location is not fixed: The directory varies by project (research/、docs/、notes/ , etc.), do not hard-code paths; after extraction is complete, use AskUserQuestion to confirm the write location. If there is no valuable context in the conversation, enter Step 4 directly.

At the end of Step 3, output the initial version of the "Knowledge Write Manifest" (format as above), and hand it off to Step 4.

Step 4: Extract reusable patterns

Extract cross-project reusable patterns from this session: error resolution patterns, debugging techniques, cross-project architecture decisions, tool usage techniques, industry standard applications, standardized solution selection. Step 3 has already diverted project-specific context elsewhere, so here focus only on the cross-project reusable parts.

Mandatory write format specification: Newly written learned skills must include the following frontmatter:

---
name: <kebab-case-slug>
description: "<適用場景一句話>"
user-invocable: false
origin: auto-extracted
---

Quality assessment (inline 5-dimension scoring, save only if at least 3 points):

Dimension	Score (1-5)	Description
specificity		The specificity of the knowledge
actionability		The degree to which it can be directly applied
scope fit		Whether the scope of applicability is appropriate
non-redundancy		The degree of overlap with existing skills
coverage		Completeness of covered scenarios

Discard specificity=4, actionability=5, ... single-line format.

After Step 4 is complete, write the extracted patterns back into the "Knowledge Write Manifest" (add new entries, update status).

Step 5: Knowledge base cross-check

After Step 4 is complete, perform final verification on the "Knowledge Write Manifest" — do not rely on LLM semantic judgment that "there should be no omissions"; always verify item by item using grep/glob/count.

Knowledge base locations that may be involved in this session:

Knowledge base	Path
Claude memory store	~/.claude/projects/<project-hash>/memory/MEMORY.md
Global skills library	~/.claude/skills/learned/
Global memory	~/.claude/MEMORY.md(if any)
Project knowledge base	Directory confirmed in Step 3
Project documents	docs/、research/、README.md

Enumerate each item in the manifest one by one, use grep/glob to confirm whether it has been written to the corresponding knowledge base (for learned skills, use Glob + read the content to confirm the content is consistent), and compute the expected_count - verified_count difference set. When the difference set > 0, proactively draft content for each missing item, and write it after confirmation via AskUserQuestion; if there are no omissions, list the item-by-item verification evidence (grep hit line numbers, etc.) and finish.

MEMORY.md path location:

• Path rules:~/.claude/projects/<project-hash>/memory/
• project-hash = in the project absolute path, replace / with -, and remove the leading -
• Use Glob to verify the path exists
• If the directory/file does not exist → create it after confirmation via AskUserQuestion

Step 6: Summary report

Output: document update list and change summary, Step 2 review results (including security gate findings, fixed/unfixed items), context extracted in Step 3 and where it was written, patterns extracted in Step 4 and where they were saved, Step 5 cross-check results, suggested next steps (how to handle unfixed issues; if appropriate, suggest running /pr）。

Step 7: Pipeline chaining (optional)

Check whether $ARGUMENTS contains other skill names (such as /pr). If so, trigger them with the Skill tool only after/update all steps (including user confirmation) are complete (passing in the parameters after that skill); do not jump mid-way.

When chaining /pr , you may skip its Step 2 (Quick Review) — a deeper review has already been done by this skill's Step 2 review agent; execute the remaining steps normally. When triggering, prepend [PIPELINE: from /update] to the prompt and list the steps that have already been completed and can be skipped, and note "visual aspects not judged" (this skill does not make that judgment; /pr Step 5.5 will supplement the judgment itself; do not skip it just because Step 2 was skipped).

Usage:/update /pr(update the knowledge base first, then commit + push + create/update the PR),/update /pr 7238(update PR #7238).