tarsk 0.6.87 → 0.6.89

package/dist/bundled-skills/tarsk-improve/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: tarsk-improve
+description: >-
+  End-of-session review that improves Tarsk built-in Tool skills from this chat
+  or prior runs in tarsk.db, then applies the small description/schema/execute
+  fixes that clear the worth bar. In an ordinary project it exports bundled
+  tarsk-* Skills into .agents/skills and edits those copies. In the Tarsk
+  checkout the built-ins are the repo's own files: it copies nothing and edits
+  cli/bundled-skills/tarsk-* directly. At the end it prunes project copies that
+  still match bundled. Use when the user says improve tools, /tarsk-improve,
+  learn from this session, or reduce tool failures/turns/tokens after a chat.
+version: 2.2.1
+disable-model-invocation: true
+when_to_use: >-
+  At the end of a chat (or when reviewing recent sessions) to improve shipped
+  Tool skills from real failures, retries, or turn/token waste — not mid-task
+  opportunistic edits.
+---
+
+# Improve Tarsk Tool skills (`tarsk-improve`)
+
+Turn this conversation (or recent sessions) into **small fixes to built-in Tool
+skills**. Edit whichever copy the Tool loader resolves for this repo:
+
+- **Ordinary project:** the project export under `.agents/skills/tarsk-*`
+  (step 0 copies it in).
+- **The Tarsk checkout itself:** `cli/bundled-skills/tarsk-*` directly. Here the
+  built-ins are the repo's own files, so step 0 copies nothing and
+  `.agents/skills/tarsk-*` must stay absent.
+
+This skill ships with Tarsk and works in any repo. It is **user-invoked**
+(`disable-model-invocation`) — run at the end of a session, not mid-task.
+
+## Goal
+
+Cut repeated tool failures, serial multi-hop that should be one `run_js`, noisy
+defaults, and misleading schemas/descriptions — by patching the Tool skill that
+publishes that tool.
+
+Every change must clear the **worth bar** before it is made:
+
+- One of: cuts wasted turns significantly, cuts tokens significantly, fixes a
+  bug the tool itself causes — or a new Tool skill would be a significant gain.
+- Likely to recur: the waste affects or plausibly will affect multiple
+  sessions, not one call pattern from a single chat.
+- Tool copy stays token-efficient: edited `description` / parameter text is
+  the same length or shorter.
+- Nothing clearing the bar is a valid outcome too: end the run with that
+  result and nothing patched.
+
+## Scope
+
+**In scope**
+
+- Bundled Tool skills: `.agents/skills/tarsk-*/` in a user project (must exist
+  after step 0), or `cli/bundled-skills/tarsk-*/` in the Tarsk checkout
+- `description`, `parameters`, and `execute` in `scripts/{tool}.js`
+- Packaging rules in the `tarsk-agent` skill
+
+**Out of scope**
+
+- User project skills/rules/`AGENTS.md` that are not `tarsk-*` Tool skills
+- Mid-task workarounds (system prompt already covers those)
+- Large Tarsk product refactors unrelated to a Tool skill surface
+
+## Required workflow
+
+Copy and track:
+
+```
+Improve progress:
+- [ ] 0. Export tarsk-* into .agents/skills (Tarsk checkout: copies nothing)
+- [ ] 1. Summarize this session / recent runs
+- [ ] 2. Diagnose Tool skill gaps
+- [ ] 3. Assess by the worth bar (no ask; no-change is a valid result)
+- [ ] 4. Patch the one resolvable copy (read tarsk-agent first)
+- [ ] 5. Report what changed and the expected improvement
+- [ ] 6. Prune project copies that still match bundled
+```
+
+### 0. Export before any edit (user projects)
+
+From the project / thread root:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/ensure-exported.ts
+```
+
+If that path is missing (skill not yet exported), run from the bundled copy and
+point at the project:
+
+```bash
+bun <path-to-bundled-skills>/tarsk-improve/scripts/ensure-exported.ts --project-skills .agents/skills
+```
+
+Or set `TARSK_BUNDLED_SKILLS` to the bundled-skills directory.
+
+**In the Tarsk checkout the script copies nothing** — it prints:
+
+```
+Tarsk checkout: the built-ins are this repo's own files, so nothing was copied.
+Edit cli/bundled-skills/tarsk-* directly (/…/cli/bundled-skills).
+```
+
+Then edit `cli/bundled-skills/tarsk-*/` in place. Never create
+`.agents/skills/tarsk-*` copies in this repo, and read "Editable Tool skills
+(none)" as the expected result, not as a failure.
+
+**Hard rule (user projects):** Only edit paths listed under "Editable Tool
+skills" in the script output (under `.agents/skills/…`). If a Tool skill is
+missing there, re-run the export command above. The host never creates project
+copies on chat load; it only prunes copies that match bundled, so export before
+editing.
+
+### 1. Summarize
+
+Prefer the **current conversation** when the user is wrapping up this chat:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/summarize-session.ts --conversation <id>
+```
+
+Otherwise recent waste:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/summarize-session.ts --since 24h
+```
+
+Do not dump raw `entries` JSON. Use `history` only for a specific failure quote.
+
+### 2. Diagnose
+
+Map waste to a **Tool skill** (package that publishes the tool), not only a tool
+name:
+
+| Signal                        | Likely fix                                          |
+| ----------------------------- | --------------------------------------------------- |
+| Same tool fails repeatedly    | Clearer errors, validation, safer defaults          |
+| grep→read loops / serial hops | Description bias to `run_js`; tighten tool guidance |
+| Huge results / token spikes   | Default `select`, truncation, preview copy          |
+| Wrong tool chosen often       | Description / when_to_use / schema shape            |
+| Retries with identical args   | Idempotent messaging or “already applied” guidance  |
+
+Read [references/signals.md](references/signals.md) when patterns are unclear.
+
+### 3. Assess by the worth bar — then implement, no gate
+
+Keep the plan short, state one grouped reason the changes clear the bar, and go
+straight into step 4 in the same turn. Do not ask which items to implement; the
+bar decides. List below-bar candidates as skipped, one line each. If nothing
+clears the bar, "no changes needed" is the correct result: say it in one line
+and skip patching.
+
+```markdown
+## Improve plan
+
+**Runs:** <this conversation / since …>
+**Export:** <copied N; editable Tool skills — or Tarsk checkout: edit bundled>
+
+### Findings
+
+1. …
+2. …
+
+### Changes to make (ROI order)
+
+1. `tarsk-<skill>` / `scripts/<tool>.js` — …
+2. …
+
+### Why these clear the bar (one group)
+
+<Short plain wording: what the runs waste in turns/tokens, how often, and why
+it will keep recurring across sessions — one paragraph for the whole batch, not
+one reason per item.>
+
+### Skipped (below the bar)
+
+1. <finding> — <one line: single-session only / cost already small / …>
+```
+
+### 4. Implement
+
+1. Read the `tarsk-agent` skill (packaging + `context.*` contract).
+2. Edit the resolved copy only: `.agents/skills/tarsk-<name>/` (user project) or
+   `cli/bundled-skills/tarsk-<name>/` (Tarsk checkout).
+3. Prefer the smallest change: `description` / `parameters` / `execute`. Keep
+   copy the same length or shorter — fold new guidance into existing lines
+   instead of adding sentences.
+4. Bump the Skill `version` patch (or minor) in that package's `SKILL.md` when
+   you intentionally change behavior so future major exports do not silently
+   clobber without a decision.
+5. If `edit`/`write` returns `[tool-skill-load]` with a revert, the bad script
+   was restored automatically — fix the reported error and retry; do not leave
+   a broken Tool skill on disk.
+6. In a user project do **not** hand-edit `cli/bundled-skills/` or any other
+   built-in tree; the project export is the only edit surface there.
+
+### 5. Report
+
+List files changed, which Tool each affects, and one expected-improvement line
+for the batch in plain wording a curious non-developer can follow (fewer
+retries, smaller output, no more needless blocks). Point back to the plan's
+group reason for why, instead of repeating it. When nothing was patched, one
+line: what was reviewed and why no change cleared the bar. Then how to verify:
+re-run the failing call pattern in a new turn; Tool skill reload picks up script
+mtime.
+
+In the Tarsk checkout there is no upstream step: the files you edited under
+`cli/bundled-skills/tarsk-*` are the built-ins that ship.
+
+### 6. Prune unchanged copies (required in user projects)
+
+Delete project copies that still match bundled so the repo only keeps Tool
+skills that actually changed:
+
+```bash
+bun .agents/skills/tarsk-improve/scripts/ensure-exported.ts --prune
+```
+
+`removed` lists the copies that matched bundled; `kept` lists the ones you
+changed. The host also prunes on chat load, so untouched copies never persist.
+In the Tarsk checkout this only cleans up legacy copies; `removed: (none)` with
+`kept: 0` is the expected result.
+
+## Script index
+
+| Script                      | Role                                                                                         |
+| --------------------------- | -------------------------------------------------------------------------------------------- |
+| `ensure-exported.ts`        | Export `tarsk-*` for editing (skips the Tarsk checkout); `--prune` deletes copies that match |
+| `export-tool-skills-lib.ts` | Shared export/prune rules (also used by the host)                                            |
+| `summarize-session.ts`      | Waste-ranked run summary from `tarsk.db`                                                     |
+| `durable-runs.ts`           | Shared DB reader (imported by summarize-session)                                             |

package/dist/bundled-skills/tarsk-improve/references/signals.md

@@ -0,0 +1,16 @@
+# Signals → Tool skill fixes
+
+Use the summarize-session output. Prefer product-facing Tool skill edits over
+telling the model to “try harder.”
+
+| Pattern in runs                                | Prefer editing                                           |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| Same `tool` fails with the same args           | Error text / validation in that tool’s `execute`         |
+| Many turns of grep → read → grep               | `run_js` description + tool descriptions that bias chain |
+| Large `largest tool results` on read/bash/grep | Defaults for `select` / truncation / preview copy        |
+| Tool chosen when another was right             | `description` disambiguation                             |
+| `retried a failed call unchanged`              | Clearer “already done / change approach” messaging       |
+| Browser / MCP flailing                         | Deferred tool descriptions; deferral list clarity        |
+
+Always resolve the Tool name to its Skill package under
+`.agents/skills/tarsk-*/SKILL.md` (`tools:` list) before editing.