pkm-session-end

# PKM Session End — Knowledge Capture and Graph Maintenance

Workflow for session wrap-up. When running as a subagent, the delegation prompt provides the project path and devlog boundary context. The agent's system prompt handles transcript discovery (Step 0) before this workflow begins.

## Step 1: Devlog Entry

Append a session summary to the project devlog, most recent entry first.

**If the devlog file doesn't exist yet** (new project, first session), create it first:

```
vault_write({
  template: "devlog",
  path: "01-Projects/<Project>/development/devlog.md",
  frontmatter: { tags: ["devlog"], project: "<Project>" }
})
```

Then append the session entry:

```
vault_append({
  path: "01-Projects/<Project>/development/devlog.md",
  heading: "## Sessions",
  position: "after_heading",
  content: "### YYYY-MM-DD HH:mm\n\n#### Session Summary\n- <what was accomplished>\n\n#### Key Decisions\n- <decisions made, link to ADRs if created>\n\n#### Blockers / Issues\n- <problems encountered, or \"None\">\n\n#### Next Steps\n- <what remains>\n\n---\n"
})
```

Use the **actual date** and fill in real content from the session. Keep entries concise but specific. Using `after_heading` inserts each new entry at the top, keeping the log in reverse-chronological order.

**Wikilinks in devlog entries**: Include `[[wikilinks]]` to tasks, ADRs, research notes, and other vault notes that were completed, created, or significantly updated during the session. For example: `- Completed [[task-api-refactor]]` or `- Decided on caching strategy ([[ADR-003-caching]])`.

**Existing devlogs**: Older devlogs may use `## YYYY-MM-DD` entries without a `## Sessions` heading. If `vault_append` fails with "Heading not found", add the heading first: `vault_append({ path: "...", content: "\n## Sessions\n" })`.

## Step 2: Review Session Work

The parent agent's session-context message in the delegation prompt is the **primary boundary** for what counts as "this session." Use it to decide which work is in-scope to capture. The activity log is a discovery aid — useful for spotting files-touched you may have missed — not a session-scope definition.

Why this matters: the MCP server's session ID can span work that was already captured in earlier devlog entries within the same session, so filtering purely by session ID risks re-capturing already-documented work or capturing work outside the parent's intended scope.

Query the activity log to find files touched:

```
vault_activity({ limit: 1 })
```

The response header shows `current session: <id>` (an 8-character prefix). Filter to the same session for full file history:

```
vault_activity({ session: "<id-from-header>", limit: 50 })
```

Cross-reference the touched files against the parent's session context. Files outside the parent's stated scope, or files already covered by prior devlog entries in the same session, are not your responsibility to capture again.

## Step 3: Capture Undocumented Work

Review the session's conversation for significant work that only exists in chat history. Most exchanges produce nothing worth capturing beyond the devlog entry in Step 1. When in doubt, don't capture — a missed capture is better than vault noise.

Skip entirely if the session was purely mechanical (config changes, minor fixes).

**For each PKM-worthy item independently**, determine whether to update an existing note or create a new one:

### 3a: Check for existing coverage

For each item, search the vault:

```
vault_semantic_search({ query: "<topic/title>", limit: 5 })
```

If unavailable, use `vault_search` with key terms + `vault_query` with matching tags.

**Route based on results.** Note on score interpretation: `vault_semantic_search` uses `text-embedding-3-large` (3072-dim) cosine similarity, which compresses hard. Even a verbatim title/heading of an existing note typically scores around 0.55–0.65; scores above 0.7 are essentially never observed.

- **Likely duplicate (top hit ≥ 0.5)**: Read the top hit with `vault_read` and confirm it's actually about the same topic before routing — a 0.5 score can be a real duplicate or a same-domain neighbor. If same topic: go to **3b** (update). If neighbor: go to **3c** (create with links).
- **No close match (top hit < 0.5)**: Go to **3c** (create new note).
- **Task status change**: Go to **3d** (update task).

### 3b: Update existing note

When a note already covers this topic, enrich it rather than creating a duplicate:

- `vault_read` the existing note to understand its current content
- `vault_append` to add new findings, with a date-stamped section if the note uses chronological entries
- `vault_edit` to update outdated information (e.g., refining a decision's rationale, adding a new root cause to a troubleshooting log)
- `vault_update_frontmatter` to update status or other metadata if changed
- After updating, run `vault_suggest_links` to discover new connections worth adding

### 3c: Create new note

Follow the pkm-write skill workflow for proper duplicate checking, template selection, and linking:

| Content Type | Template | Default Path |
|---|---|---|
| Architecture/design decisions | `adr` | `<project>/development/decisions/ADR-NNN-{title}.md` |
| Research findings or evaluations | `research-note` | `<project>/research/{title}.md` |
| Complex debugging sessions | `troubleshooting-log` | `<project>/development/debug/{title}.md` |
| Reusable insights or patterns | `permanent-note` | `03-Resources/Development/{title}.md` |
| New tasks identified | `task` | `<project>/tasks/{title}.md` |

Where `<project>` is the vault project path from session context.

### 3d: Update task status

When a task's status, priority, or details changed during the session:

1. `vault_query({ type: "task", custom_fields: { project: "<Project>" } })` to find the task
2. `vault_update_frontmatter` to update status/priority
3. Optionally `vault_append` to add context about what changed
4. Add a heading-anchored backlink from the task to the devlog entry. Important: `vault_add_links` resolves `target` by file basename only — `#heading` suffixes in `target` are not parsed and the call will fail with `not found`. To link to a specific session entry, use `vault_append` to add an inline wikilink in the task body. Use the disambiguated devlog path (`<project>/development/devlog`) rather than the bare basename, since vaults can have multiple `devlog.md` files (one per project) and Obsidian's basename resolver may pick the wrong one:
   ```
   vault_append({
     path: "<task-path>",
     content: "\n**Status change**: pending → done on YYYY-MM-DD HH:mm. See [[<project>/development/devlog#YYYY-MM-DD HH:mm]] for the session that completed this."
   })
   ```
   Substitute the actual project path and timestamp. Use the same `### YYYY-MM-DD HH:mm` heading from Step 1 as the wikilink target. This produces a clickable heading-anchored backlink that Obsidian renders correctly. Bidirectional traceability: the devlog entry links to the task (Step 1), the task body links back to the specific session heading.

## Step 4: Quality Check

Read back each note created in Step 3 using `vault_read`. Verify:
- No template placeholder text remains (e.g., "Brief description of the technology, tool, or concept", "What was the situation or context?", "Describe the problem")
- Frontmatter has real values (not template defaults)
- Content is specific to the session, not generic

Fix any issues with `vault_edit`. If a note is entirely placeholder text, delete it with `vault_trash` — an empty note is worse than no note.

## Step 5: Quick Link Check

Run a targeted link health check on files touched during this session:

```
vault_link_health({ folder: "<project-folder>", checks: ["orphans", "broken"] })
```

For any **orphan** notes found (no connections), add links using `vault_add_links`. Broken links (pointing to non-existent files) may self-resolve if the missing notes were created earlier in this session — otherwise note them for manual review. For deeper audit (weak connections, ambiguous links, full vault scan), delegate to the link-auditor agent separately.

## Step 6: Index Update

Check and update if changed during the session:
- **Project `_index.md`**: Add links to new ADRs, update project status, add key links
- **Relevant MOCs**: Add links to new notes that belong in topic index maps