From f3a4fe0b18a341e456f9f96d7326e48e5b5af495 Mon Sep 17 00:00:00 2001 From: colombod Date: Tue, 14 Jul 2026 07:53:39 +0000 Subject: [PATCH] feat(skills): add context-intelligence-derived-metrics skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a new standalone Agent Skill for the context-intelligence graph-analyst that teaches deriving INTERPRETIVE metrics over otherwise-blanket graph/event data. Flagship pattern is the "flavour" metric — a sub-session characterized as (delegation transport) x (skill payload loaded inside the spawned sub-session) — joined via Delegation.sub_session_id = Session.node_id. Documents the three moves (spot the blanket, find the discriminating join, recompute with the derived population removed) and generalizes to magnitude-based and artifact-based joins. Sibling to context-intelligence-graph-query; single-file SKILL.md, auto-discovered via the tool-skills directory pointer (no agent wiring needed). Validated in a Digital Twin Universe: the skill auto-discovers in load_skill(list) and loads cleanly with NO soft pointer in graph-analyst.md, siblings intact. 🤖 Generated with [Amplifier](https://github.com/microsoft/amplifier) Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com> --- .../SKILL.md | 266 ++++++++++++++++++ 1 file changed, 266 insertions(+) create mode 100644 skills/context-intelligence-derived-metrics/SKILL.md diff --git a/skills/context-intelligence-derived-metrics/SKILL.md b/skills/context-intelligence-derived-metrics/SKILL.md new file mode 100644 index 00000000..9e9e8e72 --- /dev/null +++ b/skills/context-intelligence-derived-metrics/SKILL.md @@ -0,0 +1,266 @@ +--- +name: context-intelligence-derived-metrics +description: > + Use when a graph query returns structurally-identical rows that hide different + intent — many delegations all "none/conversation", many look-alike sessions, + many identical tool calls — and the raw shape refuses to tell you WHY. Teaches + how to derive an INTERPRETIVE metric by joining a second graph layer onto the + blanket shape, turning undifferentiated data into behavioral signatures. + Flagship pattern: the "flavour" of a sub-session = delegation transport × the + skill payload loaded inside the sub-session it spawned. Complements + context-intelligence-graph-query (which tells you how to READ the graph); this + skill tells you how to make blanket reads MEAN something. +license: MIT +metadata: + version: "1.0.0" + changelog: + - "1.0.0: Initial skill. The blanket-data problem and the three moves (spot + the blanket, find the discriminating join, recompute with the derived + dimension). Flagship flavour metric (transport × in-subsession skill + payload) with verified Cypher. Worked example: council-panel attribution + collapsing self-delegation from ~42% to ~12% of delegations once the + derived dimension is applied. Generalization to magnitude-based and + artifact-based derived metrics." +--- + +# Context Intelligence Derived Metrics + +> **Prerequisite:** load `context-intelligence-graph-query` first. That skill owns +> the schema, scoping levers, size discipline, and blob rules. This skill assumes +> you can already run scoped queries safely; it only teaches the *interpretive +> layer* on top. Verify every node/edge/property named here against the live +> schema (`CALL db.schema.nodeTypeProperties()`) — read the live schema from the +> server, read the *meaning* from this skill. + +## Section 1 — The blanket-data problem + +Raw graph shapes are often **blanket**: many rows share one structural signature +but carry completely different intent. A single-layer query cannot tell them +apart, so the aggregate lies by omission — the mode hides sub-populations. + +The canonical case: delegation transport. Across a real corpus, ~70% of all +delegations were `context_depth="none"`, `context_scope="conversation"`. Read flat, +that says "clean-slate delegation dominates." But that one bucket contained at +least three *different behaviors* wearing the same clothes: + +- **Pure task-offloading** — spin up a fresh worker for an independent unit of work. +- **Context-sink** — park token-heavy exploration in a disposable agent so the + parent stays lean. +- **Council lenses** — a review panel fanning six persona lenses out cold. + +Transport args alone (`agent`, `context_depth`, `context_scope`, `is_self_delegation`) +put all three in the same cell of the table. The distinction is real and it +matters — but it lives in a **different layer** than the one you queried. + +> A derived metric is what you build when the shape you can see is not the meaning +> you need. You attach a second, correlated signal to the blanket shape until the +> sub-populations separate. + +## Section 2 — The three moves + +Every derived metric is the same three moves. Do them in order. + +**Move 1 — Spot the blanket.** A query returns many rows with the same structural +signature and you find yourself unable to say *why* each one happened. The tell: +a dominant mode (one `(depth, scope)` cell, one tool name, one session label) that +you suspect contains distinct intents. If you can't narrate a row from its own +fields, it's blanket. + +**Move 2 — Find the discriminating join.** Identify a *second* graph signal that +correlates with the intent you care about and is reachable from the blanket row. +It comes in three flavours: + +| Join type | Second signal | Separates | +|---|---|---| +| **Categorical (payload)** | what SKILL loaded in the spawned sub-session | council lens vs plain worker | +| **Magnitude** | token / iteration / tool-call *volume* inside the sub-session | context-sink vs light offload | +| **Artifact** | what the sub-session PRODUCED (commit, PR, file) | continuity handoff vs throwaway | + +The best join is *causally meaningful*, not merely correlated (Section 6). + +**Move 3 — Recompute with the derived dimension.** Segment the blanket population +by the new signal, then **recompute the headline stat with the derived population +removed**. The delta is the finding. "Self-delegation is 42% of delegations" +becomes "…but 82% of that is one review panel; strip it out and self-delegation is +12%." The recompute-with-removed step is non-negotiable — it's how you prove the +derived dimension was load-bearing rather than decorative. + +## Section 3 — Flagship: the "flavour" metric + +**Definition.** The *flavour* of a sub-session is `(transport) × (payload)`: + +- **Transport** = the `Delegation` that spawned it: `is_self_delegation`, + `context_depth`, `context_scope`, `agent`. +- **Payload** = what happened *inside* the spawned sub-session. The single most + discriminating payload signal is the `SkillLoad.skill_name`(s) that fired in + that sub-session. + +A `none/conversation` self-delegation is a **blank envelope** — its meaning comes +entirely from what skill gets loaded inside it. That is exactly why a review panel +can hide in plain sight: it shares a transport signature with ordinary parallel +fan-out, and only the skill payload reveals it is a debate panel convened cold. + +### The join key + +`Delegation.sub_session_id` equals the spawned session's `Session.node_id`. That +is the bridge from transport to payload. Skill loads hang off the sub-session two +ways (per graph-query Gotcha 6) — iteration-level and session-level — so match +both: + +```cypher +// FLAVOUR TABLE — every delegation transport × the skill payload of its sub-session. +// Scope on the PARENT session (it carries workspace); see graph-query Section 2. +MATCH (parent:Session {workspace: $workspace}) + -[:HAS_EXECUTION]->(:OrchestratorRun)-[:HAS_PART]->(:Iteration) + -[:HAS_TOOL_CALL]->(:ToolCall)-[:TRIGGERED]->(d:Delegation) +OPTIONAL MATCH (sub:Session {node_id: d.sub_session_id}) +OPTIONAL MATCH (sub)-[:HAS_EXECUTION]->(:OrchestratorRun)-[:HAS_PART]->(:Iteration) + -[:HAS_SKILL_LOAD]->(sl:SkillLoad) +OPTIONAL MATCH (sub)-[:HAS_SKILL_LOAD]->(slsess:SkillLoad) // session-level loads +WITH d.is_self_delegation AS self, + d.context_depth AS depth, + d.context_scope AS scope, + coalesce(sl.skill_name, slsess.skill_name) AS payload_skill +RETURN self, depth, scope, payload_skill, count(*) AS n +ORDER BY n DESC +LIMIT 100 +``` + +Rows where `payload_skill IS NULL` are transport with no skill payload — plain +workers and context-sinks (separate those with a magnitude join, Section 5). Rows +where `payload_skill` is a named lens (e.g. `crusty-old-engineer`, +`restless-old-brian`) are the panel. + +### The reverse rollup — for each skill, its transport signature + +Flip the same result to ask "when this skill runs, how is it convened?" A skill +with one dominant transport signature has a strong flavour; a skill spread across +transports is convened many ways. + +```cypher +// Same match as the flavour table, then group per skill. +// Cypher has no SQL window functions — compute the per-skill total with a +// collect/UNWIND two-pass, not OVER(PARTITION BY ...). +WITH payload_skill, d.is_self_delegation AS self, + d.context_depth AS depth, d.context_scope AS scope, count(*) AS n +WHERE payload_skill IS NOT NULL +WITH payload_skill, sum(n) AS total, + collect({self: self, depth: depth, scope: scope, n: n}) AS combos +UNWIND combos AS c +RETURN payload_skill, c.self AS self, c.depth AS depth, c.scope AS scope, + c.n AS n, toFloat(c.n) / total AS share_within_skill +ORDER BY payload_skill, n DESC +``` + +Expect the panel lenses → ~100% `self / none / conversation` (convened cold by +design). A context-sink skill → named-agent `/ none`. A continuity skill → named +`/ recent` or `/ all`. + +### Attribution discipline — attribute by CHILD, never by shared parent + +The flavour join attributes by the **sub-session's** skill load — and that is the +*correct* attribution, not a convenience. The trap: an inline panel (a +`*-here` variant that loads into the CURRENT session instead of forking) shares +its parent session with that session's own real work — git-ops, builders, the lot. +If you attribute by the *parent* session's skill loads, you sweep all that +unrelated work into the panel's bucket and massively over-count. Attributing by +the child/sub-session that actually loaded the lens keeps the count clean and +excludes the inline variant's host-session noise automatically. + +## Section 4 — Worked example (what the derived dimension revealed) + +Applying the flavour metric to a real corpus of ~2,600 delegations: + +| Metric | Blanket read | Council-driven | Derived read (council removed) | +|---|---|---|---| +| Self-delegation share | **42.0%** | 893 | **11.7%** | +| `none/conversation` share | **70.2%** | 893 | **54.6%** | + +Reading: + +- **893 delegations (34%) were one review panel** convening its lenses — invisible + on the transport axis, obvious on the flavour axis (100% self / none / + conversation with a persona `skill_name` payload). +- **Self-delegation was ~82% a panel artifact.** The flat "self-delegation + dominates" finding was an aggregate illusion; outside the panel, self-delegation + is a marginal ~12% tactic. +- **`none/conversation` survived as a genuine default** (54.6%) but dropped from a + landslide to a plurality once the derived population was removed. + +The Move-3 recompute is the whole finding. Without it you would have shipped +"self-delegation dominates," which is false. + +## Section 5 — The metric generalizes (other derived dimensions) + +Flavour is one instance. The same three moves build others: + +**Context-sink vs offload (magnitude join).** Both are `none/conversation` with a +NULL skill payload — categorically identical. Discriminate on *work volume inside +the sub-session*: sum iterations, tool calls, or token/`content_length` proxies. +High volume + broad file reads = context-sink (the parent offloaded token cost); +low volume = light task-offload. Here the discriminating signal is a *magnitude*, +not a category. + +```cypher +// Magnitude proxy: iteration + tool-call volume inside each spawned sub-session. +MATCH (parent:Session {workspace: $workspace}) + -[:HAS_EXECUTION]->(:OrchestratorRun)-[:HAS_PART]->(:Iteration) + -[:HAS_TOOL_CALL]->(:ToolCall)-[:TRIGGERED]->(d:Delegation) +WHERE d.context_depth = 'none' AND d.context_scope = 'conversation' +MATCH (sub:Session {node_id: d.sub_session_id}) +OPTIONAL MATCH (sub)-[:HAS_EXECUTION]->(:OrchestratorRun)-[:HAS_PART]->(it:Iteration) +OPTIONAL MATCH (it)-[:HAS_TOOL_CALL]->(tc:ToolCall) +RETURN d.agent AS agent, + count(DISTINCT it) AS iterations, + count(tc) AS tool_calls +ORDER BY tool_calls DESC +LIMIT 50 +``` + +**Continuity handoff (artifact join).** `recent` / `all` transport paired with what +the sub-session PRODUCED — a commit, a PR, a written file. Transport says "this +agent inherited context"; the artifact says "…because it had to author something +faithful to the session's history." That pairing is the signature of a genuine +continuity handoff versus a needlessly heavy context pass. + +The recipe never changes: **blanket shape → discriminating second signal (category, +magnitude, or artifact) → segment and recompute with the derived population +removed.** + +## Section 6 — Discipline and traps + +- **Recompute-with-removed is mandatory.** A derived dimension you don't subtract + out is just a colorful column. The finding is the delta to the headline. +- **Causal, not spurious.** Before trusting a join, ask whether the second signal + *explains* the intent or merely co-occurs. The child-vs-parent attribution trap + (Section 3) is a spurious-correlation trap: the parent-session join correlates + but does not attribute. +- **Verify the live schema.** `Delegation.sub_session_id`, `Session.node_id`, and + the `SkillLoad` attachment points are the load-bearing joins — confirm them with + `CALL db.schema.nodeTypeProperties()` before relying on them. Note two properties + seen live but NOT documented in `context-intelligence-graph-query` at time of + writing: a `resolved_agent` on `Delegation` and a `context` (e.g. `"fork"`) on + `SkillLoad`. Treat them as *verify-before-cite*; the queries here deliberately + depend only on documented properties (`agent`, `skill_name`) so they work either + way. +- **Size discipline still applies.** Derived-metric queries aggregate — return + counts and small grouped rows, never the full text of many rows. Everything in + graph-query Section 6 holds. +- **Scope honestly.** Corpus mix skews absolute numbers (a dev-heavy workspace + inflates git-ops and panel traffic). Report the scope with the metric, and offer + the single-workspace recompute. + +## Section 7 — When to reach for this + +- A query's headline is dominated by one structural mode and you can't narrate why + each row happened → build a flavour/derived metric before reporting the mode. +- Someone asks "what is this agent/session actually *doing*" and the transport + fields don't answer it → the answer lives in the payload/magnitude/artifact + layer. +- You're about to report an aggregate ("X dominates", "most delegations are Y") → + run the recompute-with-removed once to check the aggregate isn't an artifact of a + single hidden sub-population. + +Do NOT reach for it for a genuinely homogeneous population, or when the raw fields +already narrate the row (a `recent`/`all` git-ops delegation explains itself). A +derived metric you compute for everything stops being a signal.