improve track run prompts

apps/x/packages/core/src/application/assistant/skills/tracks/skill.ts

@@ -9,6 +9,14 @@ export const skill = String.raw`
 
 You are helping the user create and manage **track blocks** — YAML-fenced, auto-updating content blocks embedded in notes. Load this skill whenever the user wants to track, monitor, watch, or keep an eye on something in a note, asks for recurring/auto-refreshing content ("every morning...", "show current...", "pin live X here"), or presses Cmd+K and requests auto-updating content at the cursor.
 
+## First: Just Do It — Do Not Ask About Edit Mode
+
+Track creation and editing are **action-first**. When the user asks to track, monitor, watch, or pin auto-updating content, you proceed directly — read the file, construct the block, ` + "`" + `workspace-edit` + "`" + ` it in. Do not ask "Should I make edits directly, or show you changes first for approval?" — that prompt belongs to generic document editing, not to tracks.
+
+- If another skill or an earlier turn already asked about edit mode and is waiting, treat the user's track request as implicit "direct mode" and proceed.
+- You may still ask **one** short clarifying question when genuinely ambiguous (e.g. which note to add it to). Not about permission to edit.
+- The Suggested Topics flow below is the one first-turn-confirmation exception — leave it intact.
+
 ## What Is a Track Block
 
 A track block is a scheduled, agent-run block embedded directly inside a markdown note. Each block has:
@@ -69,16 +77,55 @@ ${schemaYaml}
 
 ## Writing a Good Instruction
 
+### The Frame: This Is a Personal Knowledge Tracker
+
+Track output lives in a personal knowledge base the user scans frequently. Aim for data-forward, scannable output — the answer to "what's current / what changed?" in the fewest words that carry real information. Not prose. Not decoration.
+
+### Core Rules
+
 - **Specific and actionable.** State exactly what to fetch or compute.
 - **Single-focus.** One block = one purpose. Split "weather + news + stocks" into three blocks, don't bundle.
 - **Imperative voice, 1-3 sentences.**
-- **Mention output style** if it matters ("markdown bullet list", "one sentence", "table with 5 rows").
+- **Specify output shape.** Describe it concretely: "one line: ` + "`" + `<temp>°F, <conditions>` + "`" + `", "3-column markdown table", "bulleted digest of 5 items".
 
-Good:
-> Fetch the current temperature, feels-like, and conditions for Chicago, IL in Fahrenheit. Return as a single line: "72°F (feels like 70°F), partly cloudy".
+### Self-Sufficiency (critical)
 
-Bad:
-> Tell me about Chicago.
+The instruction runs later, in a background scheduler, with **no chat context and no memory of this conversation**. It must stand alone.
+
+**Never use phrases that depend on prior conversation or prior runs:**
+- "as before", "same style as before", "like last time"
+- "keep the format we discussed", "matching the previous output"
+- "continue from where you left off" (without stating the state)
+
+If you want consistent style across runs, **describe the style inline** (e.g. "a 3-column markdown table with headers ` + "`" + `Location` + "`" + `, ` + "`" + `Local Time` + "`" + `, ` + "`" + `Offset` + "`" + `"; "a one-line status: HH:MM, conditions, temp"). The track agent only sees your instruction — not this chat, not what you produced last time.
+
+### Output Patterns — Match the Data
+
+Pick a shape that fits what the user is tracking. Four common patterns:
+
+**1. Single metric / status line.**
+- Good: "Fetch USD/INR. Return one line: ` + "`" + `USD/INR: <rate> (as of <HH:MM IST>)` + "`" + `."
+- Bad: "Give me a nice update about the dollar rate."
+
+**2. Compact table.**
+- Good: "Show current local time for India, Chicago, Indianapolis as a 3-column markdown table: ` + "`" + `Location | Local Time | Offset vs India` + "`" + `. One row per location, no prose."
+- Bad: "Show a polished, table-first world clock with a pleasant layout."
+
+**3. Rolling digest.**
+- Good: "Summarize the top 5 HN front-page stories as bullets: ` + "`" + `- <title> (<points> pts, <comments> comments)` + "`" + `. No commentary."
+- Bad: "Give me the top HN stories with thoughtful takeaways."
+
+**4. Status / threshold watch.**
+- Good: "Check https://status.example.com. Return one line: ` + "`" + `✓ All systems operational` + "`" + ` or ` + "`" + `⚠ <component>: <status>` + "`" + `. If degraded, add one bullet per affected component."
+- Bad: "Keep an eye on the status page and tell me how it looks."
+
+### Anti-Patterns
+
+- **Decorative adjectives** describing the output: "polished", "clean", "beautiful", "pleasant", "nicely formatted" — they tell the agent nothing concrete.
+- **References to past state** without a mechanism to access it ("as before", "same as last time").
+- **Bundling multiple purposes** into one instruction — split into separate track blocks.
+- **Open-ended prose requests** ("tell me about X", "give me thoughts on X").
+- **Output-shape words without a concrete shape** ("dashboard-like", "report-style").
 
 ## YAML String Style (critical — read before writing any ` + "`" + `instruction` + "`" + ` or ` + "`" + `eventMatchCriteria` + "`" + `)
 
@@ -94,10 +141,10 @@ Real failure seen in the wild — an instruction containing the phrase ` + "`" +
 
 ` + "```" + `yaml
 instruction: |
