From vp-knowledge
This skill should be used when the user asks to fix, repair, or tidy one or more SPECIFIC named notes — 'fix these notes', 'fix the issues in [note]', 'add the missing relations to [note]', 'tidy up [note]', 'fix orphan [note]', 'apply the gardener findings for [note]'. Applies fixes inline so the user sees and confirms each edit. NOT for read-only auditing (use /knowledge-garden), NOT for creating new notes (use /package-intel or /tool-intel), and NOT for graph-wide or autonomous remediation ('fix the whole audit', 'remediate the graph', research-and-document sweeps) — those belong to the knowledge-maintainer agent, which this skill delegates to when invoked broadly.
How this skill is triggered — by the user, by Claude, or both
Slash command
/vp-knowledge:knowledge-maintain [note ...][note ...]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Apply targeted fixes to Basic Memory notes — missing sections, relations,
Apply targeted fixes to Basic Memory notes — missing sections, relations,
structural tidies, archival — with the user confirming changes inline. This is
the scoped, interactive sibling of the knowledge-maintainer agent: it owns the
common case (repair a few named notes, where being in the main session means the
user sees each edit) and delegates heavy, autonomous remediation to the agent.
Write discipline (non-negotiable):
edit_note with find_replace ONLY. Never append with section= — it
appends to end-of-file, not end-of-section, the documented BM footgun.write_note and delete_note are intentionally excluded. Create new notes
via /package-intel or /tool-intel; archive via move_note to archive/.schema_validate after every edit. If its output appears to repeat the same
value, trust the note body (read_note JSON) as the source of truth rather
than inferring a duplication from the validator response alone.Classify the request first:
Delegate to the agent when the work is heavy or autonomous — any of:
/package-intel / /tool-intel.To delegate, launch the write agent and stop:
Agent(subagent_type="knowledge-maintainer",
description="Graph remediation from audit",
prompt="<the user's original request, verbatim; include the gardener
report if one is in context>")
If the Agent call fails or returns no usable report (unknown subagent type,
error payload, or empty output — the knowledge-maintainer agent may not be
installed), say so explicitly and state clearly that no edits were applied —
do not fabricate a remediation summary or let the user assume fixes happened.
Offer to apply a named scoped subset inline as a fallback.
Run inline (scoped) when the request names a bounded set of notes and a clear set of findings (roughly 1–8 notes). Proceed to step 2. If scope grows mid-task (e.g. a "fix this note" turns into needing a new note), stop and recommend the agent or the relevant intel skill rather than expanding inline.
For each target note, read the live content as the source of truth:
read_note(identifier="<permalink-or-title>", output_format="json")
Confirm the finding still holds against the actual note. If the premise is
wrong (the section already exists, the "duplicate" is a stub, the note already
ships correctly), STOP and report what was found instead of editing. Derive the
exact surrounding text for find_replace from what was read — never assume
whitespace or line counts from a third-party report.
| Auto-fix (apply directly) | Confirm first (content-level) |
|---|---|
Missing ## Observations / ## Relations heading | Merging duplicate notes |
Observation section trailing after ## Relations | Rewriting prose / observations |
Relation verb drift (related_to→relates_to) | Archiving a note (move_note) |
Adding a genuine missing [[wiki-link]] relation | Changing a note's meaning or scope |
| Frontmatter type case / snake_case fixes | Anything destructive or hard to reverse |
For confirm-first changes, present the exact before/after and wait for the user's response before executing.
When a fix could plausibly fall in either column — especially any edit that alters observation wording rather than purely relocating it — default to confirm-first. The auto-fix column is a positive list; treat anything not clearly in it as confirm-first.
Use edit_note(operation="find_replace") with text anchored on content read in
step 2. Typical patterns:
## Observations — two find_replaces in
strict order: (1) insert first — anchor on the first ## Relations line and
prepend the observation lines before it; if this no-matches, STOP (original
content is untouched), report, and ask how to proceed. (2) strip second —
only after a re-read confirms the lines now appear in ## Observations, strip
the stray trailing heading and its now-duplicated lines. Never strip-before-
insert: that leaves the note content-less if the insert no-matches.relates_to [[target]] line after it.Preserve meaning exactly — moves and verb fixes are not rewrites. When dropping
a heading would lose date/provenance context, fold a brief inline marker (e.g.
(Sprint 20)) onto the moved lines rather than discarding it. For any multi-step
fix (especially the insert-then-strip move), proceed to step 5's count assertion
before considering the note done.
After each note's edits, run schema_validate(identifier="<note>") (validate
the single edited note via identifier, not the whole note_type batch).
Confirm content survived, not just that it validates. For any multi-step
edit (e.g. the insert-then-strip move): record N_before = observation count
from the step-2 JSON read, then after all find_replaces re-read via
read_note(output_format="json") and compare N_after. schema_validate
passing with N_after < N_before is the exact data-loss signature — a note that
silently lost observations still validates cleanly. N_after == N_before (or
higher, if observations were intentionally added) is the passing gate. If a
multi-step edit landed only partially, the note is in a damaged/partial state:
report it explicitly and restore the removed content before continuing.
If error_count is not 0, do NOT report the fix as complete. Determine
whether your edit caused it or merely revealed a pre-existing issue (the
edit_note re-parse gotcha), surface the exact errors, state that the note is
currently schema-invalid, and either correct it or flag it prominently — never
close out a maintain pass with an unresolved non-zero error count framed as
success.
Then report per note:
find_replace operations run./schema-evolve, or a content change the user declined).edit_note re-parse gotcha — edit_note re-parses the ENTIRE note after
a raw string replacement, so a pre-existing unrelated issue can trip on your
edit. Report it; do not expand scope to fix unrelated problems.find_replace cross a ---
frontmatter boundary on a schema note; it can create a duplicate frontmatter
block. Keep find/replace inside the body or inside the YAML block, never
spanning the markers./schema-evolve question, not a note edit. Leave the note untouched.edit_note/
move_note errors and emits recovery guidance; follow it.find_replace only — never append+section.schema_validate, expect 0 errors.move_note
to archive/), no graph-wide sweeps (delegate to the agent).npx claudepluginhub voxpelli/vp-claude --plugin vp-knowledgeGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.