pi-eda 0.1.0 → 0.2.0

package/README.md

@@ -5,6 +5,7 @@ Pi skills and subagents for interactive exploratory data analysis.
 - `skills/exploring-data`: iterative analysis & plotting
 - `skills/finishing-exploratory-data-analysis`: locking in analysis into a wiki-style report
 - `show` extension: renders a figure to the user in the TUI without spending tokens on it
+- `eda-workflow-tracker` extension: tracks stage progress through `exploring-data`'s workflow graph
 
 ## Requires
 

package/agents/job-runner.md

@@ -1,6 +1,6 @@
 ---
 name: job-runner
-description: Launches and monitors a heavy/long-running analysis script in the background
+description: Launches a heavy/long-running analysis script under a memory cap and blocks on it
 tools: bash, read
 inheritProjectContext: true
 ---
@@ -12,23 +12,26 @@ that already happened before you were dispatched.
 ## What to do
 
 - Confirm inputs before launching:
-  - The estimated runtime and peak memory from the smoke test (should be
-      in the task you were given -- if missing, ask the dispatching agent
-      for it rather than guessing).
-  - Whether `systemd-run` is available on this machine.
-- Launch the script as a background process (following the project's run
-  convention, e.g. `uv run`).
-- Cap it with a memory limit so a runaway process gets killed by the OS
-  instead of taking down the machine, sized off the estimate with
-  headroom (e.g. 2x the estimated peak):
-  - `systemd-run --scope -p MemoryMax=<budget> --user -- uv run <script>`
-      if available.
-  - Otherwise, say so explicitly and fall back to periodic `ps`/`smem`
-      checks with a manual kill.
-- Monitor progress and memory use periodically rather than blocking on it
-  synchronously -- this is in addition to the hard cap above, not a
-  replacement for it, since you want to know about a job trending toward
-  the ceiling before it gets killed.
+  - The estimated runtime (should be in the task you were given -- if
+      missing, ask the dispatching agent rather than guessing).
+  - Whether `systemd-run` is available (Linux only -- no shell-level
+      equivalent on macOS or Windows).
+  - Determine how much memory can be used for the process. Check
+    available memory with `free -m` and leave at least 1GB free.
+- If `systemd-run` is available:
+  - Run in the foreground, blocked on completion using:
+  `systemd-run --scope -p MemoryMax=<budget> --user -- uv run <script>`.
+  - The cap is the safety net, so you should not:
+    - Poll for memory consumption
+    - Detach from the process
+- If `systemd-run` is not available:
+  - Say so explicitly. There is no OS cap here, so you are the safety
+    net.
+  - Launch the script as a separate process, then poll memory yourself
+    against the memory budget.
+  - Do this as a *single* bash call with an internal sleep/check loop.
+    Kill and report if it crosses the budget to save token context.
+    Do not use separate agent turns here.
 - Report back once it completes: success/failure, runtime, and where the
   output landed. On failure, include the actual error, not just "it
   failed."

package/extensions/eda-workflow-tracker.ts

