@evref-bl/pharo-mcp 1.5.1 → 2.0.0

package/templates/pharo-skills/pharo-code-profiling/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: pharo-code-profiling
+description: Profile running Pharo code to find where its time goes, and read the sampling report it answers. Use for slow code, before-and-after comparisons, and whenever a single `#timeToRun` number would not say why.
+---
+
+# Pharo Code Profiling
+
+## Model
+
+`#timeToRun` answers how long, never why, and one run is noisy: JIT warm-up, GC
+and scheduling all move it. A sampling profiler interrupts execution every
+millisecond and records the stack, so what it answers is a distribution. Trust
+the ranking and the proportions, not the individual numbers.
+
+Two samplers answer text in a headless image, and they differ in what they can
+see, not only in how much:
+
+- `MessageTally` is a Smalltalk process that wakes on a delay and records what
+  it preempted. Spied on a block, its tree is rooted at that block, so the
+  report holds the workload and nothing else. Start here.
+- `AndreasSystemProfiler` is driven by the VM. It samples every process,
+  including those running above the priority at which a Smalltalk sampler would
+  itself be starved, and it records which primitive the VM is executing, which
+  `MessageTally` can only lump together as `primitives`. Its tree is rooted at
+  the image.
+
+## Workflow
+
+1. Build a workload that runs for one to five seconds: long enough for a
+   thousand samples, short enough to answer inside the client's timeout, since
+   `image_evaluate` has none of its own. Fork a longer one instead, as below.
+   Run the workload once before measuring so the JIT is warm.
+2. Profile it and keep the tally, which is what renders the report:
+
+```smalltalk
+| workload tally |
+workload := [ 200 timesRepeat: [ "..." ] ].
+workload value.
+tally := MessageTally
+	         spyOn: workload
+	         reportOtherProcesses: false
+	         cutoff: 2
+	         openResultWindow: false
+	         closeAfter: false.
+String streamContents: [ :stream | tally report: stream cutoff: 2 ]
+```
+
+3. Read the report.
+4. Change one thing, re-profile the same workload at the same cutoff, and
+   compare shapes. Verify behavior with focused tests.
+
+## Choosing The Cutoff
+
+The cutoff is the percentage of all samples a node must hold to be printed, in
+the tree and in the leaves alike. Use 2 and read the report once. Over a
+2400-sample run of the same workload it printed 79 lines where 5% printed 52
+and 1% printed 84, so it is close enough to the whole tree that a second look
+rarely pays, and still under a thousand tokens.
+
+Raise it when the report is larger than the question. Rendering again costs no
+new run, because the tally is still in hand:
+
+```smalltalk
+String streamContents: [ :stream | tally report: stream cutoff: 10 ]
+```
+
+Do not lower it to find a workload whose methods are missing from the report.
+A node printed at cutoff *c* over *n* samples holds `n * c / 100` of them, and
+under about 25 samples that is noise rather than a measurement, so 2% means
+nothing below some 1250 samples. Lengthen the run instead.
+
+The `cutoff:` passed to the spy call only feeds the window it is not opening.
+The one that decides the report is on `report:cutoff:`.
+
+## Profiling A Workload Longer Than The Call
+
+Fork the run, write the report to a file, and come back for it. The fork
+returns the call immediately and leaves the image answering, so the profile can
+take as long as the workload needs. Keep the report out of a global: a file
+survives, is readable from outside the image, and needs no cleanup inside it.
+
+```smalltalk
+| path |
+path := FileLocator imageDirectory / 'profile-report.txt'.
+path ensureDelete.
+[
+| tally |
+tally := MessageTally
+	         spyOn: [ "..." ]
+	         reportOtherProcesses: false
+	         cutoff: 2
+	         openResultWindow: false
+	         closeAfter: false.
+path writeStreamDo: [ :out |
+	out << ((String streamContents: [ :stream | tally report: stream cutoff: 2 ])
+			 copyReplaceAll: String cr with: String lf) ] ]
+	forkAt: Processor userBackgroundPriority
+	named: 'pharo-profile'.
+path fullName
+```
+
+The file is written only once the run ends, so `path exists` answers whether it
+is done. To tell a slow run from a dead one, look for the process by the name
+it was forked under:
+
+```smalltalk
+Process allInstances anySatisfy: [ :each |
+	each name = 'pharo-profile' and: [ each isTerminated not ] ]
+```
+
+Pharo writes CR line endings, so convert to LF as above, or the report arrives
+as a single line everywhere outside the image.
+
+The tally dies with the fork, so this report is written once and cannot be
+rendered again at another cutoff. The file costs nothing to keep, and it can be
+read in parts rather than whole.
+
+Forking at `userBackgroundPriority` keeps the image answering calls while the
+profile runs. The samples it loses to those calls are charged to another
+process and dropped from the report, which lowers every percentage by the same
+factor: read the proportions between nodes, not their absolute values.
+
+## Reading The Report
+
+```
+ - 933 tallies, 933 msec.
+
+**Tree**
+Process: (60) ...
+63.9% {596ms} Array(SequenceableCollection)>>shuffle
+  63.9% {596ms} Array(SequenceableCollection)>>shuffleBy:
+    62.7% {585ms} Random>>nextInteger:
+      34.2% {319ms} Random>>privateNextValue
+        |34.2% {319ms} Random class>>primitiveRandomNumber:
+        |  17.8% {166ms} LargePositiveInteger(Integer)>>>>
+        |    |17.6% {164ms} primitives
+```
+
+- `933 tallies` is the sample count. Below a few hundred, small differences
+  mean nothing.
+- A percentage is of the whole spied block and includes everything below it.
+  Own time is a node's percentage minus its children's.
+- `Receiver(DefiningClass)>>selector` names where an inherited method is
+  defined: `Array(SequenceableCollection)>>shuffle` runs on an `Array` and is
+  defined on `SequenceableCollection`.
+- `primitives` is not a method. It is the part of the parent's time no child
+  accounts for: its own work, primitives and inlined code included.
+- The `|` bars are tree drawing. A node gets one when a sibling follows it at
+  that level, and carries it down its subtree. They mean nothing else.
+- `**Leaves**` ranks by own time and is usually what to act on. The tree says
+  who is responsible, the leaves say what is expensive.
+- `**Memory**` is the allocation delta over the run and `**GCs**` the
+  collections and the share of the run spent in them. Heavy incremental GC with
+  a large young delta is an allocation problem, and optimizing the leaves will
+  not touch it.
+
+## Whole-Image Profiling
+
+Use it when the work happens in another process, or when the question is about
+the image rather than one block.
+
+```smalltalk
+| profiler |
+profiler := AndreasSystemProfiler new.
+profiler spyOn: [ "..." ].
+String streamContents: [ :stream | profiler report: stream cutoff: 2 ]
+```
+
+Never send `spyOn:` to the class: it ends in `doReport`, which opens a window.
+The instance-side `spyOn:` is the headless path.
+
+Its tree is rooted at the image, so a report taken through MCP opens with the
+frames of the server handling the call. Find the workload's entry method and
+read the percentages from that node down.
+
+## Measuring Instead Of Profiling
+
+A profile ranks, it does not measure. For a before-and-after number:
+
+```smalltalk
+"one run, as a Duration"
+[ "..." ] timeToRun
+
+"iterations per second over five seconds, which absorbs the noise"
+[ "..." ] bench
+```
+
+Time the same thing at least three times and report the minimum rather than the
+mean: the minimum is the run least disturbed by GC and scheduling.
+
+## Stop Before
+
+- Profiling forks a process and leaves state behind. Run it inside an approved
+  image boundary and never save the image.
+- Only one `MessageTally` can run at a time; a second answers "it seems a tally
+  is already running". Let a forked profile finish before starting another.
+- Do not trust a report whose tree does not contain the workload's own methods:
+  it was too short, or it waited instead of computing.
+- Do not compare numbers across different workloads or cutoffs. Compare shapes.
+
+## Report
+
+Report the workload and how long it ran, the sampler and cutoff, the top tree
+nodes and leaves with their percentages, the change made, the before-and-after
+comparison, and the tests that showed behavior unchanged.

