Extract Knowledge

---
name: extract-knowledge
description: >
  Extract knowledge (decisions, facts, session metadata) from the current
  Claude Code session into the Grafema Knowledge Base. Run after completing
  a task or at any point when substantive knowledge was produced.
  Follows runbook _ai/runbooks/02-claude-sessions.md.
user_invocable: true
trigger: >
  User says "/extract-knowledge", "extract knowledge", "извлеки знания",
  or at the end of a substantive task per workflow step.
---

# Knowledge Extraction from Current Session

## Step 0: Detect context

```
TASK_ID = parse from current git branch (e.g., task/REG-629 → REG-629)
SESSION_DATE = today's date (YYYY-MM-DD)
SESSION_SLUG = <date>-<task-topic-slug>  (e.g., 2026-03-07-knowledge-runbooks)
```

If no task branch → use topic of the session for the slug.

## Step 1: Check existing session

Call `query_knowledge(type="SESSION", text="<SESSION_DATE>")`.

If a session for today + same task already exists → this is an UPDATE, not create.
Load existing session to avoid duplicating entities.

## Step 2: Extract decisions

Review the conversation for architectural decisions made. For each:

Ask yourself:
1. What was decided? (concise statement)
2. What alternatives were rejected and why?
3. What code does this affect? (semantic addresses: `file:name:TYPE`)
4. What facts informed this decision?

Create via `add_knowledge`:
```
add_knowledge(
  type="DECISION",
  slug="<descriptive-slug>",
  content="<decision statement + rejected alternatives>",
  status="active",
  projections=["epistemic"],
  relates_to=["<code semantic addresses>"]
)
```

## Step 3: Extract facts

Three prompts to self:

**A) Explicit facts:** What facts about the codebase were confirmed or discovered?
**B) Side-effect facts:** What non-obvious facts emerged as side effects of the main task?
**C) Preferences:** What conventions or preferences were established?

For each fact, create via `add_knowledge`:
```
add_knowledge(
  type="FACT",
  slug="<descriptive-slug>",
  content="<fact description with evidence>",
  confidence="high|medium|low",
  projections=["epistemic"],
  relates_to=["<code semantic addresses>"]
)
```

## Step 4: Collect created artifacts

Check what was created during this session:
- Linear tickets (REG-NNN, RFD-NNN patterns in conversation)
- Git commits (`git log --oneline --since="today"` on current branch)
- Files created/modified significantly

## Step 5: Create/update SESSION node

```
add_knowledge(
  type="SESSION",
  slug="<SESSION_SLUG>",
  content="<session summary: what was done, key outcomes>",
  task_id="<TASK_ID>",
  projections=["epistemic"]
)
```

Then manually update the session file's `produced:` list in frontmatter
to include all entity IDs from steps 2-4.

## Step 6: Create edges

Append to `knowledge/edges.yaml`:
- PRODUCED: session → each decision, fact
- CREATED_IN: each ticket/commit → session
- INFORMED_BY: decision → facts that informed it (with evidence)
- IMPLEMENTS: ticket → decision (if applicable)
- SUPERSEDES_APPROACH: decision → rejected approach (if applicable)

## Step 7: Validate

Run validation checks from `_ai/runbooks/README.md`:
1. All IDs match `^kb:[a-z_]+:[a-z0-9][a-z0-9-]*[a-z0-9]$`
2. No slug collisions (check existing KB)
3. All edge endpoints exist
4. Code refs resolve via `find_nodes` (mark DANGLING if not)
5. No duplicate facts (`query_knowledge(type="FACT", text="<key phrases>")`)
6. All entities have `source` field

## Step 8: Invalidation check (optional)

If the session modified code that existing KB entities reference:
1. `query_knowledge(include_dangling_only=true)` — find newly broken refs
2. For each dangling ref: is the code gone, renamed, or moved?
3. If renamed/moved → update the `relates_to` in the KB entity
4. If gone → leave as dangling (staleness signal)

## Output summary

Print a summary:
```
Knowledge extracted:
  Session: kb:session:<slug>
  Decisions: N (list IDs)
  Facts: N (list IDs)
  Artifacts: N tickets, N commits
  Edges: N new
  Validation: N OK, N warnings
  Dangling refs: N (list if any)
```

## Skip conditions

Do NOT extract if:
- Session was trivial (typo fix, single-line change, no decisions made)
- Session only read code without producing knowledge
- All knowledge from this session was already extracted (update check in Step 1)