knowledge-log

name

knowledge-log

description

Grow the jnanin knowledge map by talking. Runs the capture loop — knowledge log → candidates → resolve within candidates → apply → build — turning a free-text sentence about what you studied into evidence that moves mastery and the frontier. Use when the user says what they learned/reviewed/are shaky on/forgot, or invokes /knowledge-log "...". The pane stays read-only; the resolver only ever picks from the candidate set; structure changes are parked for a separate gated pass.

knowledge-log — the capture loop

Turn one sentence about the user's day into evidence in the knowledge map. The map lives at ~/src/aadarwal/jnanin/knowledge-map/; full contract in its LOOP.md and KNOWLEDGE_MAP_DESIGN.md. Core rule: retrieval first, you resolve second — only ever assign evidence to a concept that appears in the candidate set; never invent ids.

The CLI is ${SYSTEM_CMD_NS}.knowledge — the system command namespace plus .knowledge. SYSTEM_CMD_NS defaults to aadarwal.system for this user, so the examples below call aadarwal.system.knowledge; if your namespace differs, substitute it (alias paneapps knowledge if the binary is not on PATH).

Procedure

1. Capture. Run:

   aadarwal.system.knowledge log "<the user's text verbatim>"
   

   Parse the JSON; keep entry_id and ts.

2. Retrieve. Run:

   aadarwal.system.knowledge candidates <entry_id>
   

   This returns candidates (id/title/area/score), plus allowed kinds and ratings.

3. Resolve (this is your only job — bounded by the candidates). For each thing the user mentioned, pick the single best candidate id and classify it:

   • kind: "clicked / learned / got it" → learned; "reviewed / went over / still solid" → reviewed; "shaky / fuzzy / struggled / confused" → shaky; "forgot / blanked" → forgot; a neutral observation → source_note.
   • rating: confident → good/easy; struggled → hard/again.
   • If a phrase matches no candidate, put the phrase in unresolved — do not force it onto a wrong concept.
   • A new topic / missing sheet is not evidence → record it under structure (kind new_concept / missing_anchor / coverage) for the gated pass.

   Write delta.json (use the entry's ts):

   {"entry_id":"<id>","ts":"<ts>","evidence":[
       {"concept":"<candidate id>","kind":"...","rating":"...","note":"<short>"}],
    "unresolved":[],"structure":[]}
   

4. Apply.

   aadarwal.system.knowledge apply delta.json
   

   Read the report (applied / skipped_duplicate / rejected / unresolved / structure_suggestions). A non-zero exit means something was rejected — surface it.

5. Project.

   aadarwal.system.knowledge build
   

6. Report to the user, briefly: which concepts moved and to what mastery, how the frontier/due counts changed, anything unresolved, and any structure suggestions with the note that adding concepts needs a gated structure pass (draft the YAML record → Codex review → edit cluster YAML + place the \concept{} anchor → rebuild).

Guardrails

• Never edit concept YAML or place anchors from this skill — that is the gated structure workflow, not the capture loop.
• Never invent a concept id; only use ids from the candidate set.
• If the user's text is ambiguous about confidence, prefer the conservative rating (hard over good) — overstating mastery is the costly error.
• The map data is the user's; the loop only appends to events/ and log/.