package/templates/pharo-skills/pharo-code-profiling/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Pharo Code Profiling"
+  short_description: "Find Pharo performance hotspots"
+  default_prompt: "Use $pharo-code-profiling to profile this Pharo code and find where the time is spent before optimizing."

package/templates/pharo-skills/pharo-image-git-handoff/SKILL.md

@@ -21,6 +21,9 @@ not prove files changed on disk.
    and documentation path.
 5. Commit only the intended diff. Push only when explicitly requested or
    clearly approved.
+6. When the checkout moves under the image — switching branch, pulling, or any
+   Git command that rewrites the source files — reload the image from those
+   files afterwards, or it keeps running the code the old checkout held.
 
 ## Stop Before Mutation
 

package/templates/pharo.AGENTS.md

@@ -11,7 +11,7 @@ guessing from source.
 - Prefer the least-mutating dedicated tool. Use `image_evaluate` only when no
   dedicated tool fits.
 - Treat image, Tonel, Iceberg, and Git state as separate.
-- Successful mutating tools save the image; use a safe image boundary.
+- Tools change the running image but never save it; use a safe image boundary.
 
 ## Context Loading
 
@@ -25,6 +25,8 @@ guessing from source.
   `skills/pharo-image-git-handoff/SKILL.md`.
 - Before reproducing smalltalkCI or GitHub failures: use
   `skills/pharo-ci-repro/SKILL.md`.