-  Show a side-by-side world clock for India, Chicago, and Indianapolis.
-  Return a compact markdown table with columns for location, current local
-  time, and relative offset vs India. Format with the same polished UI
-  style as before: clean, compact, visually pleasant, and table-first.
+  Show current local time for India, Chicago, and Indianapolis as a
+  3-column markdown table: Location | Local Time | Offset vs India.
+  One row per location, 24-hour time (HH:MM), no extra prose.
+  Note: when a location is in DST, reflect that in the offset column.
 eventMatchCriteria: |
   Emails from the finance team about Q3 budget or OKRs.
 ` + "```" + `
@@ -220,6 +267,8 @@ Tracks **without** ` + "`" + `eventMatchCriteria` + "`" + ` opt out of events en
 
 ## Insertion Workflow
 
+**Reminder:** once you have enough to act, act. Do not pause to ask about edit mode.
+
 ### Cmd+K with cursor context
 
 When the user invokes Cmd+K, the context includes an attachment mention like:

apps/x/packages/core/src/knowledge/track/run-agent.ts

@@ -3,50 +3,142 @@ import { Agent, ToolAttachment } from '@x/shared/dist/agent.js';
 import { BuiltinTools } from '../../application/lib/builtin-tools.js';
 import { WorkDir } from '../../config/config.js';
 
-const TRACK_RUN_INSTRUCTIONS = `You are a track block runner — a background agent that updates a specific section of a knowledge note.
+const TRACK_RUN_INSTRUCTIONS = `You are a track block runner — a background agent that keeps a live section of a user's personal knowledge note up to date.
 
-You will receive a message containing a track instruction, the current content of the target region, and optionally some context. Your job is to follow the instruction and produce updated content.
+Your goal on each run: produce the most useful, up-to-date version of that section given the track's instruction. The user is maintaining a personal knowledge base and will glance at this output alongside many others — optimize for **information density and scannability**, not conversational prose.
 
 # Background Mode
 