@@ -0,0 +1,266 @@
+/**
+ * Workflow Tracker Extension
+ *
+ * A native pi tool for tracking progress through a named-state workflow
+ * graph (branches + loop-backs), not a flat todo list. Purely descriptive:
+ * nothing downstream enforces it, `advance` just validates the move is
+ * legal and remembers where the agent said it is.
+ *
+ * State is stored in tool result details for proper branching support,
+ * same restore-from-branch pattern as plan_tracker. Shows a one-line
+ * status widget with the raw current node name -- transparency for the
+ * user, not enforcement.
+ *
+ * Pure logic lives in lib/eda-workflow-tracker-core.ts for testability. Nested
+ * one level deep (not top-level extensions/, not an index.ts subdir) so pi's
+ * extension auto-discovery does not try to load it as a standalone extension.
+ */
+
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import {
+  type WorkflowGraph,
+  type WorkflowTrackerDetails,
+  type BranchEntry,
+  type ActionResult,
+  isValidGraph,
+  handleInit,
+  handleAdvance,
+  handleStatus,
+  handleClear,
+  formatWidgetText,
+  reconstructFromBranch,
+} from "./lib/eda-workflow-tracker-core.js";
+
+const WorkflowTrackerParams = Type.Object({
+  action: Type.Union(
+    [
+      Type.Literal("init"),
+      Type.Literal("advance"),
+      Type.Literal("status"),
+      Type.Literal("clear"),
+    ],
+    { description: "Action to perform" },
+  ),
+  graphPath: Type.Optional(
+    Type.String({
+      description:
+        "Path to a workflow.graph.json ({ start, edges }) (for init)",
+    }),
+  ),
+  to: Type.Optional(
+    Type.String({
+      description: "Node name to advance to (for advance)",
+    }),
+  ),
+  force: Type.Optional(
+    Type.Boolean({
+      description:
+        "Allow advancing to any valid node in the graph, not just ones adjacent to the current node (for advance)",
+    }),
+  ),
+});
+
+export type WorkflowTrackerInput = Static<typeof WorkflowTrackerParams>;
+
+export default function (pi: ExtensionAPI) {
+  let graphPath = "";
+  let graph: WorkflowGraph | undefined;
+  let current = "";
+
+  const loadGraphFile = async (cwd: string, path: string): Promise<unknown> => {
+    const raw = await readFile(resolve(cwd, path), "utf-8");
+    return JSON.parse(raw);
+  };
+
+  const reconstructState = async (ctx: ExtensionContext) => {
+    const state = reconstructFromBranch(
+      ctx.sessionManager.getBranch() as BranchEntry[],
+    );
+    graphPath = state.graphPath;
+    current = state.current;
+    graph = undefined;
+    if (!graphPath) return;
+    try {
+      const parsed = await loadGraphFile(ctx.cwd, graphPath);
+      if (isValidGraph(parsed)) graph = parsed;
+    } catch {
+      // leave graph undefined -- advance/status report it as not loaded
+    }
+  };
+
+  const updateWidget = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    const text = formatWidgetText(current);
+    if (text) {
+      ctx.ui.setWidget("eda-workflow-tracker", (_tui, theme) => {
+        return new Text(theme.fg("muted", text), 0, 0);
+      });
+    } else {
+      ctx.ui.setWidget("eda-workflow-tracker", undefined);
+    }
+  };
+
+  for (const event of [
+    "session_start",
+    "session_switch",
+    "session_fork",
+    "session_tree",
+  ] as const) {
+    pi.on(event, async (_event, ctx) => {
+      await reconstructState(ctx);
+      updateWidget(ctx);
+    });
+  }
+
+  pi.registerTool({
+    name: "eda-workflow-tracker",
+    label: "Workflow Tracker",
+    description:
+      "Track the current state in a named-state workflow graph (branches/loop-backs, not a flat " +
+      "todo list). Actions: init (load a workflow.graph.json and set current to its start), " +
+      "advance (move to a node; must be adjacent to current unless force is set, in which case " +
+      "any valid node in the graph is allowed), status (show current state), clear (reset).",
+    parameters: WorkflowTrackerParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      let result: ActionResult;
+
+      switch (params.action) {
+        case "init": {
+          if (!params.graphPath) {
+            result = {
+              graphPath,
+              current,
+              next: [],
+              error: "graphPath required for init",
+            };
+            break;
+          }
+          try {
+            const parsed = await loadGraphFile(ctx.cwd, params.graphPath);
+            if (!isValidGraph(parsed)) {
+              throw new Error("expected { start: string, edges: object }");
+            }
+            graph = parsed;
+          } catch (err) {
+            result = {
+              graphPath,
+              current,
+              next: [],
+              error: `failed to load graph at "${params.graphPath}": ${(err as Error).message}`,
+            };
+            break;
+          }
+          result = handleInit(graph, params.graphPath);
+          graphPath = result.graphPath;
+          current = result.current;
+          updateWidget(ctx);
+          break;
+        }
+        case "advance": {
+          if (!graph) {
+            result = {
+              graphPath,
+              current,
+              next: [],
+              error: "no graph loaded -- call init first",
+            };
+            break;
+          }
+          if (!params.to) {
+            result = {
+              graphPath,
+              current,
+              next: [],
+              error: "to required for advance",
+            };
+            break;
+          }
+          result = handleAdvance(
+            graph,
+            current,
+            params.to,
+            params.force ?? false,
+            graphPath,
+          );
+          current = result.current;
+          updateWidget(ctx);
+          break;
+        }
+        case "status": {
+          result = handleStatus(graph, current, graphPath);
+          break;
+        }
+        case "clear": {
+          result = handleClear();
+          graphPath = result.graphPath;
+          current = result.current;
+          graph = undefined;
+          updateWidget(ctx);
+          break;
+        }
+        default: {
+          result = {
+            graphPath,
+            current,
+            next: [],
+            error: `unknown action: ${params.action as string}`,
+          };
+        }
+      }
+
+      const details: WorkflowTrackerDetails = {
+        action: params.action,
+        graphPath: result.graphPath,
+        current: result.current,
+        next: result.next,
+        ...(result.error ? { error: result.error } : {}),
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: result.error
+              ? `Error: ${result.error}`
+              : `current: "${result.current}"; next: ${JSON.stringify(result.next)}`,
+          },
+        ],
+        details,
+      };
+    },
+
+    renderCall(args, theme) {
+      let text = theme.fg("toolTitle", theme.bold("eda-workflow-tracker "));
+      text += theme.fg("muted", args.action);
+      if (args.action === "advance" && args.to) {
+        text += ` -> ${theme.fg("accent", args.to)}`;
+        if (args.force) text += theme.fg("dim", " (force)");
+      }
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as WorkflowTrackerDetails | undefined;
+      if (!details) {
+        const text = result.content[0];
+        return new Text(text?.type === "text" ? text.text : "", 0, 0);
+      }
+      if (details.error) {
+        return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
+      }
+      return new Text(
+        theme.fg("success", "✓ ") + theme.fg("muted", details.current),
+        0,
+        0,
+      );
+    },
+  });
+}

package/extensions/lib/eda-workflow-tracker-core.ts