+- Before profiling or optimizing Pharo code: use
+  `skills/pharo-code-profiling/SKILL.md`.
 - Before recovering a stopped standalone image: use
   `skills/pharo-mcp-recovery/SKILL.md`.
 - Before debugger sessions or repairs: read the local

package/templates/pharo-references/debugger-driven-development.md

@@ -1,101 +0,0 @@
-# Debugger-Driven Development
-
-Applies when using MCP-Pharo to repair code from a live debugger state.
-
-Debugger-driven development keeps execution paused at the failure, edits the
-relevant method, and continues from the debugger instead of restarting the
-whole scenario.
-
-## Goal
-
-Repair code from the paused execution context while preserving the debugger as
-the source of truth for receiver, selector, class side, selected frame, and
-repair action.
-
-## Main Flow
-
-1. Get a state with `debug_state_get`, `debug_capture`, or
-   `debug_candidate_attach`.
-2. Check `repairActions` before inventing an edit target.
-3. Call `debug_method_update` with the action's `sessionId`, `stateId`, and `frameRef`.
-4. Review returned `critiques`.
-5. If the edit is blocked by critiques and the critiques are acceptable, retry
-   with `ignoreCritiques=true`.
-6. Continue with the returned state when execution pauses again.
-
-## Must Do
-
-- Use the repair action's frame reference instead of selecting a target class or
-  method by hand.
-- Review critiques before allowing the repaired computation to proceed.
-- Treat returned states and references as fresh; discard older state-scoped
-  references after each edit or control action.
-- Stop after the bounded action the user requested and report the resulting
-  state.
-
-## Do Not
-
-- Do not guess the receiver class, target behavior, selector, or class side for
-  missing-method repair.
-- Do not use general `image_evaluate` code to mutate contexts or drive
-  debugger UI.
-- Do not continue issuing frame commands when the repair outcome is running,
-  timed out, completed, or blocked by critiques.
-
-## Missing Methods
-
-For `MessageNotUnderstood`, `debug_method_update` creates the method implied by the
-paused message send. The target behavior, selector, class side, and frame are
-derived from the debug state; do not guess them in the request.
-
-You may omit `methodSource` when the default generated source is acceptable.
-Provide `methodSource` when the method should do real work. The compiled method
-is formatted before it is returned or used to continue execution.
-
-## Stub Methods
-
-For `subclassResponsibility`, `shouldBeImplemented`, and `notYetImplemented`,
-`debug_method_update` recompiles the method associated with the selected repair frame.
-Use the repair action's frame reference instead of selecting a target class by
-hand.
-
-## Critiques
-
-`debug_method_update` uses the same critique gate expected from method-editing tools. It
-stops before proceeding when critiques are reported unless
-`ignoreCritiques=true`.
-
-Use `ignoreCritiques=true` only after reading the critiques and deciding that
-continuing the suspended computation is still the right next step.
-
-## Proceeding
-
-After a successful accepted edit, `debug_method_update` attempts to proceed the repaired
-computation. Outcomes include completed, paused, running, timed out, or blocked
-by critiques.
-
-When the outcome is paused, use the returned state and repair actions. When it
-is completed, inspect the result class and print string. When it is running or
-timed out, avoid issuing stale frame commands.
-
-## Human-Owned Debuggers
-
-For debugger windows opened by a human, discover candidates with
-`debug_candidate_search`, attach with `debug_candidate_attach`, and let the
-debugger controller perform control actions. The visible debugger remains the
-UI owner. Do not use general `image_evaluate` code to drive Morphic debugger
-widgets or mutate contexts directly.
-
-When the user asks you to perform a bounded action and give control back, run
-only the requested debugger calls, then stop and report the resulting state.
-
-## Reporting
-
-When finishing a debugger-driven repair, report:
-
-- repair action used;
-- method created or recompiled, when any;
-- critiques returned and whether they were accepted;
-- proceed outcome;
-- final state or why no fresh state is available;
-- cleanup still needed.