@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/web-performance/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: web-performance
 description: "Web performance: Core Web Vitals (LCP, INP, CLS), image optimization, code splitting, caching strategies, bundle analysis, Lighthouse"
 tags: [performance, core-web-vitals, lighthouse, optimization, frontend, caching]
 version: "2025.1"
@@ -12,9 +13,9 @@ Google uses Core Web Vitals as ranking signals. All pages should meet the "Good"
 
 | Metric | Good | Needs Improvement | Poor | What It Measures |
 |--------|------|-------------------|------|-----------------|
-| **LCP** | <= 2.5s | <= 4.0s | > 4.0s | Largest Contentful Paint — loading speed |
-| **INP** | <= 200ms | <= 500ms | > 500ms | Interaction to Next Paint — responsiveness |
-| **CLS** | <= 0.1 | <= 0.25 | > 0.25 | Cumulative Layout Shift — visual stability |
+| **LCP** | <= 2.5s | <= 4.0s | > 4.0s | Largest Contentful Paint  -  loading speed |
+| **INP** | <= 200ms | <= 500ms | > 500ms | Interaction to Next Paint  -  responsiveness |
+| **CLS** | <= 0.1 | <= 0.25 | > 0.25 | Cumulative Layout Shift  -  visual stability |
 
 ## Image Optimization
 