@@ -0,0 +1,158 @@
+/**
+ * Workflow Tracker Core Logic
+ *
+ * Pure functions for a graph-shaped (not list-shaped) progress tracker:
+ * "current" is a node name in a caller-supplied edges map, advanced by
+ * naming the next node rather than by index. No pi dependencies.
+ */
+
+export interface WorkflowGraph {
+  start: string;
+  edges: Record<string, string[]>;
+}
+
+/** True if `value` has the { start: string, edges: object } shape a WorkflowGraph requires. */
+export function isValidGraph(value: unknown): value is WorkflowGraph {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate.start === "string" &&
+    typeof candidate.edges === "object" &&
+    candidate.edges !== null
+  );
+}
+
+export interface WorkflowTrackerDetails {
+  action: "init" | "advance" | "status" | "clear";
+  graphPath: string;
+  current: string;
+  next: string[];
+  error?: string;
+}
+
+export interface ActionResult {
+  graphPath: string;
+  current: string;
+  next: string[];
+  error?: string;
+}
+
+/** Nodes reachable in one step from `node`, or [] if none/no graph loaded. */
+function nextFrom(graph: WorkflowGraph | undefined, node: string): string[] {
+  return graph?.edges[node] ?? [];
+}
+
+function allNodes(edges: Record<string, string[]>): Set<string> {
+  const nodes = new Set<string>(Object.keys(edges));
+  for (const targets of Object.values(edges)) {
+    for (const target of targets) nodes.add(target);
+  }
+  return nodes;
+}
+
+/** Case-insensitive lookup: returns the canonically-cased node name, or undefined if none matches. */
+function canonicalize(
+  candidates: Iterable<string>,
+  name: string,
+): string | undefined {
+  const lower = name.toLowerCase();
+  for (const candidate of candidates) {
+    if (candidate.toLowerCase() === lower) return candidate;
+  }
+  return undefined;
+}
+
+export function handleInit(
+  graph: WorkflowGraph,
+  graphPath: string,
+): ActionResult {
+  return {
+    graphPath,
+    current: graph.start,
+    next: nextFrom(graph, graph.start),
+  };
+}
+
+export function handleAdvance(
+  graph: WorkflowGraph,
+  current: string,
+  to: string,
+  force: boolean,
+  graphPath = "",
+): ActionResult {
+  const legalFromCurrent = graph.edges[current] ?? [];
+
+  if (!force) {
+    const canonical = canonicalize(legalFromCurrent, to);
+    if (!canonical) {
+      return {
+        graphPath,
+        current,
+        next: legalFromCurrent,
+        error: `"${to}" is not reachable from "${current}"; legal: ${JSON.stringify(legalFromCurrent)}`,
+      };
+    }
+    return { graphPath, current: canonical, next: nextFrom(graph, canonical) };
+  }
+
+  const canonical = canonicalize(allNodes(graph.edges), to);
+  if (!canonical) {
+    return {
+      graphPath,
+      current,
+      next: legalFromCurrent,
+      error: `"${to}" is not a known node in this graph; legal: ${JSON.stringify(legalFromCurrent)}`,
+    };
+  }
+  return { graphPath, current: canonical, next: nextFrom(graph, canonical) };
+}
+
+export function handleStatus(
+  graph: WorkflowGraph | undefined,
+  current: string,
+  graphPath = "",
+): ActionResult {
+  return { graphPath, current, next: nextFrom(graph, current) };
+}
+
+export function handleClear(): ActionResult {
+  return { graphPath: "", current: "", next: [] };
+}
+
+export function formatWidgetText(current: string): string | undefined {
+  return current ? `EDA workflow: ${current}` : undefined;
+}
+
+// --- State Reconstruction ---
+
+export interface BranchEntry {
+  type: string;
+  message?: {
+    role: string;
+    toolName?: string;
+    details?: WorkflowTrackerDetails;
+  };
+}
+
+export function reconstructFromBranch(entries: BranchEntry[]): ActionResult {
+  let state: ActionResult = { graphPath: "", current: "", next: [] };
+  for (const entry of entries) {
+    if (entry.type !== "message") continue;
+    const msg = entry.message;
+    if (
+      !msg ||
+      msg.role !== "toolResult" ||
+      msg.toolName !== "eda-workflow-tracker"
+    )
+      continue;
+    const details = msg.details;
+    if (details && !details.error) {
+      state = {
+        graphPath: details.graphPath,
+        current: details.current,
+        next: details.next,
+      };
+    }
+  }
+  return state;
+}

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "pi-eda",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi tooling for interactive exploratory data analysis.",
   "license": "MIT",
   "author": "Shivam V Verma",
-  "keywords": ["pi-package", "pi", "eda", "exploratory-data-analysis"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shivam-v-verma/pi-eda.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "eda",
+    "exploratory-data-analysis"
+  ],
   "files": [
     "README.md",
     "agents",
@@ -12,16 +21,29 @@
     "extensions",
     "skills"
   ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
+  "devDependencies": {
+    "vitest": "^4.1.11"
+  },
   "pi": {
-    "extensions": ["./extensions"],
-    "skills": ["./skills"],
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ],
     "subagents": {
-      "agents": ["./agents"]
+      "agents": [
+        "./agents"
+      ]
     }
   }
 }

package/skills/exploring-data/SKILL.md

@@ -23,9 +23,15 @@ and suggest or build the plots that interrogate them. What a confirmed pattern
 *means*, the story it tells, is the user's call: hand back a clear summary of
 what the figure shows, not a conclusion dressed as a finding.
 
