diff --git a/agents/graph-analyst.md b/agents/graph-analyst.md index 988be3e..fa77435 100644 --- a/agents/graph-analyst.md +++ b/agents/graph-analyst.md @@ -204,6 +204,19 @@ traversals and re-deriving structure one hop at a time with naive Cypher: Load skill: context-intelligence-gds ``` +### Track multi-step investigations in a todo climb-log + +If the task is a **multi-step investigation** — provenance tracing, cross-session +synthesis ("how do we work?"), anything that will take more than one probe — load the +hill-climbing skill and track the climb in the `todo` tool: seed the open questions, +write each finding (with its node id / citation) into the item as you answer it, and +mark dead leads. It does **not** change how you query — it makes the investigation +leave an auditable trail. Skip it for a genuine single-shot lookup. + +``` +Load skill: context-intelligence-hill-climbing +``` + ### Using graph_query The `graph_query` tool auto-injects `$workspace` — provide only the Cypher query. diff --git a/agents/session-navigator.md b/agents/session-navigator.md index 7bc35ee..b020718 100644 --- a/agents/session-navigator.md +++ b/agents/session-navigator.md @@ -103,6 +103,17 @@ tool-call budget, summarize-and-discard between steps, and head-limited extracti lookup, respect the max-3-strategy ladder, and hard-stop with "session/data not found" rather than trying every ID variant. Never hold raw JSONL output across steps. +**Track multi-step navigation in a todo climb-log.** For any investigation that will take +more than one probe (provenance tracing, cross-session synthesis, anything you'll refine or +escalate), load the hill-climbing skill and track the climb in the `todo` tool: seed the open +questions, write each finding — with the file/record you found it in — into the item as you +answer it, and mark dead leads. It does **not** change the bounded-extraction discipline above; +it makes the navigation leave an auditable trail. Skip it for a genuine single-shot lookup. + +``` +Load skill: context-intelligence-hill-climbing +``` + --- ## Section 1: Identity and Navigation Approach diff --git a/skills/context-intelligence-hill-climbing/SKILL.md b/skills/context-intelligence-hill-climbing/SKILL.md new file mode 100644 index 0000000..4486cae --- /dev/null +++ b/skills/context-intelligence-hill-climbing/SKILL.md @@ -0,0 +1,63 @@ +--- +name: context-intelligence-hill-climbing +description: 'Use when an investigation needs MORE THAN ONE step — track the exploration as a hill climb in the todo tool so progress, dead leads, and findings leave an auditable trail. Governs HOW you track the climb, NOT how you query or extract (those stay in the graph-query / session-navigation skills).' +version: 0.1.0 +license: MIT +--- + +# Context Intelligence Hill-Climbing + +You already navigate well — bounded probes, count-first, `SKIP`/`LIMIT`, `jq | head`, and the +budget discipline. This skill does **not** change any of that. Its one job is to make a multi-step +investigation **track itself in the `todo` tool** so that (a) you always know the next best step and +when the plan needs adjusting, and (b) anyone reading the run afterwards can see exactly *how* the +answer was reached. + +Think of the todo list as your **climb log / belief-state**: the open questions you're climbing +toward, the findings you've banked, and the leads you've abandoned. + +## When to use this + +- **Use it** for any investigation that will take **more than one probe** — provenance tracing, + cross-session synthesis ("how do we work?"), anything where you'll refine or escalate. +- **Skip it** for a genuine **single-shot lookup** (one count, one bounded query, done). Do not add + todo ceremony to a one-liner — that's overhead, not an audit trail. + +## The climb, tracked in todo + +1. **Seed the open questions.** Before your first real probe, turn the task into `todo` items — + one per open question you must answer. This is the belief-state at the start of the climb. + *(e.g. "Identify the root cause", "Find who FIRST produced the design", "Reconstruct the causal chain".)* + +2. **Take the next best step, then record.** After each probe, update the list immediately: + - mark an open question answered, and **write the finding into the item** (the fact + where you + found it — the citation), not just a checkmark; + - if the probe opened a new question, **add a todo** for it; + - if a lead was a dead end, **mark it dead** with one line of why (so you — and the reader — don't + re-walk it). Do not silently drop it. + +3. **Adjust out loud.** When a finding changes the plan (a lead dies, the shape is different than + assumed, you must escalate the tool tier), the todo list is where that pivot is recorded. Drift + that isn't in the log is drift nobody can audit. + +4. **Converge and stop.** You're done when every open-question todo is answered **or** the budget is + hit. On genuinely absent data, mark the item resolved-as-absent — do not spin. + +5. **The final todo state IS the audit trail.** Before answering, the list should read as a legible + account of the climb: questions asked, findings banked (with citations), leads abandoned. Your + final answer should be consistent with it. + +## What this skill does NOT do + +- It does **not** tell you how to query, page, bound, or extract. For the graph surface, that's + `context-intelligence-graph-query` (+ `context-intelligence-gds` for topology). For the JSONL + surface, that's `context-intelligence-session-navigation` + the navigation-budget discipline. This + skill sits *above* those and only governs the climb log. +- It does **not** add analytical steps you wouldn't otherwise take. If you'd answer in one probe, + answer in one probe. + +## Why it's worth the keystrokes + +The todo trail turns an ephemeral investigation into a **reviewable** one: a later reader (or you, +resuming) can see which leads were tried, which were dead, and what evidence backs each finding — +without re-running the whole climb. Keep it lean; the log should help the work, never become the work.