## ADDED Requirements ### Requirement: memory-query skill — graph retrieval guidance The plugin SHALL provide a `memory-query` skill that teaches Claude when and how to query the vault knowledge graph versus the episodic memsearch layer. The skill SHALL specify: (a) use `graphify query ""` for evergreen knowledge questions ("how do we…", "what do we know about…"), (b) use `graphify path "" ""` to find how two concepts relate, (c) use `graphify explain ""` for a deep-dive with neighbors, (d) add `--budget N` to cap answer size (default ~2000 tokens), (e) add `--dfs --budget N` for bounded depth-first traversal, (f) add `--graph ` to query a specific project graph instead of the vault graph. The skill SHALL explicitly state that god-nodes are the entry point — query god-nodes first, then scalpel to specific nodes. The skill SHALL treat tag-scoped retrieval (e.g. "all notes tagged `client/acme`") as a SEPARATE query path from graph traversal, noting that whether shared frontmatter facet tags create graph edges is unverified (ADR-014 open question); Claude SHALL NOT assume facet tags enable graph traversal. For "what happened when" questions, the skill SHALL direct Claude to memsearch in natural language rather than the vault graph. #### Scenario: Claude needs to answer a knowledge question during a task - **WHEN** a task touches a tool, client, or domain the vault may know about - **THEN** Claude runs `graphify query ""` before relying on training knowledge, using `--budget` to keep context lean #### Scenario: Claude needs to find how two concepts relate - **WHEN** a task requires understanding the relationship between two vault entities (e.g. client and a tool they use) - **THEN** Claude runs `graphify path "" ""` to traverse the graph path between them #### Scenario: Cross-client knowledge lookup - **WHEN** Claude needs to find all vault knowledge about a tool or domain regardless of which client it came from - **THEN** Claude runs `graphify query ""` against the vault graph (not `--graph `) to get cross-client results #### Scenario: Project-specific knowledge lookup - **WHEN** Claude needs knowledge specific to the current project's code graph - **THEN** Claude runs `graphify query "" --graph /graphify-out/graph.json` using the project graph path injected by SessionStart #### Scenario: Episodic question ("what was I working on last week?") - **WHEN** a question is time-anchored ("what did we decide last Tuesday", "what was I working on yesterday") - **THEN** Claude queries memsearch in natural language, NOT the vault graph ### Requirement: memory-write skill — when and how to write vault knowledge The plugin SHALL provide a `memory-write` skill that teaches Claude when knowledge should be written to the vault and what the required frontmatter contract is. The skill SHALL specify: write to the vault when knowledge is evergreen and reusable across projects (tool/API behavior, conventions, client-specific facts worth reusing); do NOT write project-ephemeral state to the vault (that goes to project files or the episodic layer). The skill SHALL specify the required frontmatter fields: `summary` (one-line, written at note creation — not deferred — this is the human-authored router hint Graphify does not generate), `scope/global` or `scope/project` (default new tool/domain knowledge to `scope/global`; use `scope/project` when specific to how a client uses something), and at least one facet tag from the six-facet taxonomy (`type/`, `client/`, `project/`, `domain/`, `tool/`, `convention/`). The skill SHALL state the vault-not-repo rule: write knowledge ONLY to `~/Documents/SecondBrain`, never silently into a project repo. The skill SHALL note that writing a vault note automatically triggers the PostToolUse hook to update the graph — no manual graphify call is needed after writing. #### Scenario: Claude discovers how a tool's API behaves - **WHEN** Claude learns something about a tool's authentication, rate limits, or endpoint quirks that could apply to future sessions or projects - **THEN** Claude writes a note to the vault with the required frontmatter (summary, scope/global, type/reference, tool/) rather than embedding it in the project's CLAUDE.md #### Scenario: Claude establishes a convention that should apply beyond this task - **WHEN** Claude and the user settle on a convention (coding style, workflow, decision rule) that should propagate to other projects - **THEN** Claude writes a `convention/` note to the vault with the required frontmatter (summary, scope, type/convention) #### Scenario: Knowledge is project-specific (how this client uses a tool) - **WHEN** the knowledge describes behavior specific to one client's setup, not the tool generally - **THEN** Claude writes the note with `scope/project` and a `client/` facet tag rather than `scope/global` #### Scenario: Claude tries to record project-ephemeral state - **WHEN** the information is specific to the current task and not reusable in future sessions or projects - **THEN** Claude does NOT write it to the vault; it stays in the project repo or episodic session notes ### Requirement: memory-reorganize skill — consolidation and plan-mode promotion The plugin SHALL provide a `memory-reorganize` skill that teaches Claude the procedure for consolidating, deduplicating, promoting, and reorganizing vault notes. The skill SHALL specify: (a) reorganization MUST happen in plan mode — Claude proposes changes for human review before executing; (b) triggers include: duplicate coverage noticed across notes, a `scope/project` fact observed to recur across 2+ clients (promotion candidate), a note grown beyond the L1 "one concept, ~200 lines" discipline; (c) the consolidation procedure is: identify candidate notes, propose a merge/split/promote/rename plan, await human approval, execute edits, then run `graphify extract --force` to rebuild the graph clean; (d) a `--force` rebuild is required after any reorganization that removes, renames, or restructures notes (to clear ghost nodes); (e) `--force` rebuild is ALSO triggered when the SessionStart stale check fires, so reorganize skill's rebuild invocation is consistent with the staleness-check mechanism. The skill SHALL warn that `graphify update --file` does NOT prune deleted or renamed nodes — only `--force` rebuilds clear ghost nodes. #### Scenario: Claude notices duplicate coverage across two vault notes - **WHEN** Claude identifies two notes that cover the same concept with overlapping content - **THEN** Claude enters plan mode: proposes which note to keep, what to merge, and what to discard — and awaits human approval before making any edits #### Scenario: A project-scoped fact has recurred across multiple clients - **WHEN** Claude observes that a fact tagged `scope/project` has appeared in 2+ client contexts, suggesting it is actually global knowledge - **THEN** Claude proposes promoting the note to `scope/global` (updating frontmatter, merging client-specific variants if needed) in plan mode before executing #### Scenario: Reorganization is complete and graph needs to be rebuilt - **WHEN** any reorganization edit has been approved and executed (notes deleted, renamed, or restructured) - **THEN** Claude runs `graphify extract --backend ollama --model --force` to clear ghost nodes and rebuild a clean graph; updates the rebuild stamp #### Scenario: Note has grown beyond single-concept discipline - **WHEN** Claude observes a vault note has grown beyond ~200 lines or covers more than one distinct concept - **THEN** Claude proposes a split into two or more focused notes in plan mode, with proposed filenames, frontmatter, and the wikilinks that would connect them — before executing