@@ -31,7 +32,7 @@ function HeroSection() {
         alt="Hero banner showing product lineup"
         width={1200}
         height={600}
-        priority  // Preloads — use for above-the-fold LCP images
+        priority  // Preloads  -  use for above-the-fold LCP images
         sizes="100vw"
         quality={85}
       />
@@ -120,9 +121,9 @@ const HeavyEditor = dynamic(() => import('@/components/RichTextEditor'), {
 import { debounce, throttle } from 'lodash-es'; // NOT 'lodash'
 import { format, parseISO } from 'date-fns'; // NOT import * as dateFns
 
-// Barrel exports can hurt tree shaking — use direct imports
+// Barrel exports can hurt tree shaking  -  use direct imports
 import { Button } from '@/components/Button'; // Direct
-// NOT: import { Button } from '@/components'; // Barrel — may pull entire lib
+// NOT: import { Button } from '@/components'; // Barrel  -  may pull entire lib
 
 // Mark side-effect-free in package.json
 // {
@@ -330,7 +331,7 @@ npx lhci autorun --config=lighthouserc.json
 - Do not lazy-load above-the-fold content
 - Do not import entire libraries when you need one function
 - Do not ignore CLS from dynamically injected content (ads, banners)
-- Do not use `document.write()` — it blocks parsing
+- Do not use `document.write()`  -  it blocks parsing
 - Do not serve uncompressed assets (enable gzip/brotli)
 
 ## Troubleshooting

package/pipeline/skills/shared/external/web-testing/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: web-testing
 description: "Web testing: Vitest unit tests, React Testing Library, Playwright E2E, MSW API mocking, testing hooks and async operations"
 tags: [testing, vitest, playwright, react-testing-library, msw, e2e, frontend]
 version: "2025.1"
@@ -10,11 +11,11 @@ version: "2025.1"
 
 ```
          [E2E Tests - Playwright]
-           (slow, high confidence — few)
+           (slow, high confidence  -  few)
       [Integration Tests - RTL + MSW]
-        (medium speed, realistic — moderate)
+        (medium speed, realistic  -  moderate)
    [Unit Tests - Vitest]
-     (fast, isolated — many)
+     (fast, isolated  -  many)
 ```
 
 ## Vitest (Unit Testing)
@@ -365,12 +366,12 @@ test('completes checkout flow', async ({ page }) => {
 ## Don'ts
 
 - Do not test implementation details (internal state, method calls)
-- Do not use `container.querySelector` — use RTL queries instead
+- Do not use `container.querySelector`  -  use RTL queries instead
 - Do not write E2E tests for everything; reserve for critical paths
 - Do not use `waitFor` wrapping `getBy*` queries (they already throw)
-- Do not skip flaky tests permanently — fix the root cause
+- Do not skip flaky tests permanently  -  fix the root cause
 - Do not mock everything; prefer integration over isolation
-- Do not use `sleep` or fixed timeouts — use proper waiters
+- Do not use `sleep` or fixed timeouts  -  use proper waiters
 - Do not test third-party library internals
 
 ## Troubleshooting

package/pipeline/skills/shared/external/widgetkit/SKILL.md

@@ -8,7 +8,7 @@ description: "Implement, review, or improve widgets, Live Activities, and contro
 Build home screen widgets, Lock Screen widgets, Live Activities, Dynamic Island
 presentations, Control Center controls, and StandBy surfaces for iOS 26+.
 
-See `references/widgetkit-advanced.md` for timeline strategies, push-based
+See [references/widgetkit-advanced.md](references/widgetkit-advanced.md) for timeline strategies, push-based
 updates, Xcode setup, and advanced patterns.
 
 ## Contents
@@ -24,6 +24,7 @@ updates, Xcode setup, and advanced patterns.
 - [Control Center Widgets (iOS 18+)](#control-center-widgets-ios-18)
 - [Lock Screen Widgets](#lock-screen-widgets)
 - [StandBy Mode](#standby-mode)
+- [Design Patterns](#design-patterns)
 - [iOS 26 Additions](#ios-26-additions)
 - [Common Mistakes](#common-mistakes)
 - [Review Checklist](#review-checklist)
@@ -182,19 +183,12 @@ struct CategoryProvider: AppIntentTimelineProvider {
 
 ## Widget Families
 
-### System Families (Home Screen)
-
 | Family | Platform |
 |---|---|
 | `.systemSmall` | iOS, iPadOS, macOS, CarPlay (iOS 26+) |
 | `.systemMedium` | iOS, iPadOS, macOS |
 | `.systemLarge` | iOS, iPadOS, macOS |
 | `.systemExtraLarge` | iPadOS only |
-
-### Accessory Families (Lock Screen / watchOS)
-
-| Family | Platform |
-|---|---|
 | `.accessoryCircular` | iOS, watchOS |
 | `.accessoryRectangular` | iOS, watchOS |
 | `.accessoryInline` | iOS, watchOS |
@@ -327,7 +321,6 @@ struct DeliveryActivityWidget: Widget {
 ### Starting, Updating, and Ending
 
 ```swift
-// Start
 let attributes = DeliveryAttributes(orderNumber: 123, restaurantName: "Pizza Place")
 let state = DeliveryAttributes.ContentState(
     driverName: "Alex",
@@ -337,14 +330,9 @@ let state = DeliveryAttributes.ContentState(
 let content = ActivityContent(state: state, staleDate: nil, relevanceScore: 75)
 let activity = try Activity.request(attributes: attributes, content: content, pushType: .token)
 
-// Update (optionally with alert)
 let updated = ActivityContent(state: newState, staleDate: nil, relevanceScore: 90)
 await activity.update(updated)
-await activity.update(updated, alertConfiguration: AlertConfiguration(
-    title: "Order Update", body: "Your driver is nearby!", sound: .default
-))
 
-// End
 let final = ActivityContent(state: finalState, staleDate: nil, relevanceScore: 0)
 await activity.end(final, dismissalPolicy: .after(.now.addingTimeInterval(3600)))
 ```
@@ -409,6 +397,24 @@ landscape). Use `@Environment(\.widgetLocation)` for conditional rendering:
 // location == .standBy, .homeScreen, .lockScreen, .carPlay, etc.
 ```
 
+## Design Patterns
+
+- **Prefer `Gauge` over manual arcs.** Use `.gaugeStyle(.accessoryCircular)` for
+  Lock Screen circular widgets and `.linearCapacity` for home screen capacity bars.
+  The system handles styling, accessibility, and rendering-mode adaptation.
+- **Use `.containerBackground(_:for: .widget)`** (iOS 17+) for widget backgrounds
+  instead of padding and background modifiers.
+- **Use `Canvas` for dense visualizations** like sparklines or mini bar charts.
+  The lack of per-element accessibility is acceptable since the entire widget
+  surface is a single tap target.
+- **Match timeline refresh to data granularity.** Apple budgets
+  [40-70 refreshes per day](https://sosumi.ai/documentation/widgetkit/keeping-a-widget-up-to-date)
+  with entries at least 5 minutes apart. Use `Text(timerInterval:countsDown:)`
+  for live countdowns instead of burning timeline entries.
+
+See [references/widgetkit-advanced.md](references/widgetkit-advanced.md) for
+code examples and detailed guidance on each pattern.
+
 ## iOS 26 Additions
 
 ### Liquid Glass Support
@@ -443,8 +449,8 @@ are legible at a glance for driver safety.
 ## Common Mistakes
 
 1. **Using IntentTimelineProvider instead of AppIntentTimelineProvider.**
-   `IntentTimelineProvider` is deprecated. Use `AppIntentTimelineProvider` with
-   the App Intents framework.
+   `IntentTimelineProvider` is the older SiriKit Intents-based provider. Prefer
+   `AppIntentTimelineProvider` with the App Intents framework for new widgets.
 
 2. **Exceeding the refresh budget.** Widgets have a daily refresh limit. Do not
    call `WidgetCenter.shared.reloadTimelines(ofKind:)` on every minor data change.
@@ -493,5 +499,5 @@ are legible at a glance for driver safety.
 
 ## References
 
-- Advanced guide: `references/widgetkit-advanced.md`
+- Advanced guide: [references/widgetkit-advanced.md](references/widgetkit-advanced.md)
 - Apple docs: [WidgetKit](https://sosumi.ai/documentation/widgetkit) | [ActivityKit](https://sosumi.ai/documentation/activitykit) | [Keeping a widget up to date](https://sosumi.ai/documentation/widgetkit/keeping-a-widget-up-to-date)

package/pipeline/skills/shared/external/widgetkit/references/widgetkit-advanced.md

@@ -20,6 +20,7 @@
 - [ActivityStyle](#activitystyle)
 - [Dismissal Policies](#dismissal-policies)
 - [Querying Active Widgets and Activities](#querying-active-widgets-and-activities)
+- [Design Patterns](#design-patterns)
 - [Apple Documentation Links](#apple-documentation-links)
 
 ## Timeline Strategies
@@ -855,6 +856,104 @@ Task {
 }
 ```
 
+## Design Patterns
+
+### Prefer Gauge for Value Indicators
+
+Use `Gauge` (iOS 16+) instead of manual `Circle` or `Path` arcs to show a value
+within a range. The system handles styling, accessibility, and rendering-mode
+adaptation automatically.
+
+- `.accessoryCircular`  -  open ring with center value label, matches the system
+  complication style. Use for `accessoryCircular` Lock Screen widgets.
+- `.linearCapacity`  -  horizontal bar that fills leading to trailing. Use for
+  home screen widgets when a capacity bar fits.
+
+```swift
+// accessoryCircular Lock Screen widget
+struct StepsCircularView: View {
+    let entry: StepsEntry
+
+    var body: some View {
+        Gauge(value: Double(entry.stepCount), in: 0...10000) {
+            Image(systemName: "figure.walk")
+        } currentValueLabel: {
+            Text("\(entry.stepCount)")
+        }
+        .gaugeStyle(.accessoryCircular)
+    }
+}
+
+// Home screen capacity bar
+Gauge(value: storageUsed, in: 0...storageTotal) {
+    Text("Storage")
+} currentValueLabel: {
+    Text(storageUsed, format: .byteCount(style: .file))
+}
+.gaugeStyle(.linearCapacity)
+```
+
+### Use containerBackground for Widget Backgrounds
+
+`.containerBackground(_:for: .widget)` (iOS 17+) is the designated way to set
+widget backgrounds. Replaces older padding and background patterns. The system
+uses this placement to correctly render backgrounds across all widget surfaces.
+
+```swift
+struct OrderWidgetView: View {
+    let entry: OrderEntry
+
+    var body: some View {
+        VStack(alignment: .leading) {
+            Text(entry.orderName).font(.headline)
+            Text(entry.status).foregroundStyle(.secondary)
+        }
+        .containerBackground(.fill.tertiary, for: .widget)
+    }
+}
+```
+
+### Use Canvas for Dense Visualizations
+
+Use `Canvas` for sparklines, mini bar charts, or heat maps inside widgets. The
+lack of per-element accessibility is acceptable since the entire widget surface
+is a single tap target.
+
+```swift
+struct SparklineView: View {
+    let values: [Double]
+
+    var body: some View {
+        Canvas { context, size in
+            guard values.count > 1 else { return }
+            let maxVal = values.max() ?? 1
+            let step = size.width / CGFloat(values.count - 1)
+            var path = Path()
+            for (i, value) in values.enumerated() {
+                let x = step * CGFloat(i)
+                let y = size.height * (1 - value / maxVal)
+                if i == 0 { path.move(to: CGPoint(x: x, y: y)) }
+                else { path.addLine(to: CGPoint(x: x, y: y)) }
+            }
+            context.stroke(path, with: .color(.blue), lineWidth: 2)
+        }
+    }
+}
+```
+
+### Match Timeline Refresh to Data Granularity
+
+Apple budgets
+[40-70 refreshes per day](https://sosumi.ai/documentation/widgetkit/keeping-a-widget-up-to-date)
+for frequently viewed widgets, with entries at least 5 minutes apart. Align
+reload cadence to how often the underlying data actually changes.
+
+- Generate entries for as many future dates as possible to reduce reload requests.
+- Use `.after(date)` when data updates on a known schedule (market hours, transit).
+- Use `.never` when data only changes from user action.
+- Use `Text(timerInterval:countsDown:)` for live countdowns instead of burning
+  timeline entries on every tick.
+
 ## Apple Documentation Links
 
 - [WidgetKit](https://sosumi.ai/documentation/widgetkit)

package/pipeline/skills/shared/external/xcode-build-benchmark/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: xcode-build-benchmark
+description: Benchmark Xcode clean and incremental builds with repeatable inputs, timing summaries, and timestamped `.build-benchmark/` artifacts. Use when a developer wants a baseline, wants to compare before and after changes, asks to measure build performance, mentions build times, build duration, how long builds take, or wants to know if builds got faster or slower.
+user-invocable: false
+---
+
+# Xcode Build Benchmark
+
+Use this skill to produce a repeatable Xcode build baseline before anyone tries to optimize build times.
+
+## Core Rules
+
+- Measure before recommending changes.
+- Capture clean and incremental builds separately.
+- Keep the command, destination, configuration, scheme, and warm-up rules consistent across runs.
+- Write a timestamped JSON artifact to `.build-benchmark/`.
+- Do not change project files as part of benchmarking.
+
+## Inputs To Collect
+
+Confirm or infer:
+
+- workspace or project path
+- scheme
+- configuration
+- destination
+- whether the user wants simulator or device numbers
+- whether a custom `DerivedData` path is needed
+
+If the project has both clean-build and incremental-build pain, benchmark both. That is the default.
+
+## Worktree Considerations
+
+When benchmarking inside a git worktree, SPM packages with `exclude:` paths that reference gitignored directories (e.g., `__Snapshots__`) will cause `xcodebuild -resolvePackageDependencies` to crash. Create those missing directories before running any builds.
+
+## Default Workflow
+
+1. Normalize the build command and note every flag that affects caching or module reuse.
+2. Run one warm-up build if needed to validate that the command succeeds.
+3. Run 3 clean builds.
+4. If `COMPILATION_CACHE_ENABLE_CACHING = YES` is detected, run 3 cached clean builds. These measure clean build time with a warm compilation cache -- the realistic scenario for branch switching, pulling changes, or Clean Build Folder. The script handles this automatically by building once to warm the cache, then deleting DerivedData (but not the compilation cache) before each measured run. Pass `--no-cached-clean` to skip.
+5. Run 3 zero-change builds (build immediately after a successful build with no edits). This measures the fixed overhead floor: dependency computation, project description transfer, build description creation, script phases, codesigning, and validation. A zero-change build that takes more than a few seconds indicates avoidable per-build overhead. Use the default `benchmark_builds.py` invocation (no `--touch-file` flag).
+6. Optionally run 3 incremental builds with a file touch to measure a real edit-rebuild loop. Use `--touch-file path/to/SomeFile.swift` to touch a representative source file before each build.
+7. Save the raw results and summary into `.build-benchmark/`.
+8. Report medians and spread, not just the single fastest run.
+
+## Preferred Command Path
+
+Use the shared helper when possible:
+
+```bash
+python3 scripts/benchmark_builds.py \
+  --workspace App.xcworkspace \
+  --scheme MyApp \
+  --configuration Debug \
+  --destination "platform=iOS Simulator,name=iPhone 16" \
+  --output-dir .build-benchmark
+```
+
+If you cannot use the helper script, run equivalent `xcodebuild` commands with `-showBuildTimingSummary` and preserve the raw output.
+
+## Required Output
+
+Return:
+
+- clean build median, min, max
+- cached clean build median, min, max (when COMPILATION_CACHE_ENABLE_CACHING is enabled)
+- zero-change build median, min, max (fixed overhead floor)
+- incremental build median, min, max (if `--touch-file` was used)
+- biggest timing-summary categories
+- environment details that could affect comparisons
+- path to the saved artifact
+
+If results are noisy, say so and recommend rerunning under calmer conditions.
+
+## When To Stop
+
+Stop after measurement if the user only asked for benchmarking. If they want optimization guidance, hand off the artifact to the relevant specialist by reading its SKILL.md and applying its workflow to the same project context:
+
+- [`xcode-compilation-analyzer`](../xcode-compilation-analyzer/SKILL.md)
+- [`xcode-project-analyzer`](../xcode-project-analyzer/SKILL.md)
+- [`spm-build-analysis`](../spm-build-analysis/SKILL.md)
+- [`xcode-build-orchestrator`](../xcode-build-orchestrator/SKILL.md) for full orchestration
+
+## Additional Resources
+
+- For the benchmark contract, see [references/benchmarking-workflow.md](references/benchmarking-workflow.md)
+- For the shared artifact format, see [references/benchmark-artifacts.md](references/benchmark-artifacts.md)
+- For the JSON schema, see [schemas/build-benchmark.schema.json](schemas/build-benchmark.schema.json)

package/pipeline/skills/shared/external/xcode-build-benchmark/references/benchmark-artifacts.md

@@ -0,0 +1,94 @@
+# Benchmark Artifacts
+
+All skills in this repository should treat `.build-benchmark/` as the canonical location for measured build evidence.
+
+## Goals
+
+- Keep build measurements reproducible.
+- Make clean and incremental build data easy to compare.
+- Preserve enough context for later specialist analysis without rerunning the benchmark.
+
+## Wall-Clock vs Cumulative Task Time
+
+The `duration_seconds` field on each run and the `median_seconds` in the summary represent **wall-clock time** -- how long the developer actually waits. This is the primary success metric.
+
+The `timing_summary_categories` are **aggregated task times** parsed from Xcode's Build Timing Summary. Because Xcode runs many tasks in parallel across CPU cores, these totals typically exceed the wall-clock duration. A large cumulative `SwiftCompile` value is diagnostic evidence of compiler workload, not proof that compilation is blocking the build. Always compare category totals against the wall-clock median before concluding that a category is a bottleneck.
+
+## File Layout
+
+Recommended outputs:
+
+- `.build-benchmark/<timestamp>-<scheme>.json`
+- `.build-benchmark/<timestamp>-<scheme>-clean-1.log`
+- `.build-benchmark/<timestamp>-<scheme>-clean-2.log`
+- `.build-benchmark/<timestamp>-<scheme>-clean-3.log`
+- `.build-benchmark/<timestamp>-<scheme>-cached-clean-1.log` (when COMPILATION_CACHE_ENABLE_CACHING is enabled)
+- `.build-benchmark/<timestamp>-<scheme>-cached-clean-2.log`
+- `.build-benchmark/<timestamp>-<scheme>-cached-clean-3.log`
+- `.build-benchmark/<timestamp>-<scheme>-incremental-1.log`
+- `.build-benchmark/<timestamp>-<scheme>-incremental-2.log`
+- `.build-benchmark/<timestamp>-<scheme>-incremental-3.log`
+
+Use an ISO-like UTC timestamp without spaces so the files sort naturally.
+
+## Artifact Requirements
+
+Each JSON artifact should include:
+
+- schema version
+- creation timestamp
+- project context
+- environment details when available
+- the normalized build command
+- separate `clean` and `incremental` run arrays
+- summary statistics for each build type
+- parsed timing-summary categories
+- free-form notes for caveats or noise
+
+## Clean, Cached Clean, And Incremental Separation
+
+Do not merge different build type measurements into a single list. They answer different questions:
+
+- **Clean builds** show full build-system, package, and module setup cost with a cold compilation cache.
+- **Cached clean builds** show clean build cost when the compilation cache is warm. This is the realistic scenario for branch switching, pulling changes, or Clean Build Folder. Only present when `COMPILATION_CACHE_ENABLE_CACHING = YES` is detected.
+- **Incremental builds** show edit-loop productivity and script or cache invalidation problems.
+
+## Raw Logs
+
+Store raw `xcodebuild` output beside the JSON artifact whenever possible. That allows later skills to:
+
+- re-parse timing summaries
+- inspect failed builds
+- search for long type-check warnings
+- correlate build-system phases with recommendations
+
+## Measurement Caveats
+
+### COMPILATION_CACHE_ENABLE_CACHING
+
+`COMPILATION_CACHE_ENABLE_CACHING = YES` stores compiled artifacts in a system-managed cache outside DerivedData so that repeated compilations of identical inputs are served from cache. The standard clean-build benchmark (`xcodebuild clean` between runs) may add overhead from cache population without showing the corresponding cache-hit benefit.
+
+The benchmark script automatically detects `COMPILATION_CACHE_ENABLE_CACHING = YES` and runs a **cached clean** benchmark phase. This phase:
+
+1. Builds once to warm the compilation cache.
+2. Deletes DerivedData (but not the compilation cache) before each measured run.
+3. Rebuilds, measuring the cache-hit clean build time.
+
+The cached clean metric captures the realistic developer experience: branch switching, pulling changes, and Clean Build Folder. Use the cached clean median as the primary comparison metric when evaluating `COMPILATION_CACHE_ENABLE_CACHING` impact.
+
+To skip this phase, pass `--no-cached-clean`.
+
+### First-Run Variance
+
+The first clean build after the warmup cycle often runs 20-40% slower than subsequent clean builds due to cold OS-level caches (disk I/O, dynamic linker cache, etc.). The benchmark script mitigates this by running a warmup clean+build cycle before measured runs. If variance between the first and later clean runs is still high, prefer the median or min over the mean, and note the variance in the artifact's `notes` field.
+
+## Shared Consumer Expectations
+
+Any skill reading a benchmark artifact should be able to identify:
+
+- what was measured
+- how it was measured
+- whether the run succeeded
+- whether the results are stable enough to compare
+
+For the authoritative field-level schema, see [../schemas/build-benchmark.schema.json](../schemas/build-benchmark.schema.json).

package/pipeline/skills/shared/external/xcode-build-benchmark/references/benchmarking-workflow.md

@@ -0,0 +1,67 @@
+# Benchmarking Workflow
+
+Use this reference when you need the full operational contract for collecting Xcode build measurements.
+
+## Goal
+
+Produce a benchmark artifact that another skill can trust without rerunning the same setup discovery.
+
+## Benchmark Contract
+
+- Measure both clean and incremental builds unless the user narrows the scope.
+- Use the same scheme, configuration, destination, and command flags for all measured runs.
+- Record the exact command and any environment overrides.
+- Keep clean and incremental runs in separate arrays in the artifact.
+- Save wall-clock timing plus any parsed timing-summary categories.
+
+## Suggested Run Counts
+
+- Clean builds: 3 measured runs
+- Incremental builds: 3 measured runs
+- Warm-up: 0 to 1 validation run, excluded from the summary unless the user explicitly wants it included
+
+## Clean Build Rules
+
+- Clear build products with `xcodebuild clean` or an equivalent clean-build-folder step before each measured clean run.
+- Do not change scheme, destination, or configuration between runs.
+- If the command fails, store the failure and stop rather than mixing failed and successful runs.
+
+## Incremental Build Rules
+
+- Use the same build command after a successful baseline build.
+- Do not clean between incremental runs.
+- If the user wants edit-loop benchmarking, note the file change strategy explicitly in the artifact.
+- If there are no source edits between runs, label the result as no-edit incremental timing.
+
+## What To Capture
+
+At minimum, keep:
+
+- timestamp
+- host machine info if available
+- Xcode version if available
+- workspace or project path
+- scheme, configuration, destination
+- exact `xcodebuild` command
+- duration per run
+- success or failure
+- parsed timing-summary categories
+- notes on warm-up behavior or unusual noise
+
+## Reporting Guidance
+
+Use medians for the headline number. Also include:
+
+- min and max
+- range
+- category totals from the timing summary
+- obvious outliers or instability
+
+## Handoff Expectations
+
+The next optimization skill should be able to answer:
+
+- Is the main problem clean, incremental, or both?
+- Which build categories dominate time?
+- Which command produced the evidence?
+- Is the baseline trustworthy enough to compare before and after changes?