-See `workflow.md` for stages of this skill. In all stages, confirm framing
-with the user. Never run a batch of steps by yourself; always interleave
-by checking for the user's insight/thoughts.
+If using this skill, you **must** first:
+
+- Run `init` on `eda-workflow-tracker` with `graphPath:
+  "skills/exploring-data/workflow.graph.json"` for guidance on what stage you
+  should be working on.
+- Read `workflow.md` for instructions for each stage.
+
+**Always call `advance` on the `eda-workflow-tracker` when done with a
+stage before performing the next action or moving on to the next stage.**
 
 A good hypothesis is usually a simple, clean one -- reachable through better
 framing of the question, not through aggressively slicing the dataset more ways
@@ -59,10 +65,12 @@ its own narrower table.
 
 | Mistake | Fix |
 | --- | --- |
-| Running the full dataset before a smoke test | See `checking-and-running-scripts.md` -- always sample/time on a subset first |
-| Auto-advancing to the next question without a framing check | See `pre-code-checkpoints.md` -- confirm framing before each new question, not once for the whole analysis |
+| Doing any work using this skill (e.g. scoping the analysis, peeking at data, building a script) without having initialized `eda-workflow-tracker` with `init` | `init` as soon as you decide to use this skill. `eda-workflow-tracker` is essential to this skill. |
+| Doing a stage without calling `advance` after it | Treat `advance` as part of finishing the stage, not separate bookkeeping. If you just did something on the graph, the next tool call is `advance`, not the action of the next stage |
+| Running the full dataset before a smoke test | See `workflow.md` (`Build script/plot`) -- always sample/time on a subset first |
+| Auto-advancing to the next question without a framing check | See `workflow.md` (`Propose/ask a question`) -- confirm framing before each new question, not once for the whole analysis |
 | Picking the report/subfolder name yourself instead of asking | Ask before creating it -- one name, shared by the file and its folder |
-| Launching a heavy scale-up run while the `script-checker` is still pending | See `checking-and-running-scripts.md` -- wait for it, or the expensive run finishes before a material issue could surface |
+| Launching a heavy scale-up run while the `script-checker` is still pending | See `workflow.md` (`Dispatch script-checker`) -- wait for it, or the expensive run finishes before a material issue could surface |
 | Deleting/pruning a failed or paused script | Leave it in place with a status docstring unless the user explicitly asks to remove it |
 | Treating an approval-sounding signal ("looks great", "keep going", "I trust your judgment") as done | Ask whether to move to `/skill:finishing-exploratory-data-analysis` -- don't auto-advance and don't stay silent |
 | Chasing a pattern that only appears after trying many slices/cuts of the data | Multiple-comparisons risk -- go back to framing, not more cuts |

package/skills/exploring-data/workflow.graph.json

@@ -0,0 +1,19 @@
+{
+  "start": "Scope the analysis",
+  "edges": {
+    "Scope the analysis": ["Peek at the data"],
+    "Peek at the data": ["Propose/ask a question"],
+    "Propose/ask a question": ["Build script/plot"],
+    "Build script/plot": ["Light or heavy?"],
+    "Light or heavy?": ["Reread script", "Dispatch script-checker"],
+    "Reread script": ["Build script/plot", "Run now, this session"],
+    "Dispatch script-checker": ["Build script/plot", "Dispatch job-runner"],
+    "Run now, this session": ["Summarize the answer"],
+    "Dispatch job-runner": ["Summarize the answer"],
+    "Summarize the answer": ["Continue analysis or lock in?"],
+    "Continue analysis or lock in?": [
+      "Propose/ask a question",
+      "/skill:finishing-exploratory-data-analysis"
+    ]
+  }
+}

package/skills/exploring-data/workflow.md

@@ -1,66 +1,184 @@
 # Workflow
 
