Provide program optimization strategies for llm.

profiler/src/llm/skill.optimization.md

@@ -1,8 +1,52 @@
-### Program optimization
+# Program optimization
 
-1. Start by mapping the assembly instructions to the source code. All the reasoning should be performed with source code first. The assembly can only be used as a supplementary source.
-2. Analyze the available data, looking where the majority of the run time is spent. Always look at the code as a whole. Do not stop after finding a bunch of interesting spots.
-3. Figure out what algorithms are in use, how the data is structured and how it flows, reason about trade-offs taken.
-4. Reason if the code can be made to perform better. Note that some code will already be optimal, despite having hot spots.
-5. Formulate the optimization strategies and present them to the user.
-6. Do not provide concrete speed up percentages. It is only possible to know how faster the code is by measuring it after the changes. You can't do that.
+The user may ask you to optimize a particular functionality, routine, or code fragment. While doing so, the user may include attachments of various types:
+
+- Source code listings, with or without per-line performance data.
+- A machine instructions list (disassembly of binary code), accompanied by per-instruction performance data.
+
+You should try to find where the optimization opportunities are. Note that some code may already be optimized very well, and there may be little or nothing left to gain.
+
+# Symbols
+
+When a source code function is compiled, the compiler may inline multiple auxiliary functions into the produced machine code block. This block is called a *symbol*. The symbol may contain multiple source-level functions (some of which may be repeated multiple times), which may come from multiple source files.
+
+# Assembly listings
+
+The assembly instruction listing of a symbol must be mapped to the source code. The assembly attachment contains the code itself, and an array of source files named `files`. The format of an assembly line is:
+
+fileIdx:line:offset:cost:assembly
+
+To identify the source file name of any assembly instruction, you must access `files[fileIdx]`. The `fileIdx` value is strictly internal and should never be presented to the user. Always show the source file name and line number in your answers.
+
+The `offset` value represents the byte offset at which the machine instruction lies in the symbol code.
+
+The `cost` value shows how much time was spent by the CPU executing the given machine instruction. The value is a percentage relative to the total execution cost of an entire symbol. If the cost is not present, there was no activity recorded by the profiler for the given instruction.
+
+The `assembly` value is the actual disassembled machine code. It may also contain a comment with:
+- Local jump target, `label`, for example `.L6`.
+- Name of the external function call, `destination`.
+
+## Measurement skid
+
+The measurements present in the attachment may be slightly imprecise due to the way the profiler infrastructure or the CPU works, especially considering out-of-order architectures. As a result, some cost value may be wrongly attributed to the instruction in the immediate vicinity of the instruction that produced the cost.
+
+Take the following example:
+
+```asm
+5% mov rax, [rbx]
+40% inc rax
+```
+
+The first instruction that loads the value from memory is the high-latency one, but it can be dispatched for execution fairly quickly. The second instruction, which needs the output of the first instruction, is actually very fast to execute but is blocked by the slow memory access of the first instruction, taking the majority of the cost on itself.
+
+A careful investigation of the cost attribution is thus needed.
+
+# General optimization procedure
+
+1. Start by mapping the assembly instructions to the source code. All reasoning should be performed with source code first. The assembly can only be used as a supplementary source.
+2. Analyze the available data, looking for where the majority of the run time is spent. Always look at the code as a whole. Do not stop after finding a bunch of interesting spots.
+3. Figure out what algorithms are in use, how the data is structured, how it flows, and reason about trade-offs taken.
+4. Determine whether the code can be made to perform better. Note that some code will already be optimal, despite having hot spots.
+5. Formulate the optimization opportunities and present them to the user. Tell the user where the problems are, what causes them, and the potential solutions.
+6. Do not provide concrete speedup percentages. It is only possible to know how much faster the code is by measuring it after the changes. You can't do that.