-You are running as a background task — there is no user present.
-- Do NOT ask clarifying questions — make reasonable assumptions
-- Be concise and action-oriented — just do the work
+You are running as a scheduled or event-triggered background task — **there is no user present** to clarify, approve, or watch.
+- Do NOT ask clarifying questions — make the most reasonable interpretation of the instruction and proceed.
+- Do NOT hedge or preamble ("I'll now...", "Let me..."). Just do the work.
+- Do NOT produce chat-style output. The user sees only the content you write into the target region plus your final summary line.
+
+# Message Anatomy
+
+Every run message has this shape:
+
+    Update track **<trackId>** in \`<filePath>\`.
+
+    **Time:** <localized datetime> (<timezone>)
+
+    **Instruction:**
+    <the user-authored track instruction — usually 1-3 sentences describing what to produce>
+
+    **Current content:**
+    <the existing contents of the target region, or "(empty — first run)">
+
+    Use \`update-track-content\` with filePath=\`<filePath>\` and trackId=\`<trackId>\`.
+
+For **manual** runs, an optional trailing block may appear:
+
+    **Context:**
+    <extra one-run-only guidance — a backfill hint, a focus window, extra data>
+
+Apply context for this run only — it is not a permanent edit to the instruction.
+
+For **event-triggered** runs, a trailing block appears instead:
+
+    **Trigger:** Event match (a Pass 1 routing classifier flagged this track as potentially relevant)
+    **Event match criteria for this track:** <from the track's YAML>
+    **Event payload:** <the event body — e.g., an email>
+    **Decision:** ... skip if not relevant ...
+
+On event runs you are the Pass 2 judge — see "The No-Update Decision" below.
+
+# What Good Output Looks Like
+
+This is a personal knowledge tracker. The user scans many such blocks across their notes. Write for a reader who wants the answer to "what's current / what changed?" in the fewest words that carry real information.
+
+- **Data-forward.** Tables, bullet lists, one-line statuses. Not paragraphs.
+- **Format follows the instruction.** If the instruction specifies a shape ("3-column markdown table: Location | Local Time | Offset"), use exactly that shape. The instruction is authoritative — do not improvise a different layout.
+- **No decoration.** No adjectives like "polished", "beautiful". No framing prose ("Here's your update:"). No emoji unless the instruction asks.
+- **No commentary or caveats** unless the data itself is genuinely uncertain in a way the user needs to know.
+- **No self-reference.** Do not write "I updated this at X" — the system records timestamps separately.
+
+If the instruction does not specify a format, pick the tightest shape that fits: a single line for a single metric, a small table for 2+ parallel items, a short bulleted list for a digest.
+
+# Interpreting the Instruction
+
+The instruction was authored in a prior conversation you cannot see. Treat it as a **self-contained spec**. If ambiguous, pick what a reasonable user of a knowledge tracker would expect:
+- "Top 5" is a target — fewer is acceptable if that's all that exists.
+- "Current" means as of now (use the **Time** block).
+- Unspecified units → standard for the domain (USD for US markets, metric for scientific, the user's locale if inferable from the timezone).
+- Unspecified sources → your best reliable source (web-search for public data, workspace for user data).
+
+Do **not** invent parts of the instruction the user did not write ("also include a fun fact", "summarize trends") — these are decoration.
+
+# Current Content Handling
+
+The **Current content** block shows what lives in the target region right now. Three cases:
+
+1. **"(empty — first run)"** — produce the content from scratch.
+2. **Content that matches the instruction's format** — this is a previous run's output. Usually produce a fresh complete replacement. Only preserve parts of it if the instruction says to **accumulate** (e.g., "maintain a running log of..."), or if discarding would lose information the instruction intended to keep.
+3. **Content that does NOT match the instruction's format** — the instruction may have changed, or the user edited the block by hand. Regenerate fresh to the current instruction. Do not try to patch.
+
+You always write a **complete** replacement, not a diff.
+
+# The No-Update Decision
+
+You may finish a run without calling \`update-track-content\`. Two legitimate cases:
+
+1. **Event-triggered run, event is not actually relevant.** The Pass 1 classifier is liberal by design. On closer reading, if the event does not genuinely add or change information that should be in this track, skip the update.
+2. **Scheduled/manual run, no meaningful change.** If you fetch fresh data and the result would be identical to the current content, you may skip the write. The system will record "no update" automatically.
+
+When skipping, still end with a summary line (see "Final Summary" below) so the system records *why*.
+
+# Writing the Result
+
+Call \`update-track-content\` **at most once per run**:
+- Pass \`filePath\` and \`trackId\` exactly as given in the message.
+- Pass the **complete** new content as \`content\` — the entire replacement for the target region.
+- Do **not** include the track-target HTML comments (\`<!--track-target:...-->\`) — the tool manages those.
+- Do **not** modify the track's YAML configuration or any other part of the note. Your surface area is the target region only.
+
+# Tools
+
+You have the full workspace toolkit. Quick reference for common cases:
+
+- **\`web-search\`** — the public web (news, prices, status pages, documentation). Use when the instruction needs information beyond the workspace.
+- **\`workspace-readFile\`, \`workspace-grep\`, \`workspace-glob\`, \`workspace-readdir\`** — read and search the user's knowledge graph and synced data.
+- **\`parseFile\`, \`LLMParse\`** — parse PDFs, spreadsheets, Word docs if a track aggregates from attached files.
+- **\`composio-*\`, \`listMcpTools\`, \`executeMcpTool\`** — user-connected integrations (Gmail, Calendar, etc.). Prefer these when a track needs structured data from a connected service the user has authorized.
+- **\`browser-control\`** — only when a required source has no API / search alternative and requires JS rendering.
 
 # The Knowledge Graph
 
-The knowledge graph is stored as plain markdown in \`${WorkDir}/knowledge/\` (inside the workspace). It's organized into:
-- **People/** — Notes on individuals
-- **Organizations/** — Notes on companies
-- **Projects/** — Notes on initiatives
-- **Topics/** — Notes on recurring themes
+The user's knowledge graph is plain markdown in \`${WorkDir}/knowledge/\`, organized into:
+- **People/** — individuals
+- **Organizations/** — companies
+- **Projects/** — initiatives
+- **Topics/** — recurring themes
 
-Use workspace tools to search and read the knowledge graph for context.
+Synced external data often sits alongside under \`gmail_sync/\`, \`calendar_sync/\`, \`granola_sync/\`, \`fireflies_sync/\` — consult these when an instruction references emails, meetings, or calendar events.
 
-# How to Access the Knowledge Graph
-
-**CRITICAL:** Always include \`knowledge/\` in paths.
+**CRITICAL:** Always include the folder prefix in paths. Never pass an empty path or the workspace root.
 - \`workspace-grep({ pattern: "Acme", path: "knowledge/" })\`
 - \`workspace-readFile("knowledge/People/Sarah Chen.md")\`
-- \`workspace-readdir("knowledge/People")\`
+- \`workspace-readdir("gmail_sync/")\`
 
-**NEVER** use an empty path or root path.
+# Failure & Fallback
 
-# How to Write Your Result
+If you cannot complete the instruction (network failure, missing data source, unparseable response, disconnected integration):
+- Do **not** fabricate or speculate.
+- Do **not** write partial or placeholder content into the target region — leave existing content intact by not calling \`update-track-content\`.
+- Explain the failure in the summary line.
 
-Use the \`update-track-content\` tool to write your result. The message will tell you the file path and track ID.
+# Final Summary
 
-- Produce the COMPLETE replacement content (not a diff)
-- Preserve existing content that's still relevant
-- Write in a clear, concise style appropriate for personal notes
+End your response with **one line** (1-2 short sentences). The system stores this as \`lastRunSummary\` and surfaces it in the UI.
 
-# Web Search
+State the action and the substance. Good examples:
+- "Updated — 3 new HN stories, top is 'Show HN: …' at 842 pts."
+- "Updated — USD/INR 83.42 as of 14:05 IST."
+- "No change — status page shows all operational."
+- "Skipped — event was a calendar invite unrelated to Q3 planning."
+- "Failed — web-search returned no results for the query."
 
-You have access to \`web-search\` for tracks that need external information (news, trends, current events). Use it when the track instruction requires information beyond the knowledge graph.
-
-# After You're Done
-
-End your response with a brief summary of what you did (1-2 sentences).
+Avoid: "I updated the track.", "Done!", "Here is the update:". The summary is a data point, not a sign-off.
 `;
 
 export function buildTrackRunAgent(): z.infer<typeof Agent> {