-Loop/flow-control for `/skill:exploring-data`.
-
-The user drives this loop: they propose or pick the next thing to plot or
-check, you build it and return what it shows. They then interpret it
-and pick next steps or ask additional questions.
-
-This is a looped pipeline, exiting only when the user decides to
-lock-in an analysis.
-
-```dot
-digraph EDA_WORKFLOW {
-    "Start analysis" [shape=doublecircle];
-    "Scope the analysis" [shape=box, style=filled, fillcolor=lightblue];
-    "Peek at the data" [shape=box, style=filled, fillcolor=lightyellow];
-    "Propose/ask a question" [shape=box, style=filled, fillcolor=lightblue];
-    "Build script/plot" [shape=box];
-    "light or heavy?" [shape=diamond];
-    "Reread script" [shape=box];
-    "Dispatch script-checker (blocking)" [shape=box];
-    "run now, this session" [shape=box];
-    "Dispatch job-runner" [shape=box];
-    "Summarize the answer" [shape=box, style=filled, fillcolor=lightyellow];
-    "Continue analysis or lock in?" [shape=diamond, style=filled, fillcolor=lightblue];
-    "/skill:finishing-exploratory-data-analysis" [shape=doublecircle];
-
-    "Start analysis" -> "Scope the analysis";
-    "Scope the analysis" -> "Peek at the data";
-    "Peek at the data" -> "Propose/ask a question";
-    "Propose/ask a question" -> "Build script/plot";
-    "Build script/plot" -> "light or heavy?";
-    "light or heavy?" -> "Reread script" [label="light"];
-    "Reread script" -> "Build script/plot" [label="issues found"];
-    "Reread script" -> "run now, this session" [label="looks right"];
-    "light or heavy?" -> "Dispatch script-checker (blocking)" [label="heavy"];
-    "Dispatch script-checker (blocking)" -> "Build script/plot" [label="issues found"];
-    "Dispatch script-checker (blocking)" -> "Dispatch job-runner" [label="clean"];
-    "run now, this session" -> "Summarize the answer";
-    "Dispatch job-runner" -> "Summarize the answer";
-    "Summarize the answer" -> "Continue analysis or lock in?";
-    "Continue analysis or lock in?" -> "Propose/ask a question" [label="next question"];
-    "Continue analysis or lock in?" -> "/skill:finishing-exploratory-data-analysis" [label="finish analysis"];
-}
-```
-
-(blue = User turn, yellow = Agent -> User handoff, white = Agent-only)
-
-| Stage | Turn | What it looks like | See |
-| --- | --- | --- | --- |
-| Scope the analysis | User | State the broad scope/question area for this analysis and confirm it, once per analysis, before touching data | `pre-code-checkpoints.md` (Scope the analysis) |
-| Peek at the data | Agent -> User | Schema/dtypes, `.head()`, a sample, eyeball raw rows, hand back for a look | `pre-code-checkpoints.md` (Peek at the data) |
-| Propose/ask a question | User (agent may suggest) | Confirm framing for the next question, then the user picks what to plot or check | `pre-code-checkpoints.md` (Propose/ask a question) |
-| Build script/plot | Agent | Write the script/plot, smoke test on a subset before scaling | `checking-and-running-scripts.md`, `plotting.md` |
-| light or heavy? | Agent | Judge from the smoke-test timing/size ratio | `checking-and-running-scripts.md` |
-| Reread script | Agent | Light: reread the script yourself before running -- no `script-checker` dispatch, loop back to the script on issues you find | `checking-and-running-scripts.md` |
-| Dispatch script-checker (blocking) / Dispatch job-runner | Agent | Heavy: dispatch the `script-checker` and wait; loop back to the script on findings; don't launch the `job-runner` until it's clean | `checking-and-running-scripts.md` |
-| Summarize the answer | Agent -> User | Interpret the figure/stats as a summary, not a conclusion -- the user decides what it means and what's next | `SKILL.md` Core principle |
-| Lock-in checkpoint | User | Figure/analysis seems meaningful, ready to write up or commit | `/skill:finishing-exploratory-data-analysis` |
+This file is the legend for the EDA workflow.
+
+Use the `eda-workflow-tracker` tool to determine what stage you're on; perform
+exactly that stage of work; and then call `advance` before starting the next
+stage. Call `status` whenever you need to know where you are instead of holding
+it in your head.
+
+At the end of every turn, ask yourself if you have accomplished the exit 
+condition to `advance` to the next stage.
+
+- If yes, `advance` should **always** be your first tool call.
+- If no, keep working on the stage until you have reached the exit condition.
+
+## Stages
+
+### `Scope the analysis`
+
+- Before opening the data, ask in one or two sentences what is broadly in
+  scope for this analysis. This is a "what are we even doing here", at a
+  high level.
+- Keep interrogating until the user agrees with the framing. Do not advance
+  on a partial answer or lukewarm agreement.
+- Ask the user for a report name for this analysis -- it names both the
+  report file and its paired folder (see `directory-structure.md`).
+  Don't pick one yourself. Keep asking until they give one.
+- Expect the scope to narrow or shift as the data yields a story during
+  this analysis. This step is purely for you to ground yourself.
+- You should **never** be running code at this stage. If the user has
+  already offered specific questions/approaches, you must confirm your
+  understanding and then `advance`.
+- `advance` condition: the user has confirmed the scope of the analysis and has
+  given a report name; or the user has already requested a specific question.
+
+### `Peek at the data`
+
+- Load the dataset (lazily), check schema/dtypes.
+- Get null counts and basic summary stats (mean/median, min/max, std).
+- Get a feel for the actual data: `.head()`, a strided sample, or a random
+  sample (fixed seed).
+- Read a few raw rows by eye. They catch what schema/dtype checks and basic
+  stats above miss: a "numeric" column that's really a formatted string,
+  an ID convention, units, or what a free-text field actually holds.
+- Even raw rows and basic stats can miss duplicate rows.
+- Beyond that, think about what else is cheap to calculate and might
+  reveal something missed above -- e.g. sentinel/placeholder values (`-1`,
+  `0`, `"unknown"`), class imbalance, or a grain mismatch after a join.
+- `advance` condition: you understand the high-level structure of the data.
+
+### `Propose/ask a question`
+
+- Propose a framing for *this* question/figure yourself, then keep
+  interrogating until the user agrees with it, before writing a script for it.
+- You can refine the approach by writing/executing some code, but don't write
+  any scripts in the directory yet. This is exploratory, not polish.
+- The goal here is focus: work with the user to identify a specific, question
+  that can be tested with data. Do not attempt many questions or approaches at
+  once. Iterate one at a time with the user until it's settled.
+- If the user has already proposed a specific question, confirm your
+  understanding vocally and then `advance`.
+- `advance` condition: You have explained what you plan to do, and the user
+  agrees with the question and approach.
+
+### `Build script/plot`
+
+Goal: Write the script/plot (see `plotting.md` for chart conventions), then
+build confidence in it:
+
+- After each nontrivial transform (groupby, join, pivot, filter, etc.), do
+  a quick check (`.head()`, row counts, spot-check a few values) that the
+  output matches what the transform should have done. Don't just do this once
+  at the end of the script.
+- Pick a case that could actually fail, not the first one at hand.
+  especially for canonicalization/ordering/matching logic, where an easy
+  case can pass while hiding a real bug.
+- Time the script on a small subset of the data to understand how long the
+  full scale run will take
+- Glance at the actual output values to sanity check the output.
+- `advance` condition: the script is written and each nontrivial transform has
+  been spot-checked.
+
+### `Light or heavy?`
+
+Goal: Decide whether the full scale run will be a light task or a heavy task.
+We want to increase iteration speed and not waste user time.
+
+- Judge from the smoke-test timing/size ratio whether the full-scale run
+  will be heavy (long-running or memory-heavy relative to the sample --
+  e.g. 1% took a second but full scale extrapolates to minutes).
+- Rough thresholds based on estimated time: light if under ~1 minute,
+  heavy if over ~5 minutes. In between is a judgment call.
+- State that judgment explicitly: "sample took Xs, full run estimated ~Y,
+  treating as heavy."
+- `advance` condition: you understand the computational cost of the script.
+
+### `Reread script`
+
+Light path: Reread the script as a sanity check.
+
+- Does it match the user's stated intent/framing, does each nontrivial
+  transform do what it should?
+- If the reread surfaces an issue, fix it and reread again before
+  running. Don't run first and raise the concern after.
+- This is a deliberately lower bar than the heavy path. A subtle mistake here
+  can also be caught downstream in `/skill:finishing-exploratory-data-analysis`.
+  We just want to sanity check here.
+- `advance` condition: you have reread the script and haven't found issues.
+
+### `Run now, this session`
+
+Light path continuation: run the smoke-tested script/plot in this session.
+
+- `advance` condition: you have run the script successfully on the data.
+
+### `Dispatch script-checker`
+
+Heavy path: dispatch the `script-checker` and wait, before launching.
+
+- `subagent({agent:"script-checker",
+  task:"<script path + stated intent/framing>"})`.
+- This must be a blocking call. wait for the `script-checker` to finish. You
+  don't want to surface issues after the expensive run has finished. We want to
+  catch all issues here.
+- Two or more edits since the last `script-checker` dispatch count as one
+  nontrivial change on their own. Dispatch again at that point; don't wait for
+  it to feel big enough.
+- "Issues found" loops back to `Build script/plot`, "clean" goes to `Dispatch
+  job-runner`.
+- `advance` condition: `script-checker` has not found substantial issues, and
+  all issues have been handled and rechecked.
+
+### `Dispatch job-runner`
+
+Heavy path continuation: launch the `job-runner` only once the
+`script-checker` is clean.
+
+- Run the `job runner` with `subagent({agent:"job-runner", task:"<script path +
+  output location + estimated runtime>"})`.
+- Pass the runtime estimate to the `job-runner` from your smoke test in
+  `Light or heavy?` above rather than making it re-derive it blind.
+- Register a wake instead of blocking: `subagent_wait({id, nonBlocking: true})`
+  after launching. Non-blocking waits allow you to continue the conversation
+  with the user while waiting.
+- `advance` condition: `job-runner` has successfully completed the job.
+
+### `Summarize the answer`
+
+- `show` the figure(s) to the user, then summarize briefly with bullets.
+- Core principle: the user decides the interpretation. Continue interrogating
+  the user until it makes sense to you and is consistent with the dataset.
+- `advance` condition: you understand the user's interpretation of the figure.
+
+### `Continue analysis or lock in?`
+
+- Ask the user whether to continue with another question or lock in the
+  analysis; keep interrogating until they pick one. "Next question" loops back
+  to `Propose/ask a question`, "finish analysis" exits to the finishing skill.
+- `advance` condition: the user has decided to continue the session or finish it.
+
+### `/skill:finishing-exploratory-data-analysis`
+
+Figure/analysis seems meaningful, ready to write up or commit.
 
 ## Common Mistakes
 
 | Mistake | Fix |
 | --- | --- |
-| Treating any issue in scripts (via self-reread or `script-checker`) as a note to fold in later instead of a loop back to the script | Go to "Build script/plot" and fix it -- see the graph's "issues found" edges |
-| Launching a heavy scale-up while the `script-checker` is still pending or has open findings | See `checking-and-running-scripts.md`'s Common Mistakes |
+| Getting the user's agreement on a confirmation stage, then acting on it without calling `advance` first | The agreement itself completes the stage -- `advance` is the first tool call once you have it, not a follow-up after next-stage work has already started |
+| Treating any issue in scripts (via self-reread or `script-checker`) as a note to fold in later instead of a loop back to the script | Go to `Build script/plot` and fix it -- see the graph's "issues found" edges |
+| Opening the data before agreeing on a broad scope | State the analysis's scope/question area in a sentence and confirm before `Peek at the data` |
+| Picking the report/subfolder name yourself instead of asking | Ask before creating it -- one name, shared by the file and its folder |
+| Treating EDA as a pipeline and auto-advancing through questions without a framing check | Confirm framing per question, not once for the whole analysis |
+| Adding a follow-up figure/question under an earlier blanket go-ahead without confirming its framing | State the new framing in a sentence before scripting it |
+| Building the next two questions back-to-back and presenting a "complete report" because the user said "keep going" / "I trust your judgment" | That phrase covers continued work, not skipped per-question confirmation -- stop after each one |
+| Skipping the raw-row eyeball and stopping at summary stats | Read a few actual rows -- aggregates hide format/unit/encoding surprises |
+| Running the full dataset (or an ad hoc exploratory probe) before a smoke test | Always sample/time on a subset first -- applies to one-off probes too, not just numbered scripts |
+| Silently skipping the smoke test on a "just read cache and plot" script | Only skip for zero-computation cached-read-and-plot, and state that justification explicitly |
+| Trusting a sanity check that only ran on an easy/symmetric case | Pick a case that could actually have failed, especially for matching/ordering/canonicalization logic |
+| Checking that a smoke test ran fast/clean without looking at what it produced | Glance at the actual output values -- a clean run on garbage isn't a pass |
+| Running a light-path script without rereading it first because it's "just quick" | Reread against the stated intent/framing before running -- speed doesn't waive the check, it just changes who does it |
+| Launching a heavy scale-up "while the `script-checker` runs in the background" instead of waiting for it | Confirm the `script-checker` came back clean before launching -- don't launch and plan to fold feedback in later |
+| Letting 2+ small edits pile up on a heavy-path script since the last `script-checker` dispatch because none felt big enough alone | Dispatch again once 2+ edits have landed |
+| Treating a mid-work `script-checker` pass as covering the finishing skill's lock-in checkpoint | Different gate, different artifact -- a pending or completed `script-checker` pass never substitutes for it |

package/skills/exploring-data/checking-and-running-scripts.md

@@ -1,97 +0,0 @@
-# Checking and Running Scripts
-
-Building confidence in a script for `/skill:exploring-data`, then deciding
-how to run it. See `workflow.md` for where this fits in the full loop
-(the light/heavy fork is inlined there, each branch with its own check
-step and loop-back on findings).
-
-## Sanity Checking a Script
-
-- After each nontrivial transform (groupby, join, pivot, filter, etc.), do
-  a quick check (`.head()`, row counts, spot-check a few values) that the
-  output matches what the transform should have done -- not just once at
-  the end of the script.
-- Pick a case that could actually fail, not the first one at hand --
-  especially for canonicalization/ordering/matching logic, where an easy
-  case can pass while hiding a real bug.
-
-## Smoke Testing a Script
-
-- Run on a sampled/head subset (fixed seed) and time it before running at
-  full scale.
-- After it runs, glance at the actual output values, not just "it
-  completed in time." A fast clean run on garbage output is not a
-  passing smoke test.
-- Exception: a cached-read-and-plot script -- one that purely reads an
-  already-validated cached table and plots it, with zero computation (no
-  groupby, join, pivot, or filter). State that justification explicitly
-  instead of skipping silently.
-
-## Judging Heavy vs. Light Scale-up
-
-Goal: increase iteration speed without being reckless. Either extreme
-wastes the user's time -- blocking every quick diff on a check likely to
-pass, or committing to a large/expensive run that turns out wrong.
-
-- Judge from the smoke-test timing/size ratio whether the full-scale run
-  will be heavy (long-running or memory-heavy relative to the sample --
-  e.g. 1% took a second but full scale extrapolates to minutes).
-- Rough thresholds based on estimated time: light if under ~1 minute,
-  heavy if over ~5 minutes. In between is a judgment call.
-- State that judgment explicitly: "sample took Xs, full run estimated ~Y,
-  treating as heavy."
-
-## Light Scale-up
-
-- No `script-checker` dispatch -- reread the script yourself before
-  running: does it match the user's stated intent/framing, does each
-  nontrivial transform do what it should.
-- If the reread surfaces an issue, fix it and reread again before
-  running -- don't run first and raise the concern after.
-- This is a deliberately lower bar than the heavy path: a light-path
-  mistake is cheap to catch downstream too, since the run finishes fast
-  and you're looking at the output right away. The real second-set-of-
-  eyes gate for the analysis still happens at
-  `/skill:finishing-exploratory-data-analysis`'s lock-in checkpoint --
-  this reread isn't the last line of defense, it's a cheap intermediate
-  one.
-
-## Heavy Scale-up
-
-- Dispatch the `script-checker` before launching:
-  `subagent({agent:"script-checker", task:"<script path + stated intent/framing>"})`.
-- Do not launch until it has returned and come back clean.
-- If it's still running, wait for it (or say explicitly you're waiting)
-  -- don't launch anyway planning to fold in feedback once it lands.
-- Launching "in parallel while the `script-checker` runs in the
-  background" still counts as launching without it -- the expensive run
-  finishes and gets shown to the user before a material issue could
-  surface.
-- A `script-checker` pass only checks the script -- it never substitutes
-  for the lock-in checkpoint in
-  `/skill:finishing-exploratory-data-analysis` once a figure/question is
-  ready to show the user.
-- Two or more edits since the last `script-checker` dispatch count as one
-  nontrivial change on their own -- dispatch again at that point, don't
-  wait for it to feel big enough.
-
-### Dispatching the `job-runner`
-
-- Once clear to launch:
-  `subagent({agent:"job-runner", task:"<script path + output location + estimated runtime + estimated peak memory>"})`.
-  This frees the main session to keep iterating while it runs. Pass the
-  runtime/memory estimate from your smoke test (see "Judging Heavy vs.
-  Light Scale-up" above) rather than making it re-derive them blind.
-
-## Common Mistakes
-
-| Mistake | Fix |
-| --- | --- |
-| Running the full dataset (or an ad hoc exploratory probe) before a smoke test | Always sample/time on a subset first -- applies to one-off probes too, not just numbered scripts |
-| Silently skipping the smoke test on a "just read cache and plot" script | Only skip for zero-computation cached-read-and-plot, and state that justification explicitly |
-| Trusting a sanity check that only ran on an easy/symmetric case | Pick a case that could actually have failed, especially for matching/ordering/canonicalization logic |
-| Checking that a smoke test ran fast/clean without looking at what it produced | Glance at the actual output values -- a clean run on garbage isn't a pass |
-| Running a light-path script without rereading it first because it's "just quick" | Reread against the stated intent/framing before running -- speed doesn't waive the check, it just changes who does it |
-| Launching a heavy scale-up "while the `script-checker` runs in the background" instead of waiting for it | Confirm the `script-checker` came back clean before launching -- don't launch and plan to fold feedback in later |
-| Letting 2+ small edits pile up on a heavy-path script since the last `script-checker` dispatch because none felt big enough alone | Dispatch again once 2+ edits have landed |
-| Treating a mid-work `script-checker` pass as covering the finishing skill's lock-in checkpoint | Different gate, different artifact -- a pending or completed `script-checker` pass never substitutes for it |

package/skills/exploring-data/pre-code-checkpoints.md

@@ -1,63 +0,0 @@
-# Pre-Code Checkpoints
-
-What to do for `/skill:exploring-data` before you write any
-code for the next question.
-
-## Scope the analysis (once per analysis, before Peek at the data)
-
-- Before opening the data, check in one or two sentences what is broadly in
-  scope for this analysis and get the user's confirmation. This is a "what
-  are we even doing here", separate from and prior to the per-question framing
-  below.
-- Ask the user for a report name for this analysis -- it names both the
-  report file and its paired folder (see `directory-structure.md`).
-  Don't pick one yourself.
-- Keep it broad on purpose -- treat it as provisional, not a lock. Expect
-  it to narrow or shift as the data reveals what's actually there, well
-  before you reach conclusions -- confirm the new framing with the user
-  when it does, same as any other question (see below). `index.md` and
-  the report are written together during
-  `/skill:finishing-exploratory-data-analysis`, not during exploration.
-
-## Peek at the data (once per new dataset, before Propose/ask a question)
-
-- Load the dataset (lazily), check schema/dtypes.
-- Get null counts and basic summary stats (mean/median, min/max, std).
-- Get a feel for the actual data: `.head()`, a strided sample, or a random
-  sample (fixed seed).
-- Read a few raw rows by eye. They catch what schema/dtype checks and basic
-  stats above miss: a "numeric" column that's really a formatted string,
-  an ID convention, units, or what a free-text field actually holds.
-- Even raw rows and basic stats can miss duplicate rows.
-- Beyond that, think about what else is cheap to calculate and might
-  reveal something missed above -- e.g. sentinel/placeholder values (`-1`,
-  `0`, `"unknown"`), class imbalance, or a grain mismatch after a join.
-
-## Propose/ask a question (once per question, every time)
-
-- Confirm the framing for *this* question/figure with the user before
-  writing a script for it.
-- State the new framing in a sentence before scripting it, even if a broad
-  go-ahead was already given for the analysis as a whole.
-- This applies to every question, including one you decide to add on your
-  own after an earlier go-ahead. Approval for one question is not
-  approval for the next one the user hasn't seen proposed yet.
-- **A blanket "keep going" / "I trust your judgment" is not per-question
-  approval.** It authorizes you to keep working on framing, not to skip
-  asking about the next question's framing. Treat it the same as
-  silence: propose the next question's framing in one sentence, then
-  build it.
-- Do not build multiple questions in one pass and hand over a "finished
-  report" -- stop after each one and surface what it shows before
-  moving to the next.
-
-## Common Mistakes
-
-| Mistake | Fix |
-| --- | --- |
-| Opening the data before agreeing on a broad scope | State the analysis's scope/question area in a sentence and confirm before Peek at the data |
-| Picking the report/subfolder name yourself instead of asking | Ask before creating it -- one name, shared by the file and its folder |
-| Treating EDA as a pipeline and auto-advancing through questions without a framing check | Confirm framing per question, not once for the whole analysis |
-| Adding a follow-up figure/question under an earlier blanket go-ahead without confirming its framing | State the new framing in a sentence before scripting it |
-| Building the next two questions back-to-back and presenting a "complete report" because the user said "keep going" / "I trust your judgment" | That phrase covers continued work, not skipped per-question confirmation -- stop after each one |
-| Skipping the raw-row eyeball and stopping at summary stats | Read a few actual rows -- aggregates hide format/unit/encoding surprises |