winapp-performance

## Workflow 1. Read the [WinUI performance guide](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/winui-performance.md) for capture limits, query options, partial-result handling, privacy and interpretation. 2. Use the existing app PID when possible. Start with `winapp perf start --app <pid> --output <empty-directory> --json`. `--app` also accepts a process name or window title using the same matching rules as `winapp ui`. Use the returned `target.pid` for subsequent UI actions. For a new launch, use `winapp run <project> --profile <empty-directory> --detach --json`. This records after launch, which is enough for navigation, scrolling and other post-launch scenarios. For startup investigations only, add `--profile-mode elevated` (one UAC prompt for the recorder, which the user must approve) and check `Profile.StartupCoverage`; see the guide's [startup workflow](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/winui-performance.md#record-startup-layout). Do not add startup delays or replace a generated `Main`. 3. Wait for successful recording readiness. Save the returned capture ID. 4. Mark the beginning with `winapp perf mark <id> --name scenario-start --json`, drive a short repeatable scenario with verified UI selectors, wait for its visible outcome, then run `winapp perf mark <id> --name scenario-end --json`. 5. Run `winapp perf stop <id> --json` before closing the app. 6. Start with `winapp perf analyze <directory> --from-marker scenario-start --to-marker scenario-end --json` to compare mutually exclusive primary-UI-thread activity, the hottest parsed XAML resources, and the detailed operation ranking. Use `--view parsing` over the same range when the parsing preview needs full paging. Then query `winapp perf analyze <directory> --view hotspots --from-marker scenario-start --to-marker scenario-end --json`; its default threshold is 16.67 ms and each row includes dominant direct child operations. Expand a returned operation with `--view call --id <call-id> --depth 2 --from-marker scenario-start --to-marker scenario-end --json`. Use `--view calls --family layout` with the same marker range when the hotspot evidence points to layout. Query `--view gc --sort duration` over the same marker range to find the longest collection and suspension intervals, then inspect referenced interval IDs. Use element and event views for source and evidence drill-down. Follow `nextOffset`; do not dump NDJSON or ETL into context. For overall resource cost, use `--view resources` over the same marker range; see the guide's [process counters](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/winui-performance.md#compare-process-resource-cost). For app-side composition, query `--view calls --family composition` and `--view events --event DCompDeviceCommit` over the same marker range; see [composition submission](https://github.com/microsoft/WinAppCli/blob/main/docs/guides/winui-performance.md#separate-xaml-work-from-composition-submission). 7. Report observed cost, supporting event IDs, coverage gaps, and one concrete next experiment. Preserve stdout when partial results accompany a nonzero exit code. ## Guardrails - Use `--profile-mode elevated` only for startup, and tell the user to expect a UAC prompt. If they decline it, do not retry; fall back to the default attach mode and say that early startup may be missing. Otherwise never elevate, change tracing ACLs, or modify app code to make capture work. - Recording is local only. Do not combine `run --profile` with `--on sandbox`; see the guide for the supported launch and recording commands. - Readiness is not decoded coverage. Missing events are inconclusive. - For WinUI operations, use elapsed-time terminology; do not claim CPU/GPU attribution, displayed FPS, proven input-to-display latency, or complete startup/visual-tree coverage. - `Unclassified` includes idle, waits, and uninstrumented work. Do not describe it as app code or CPU use. Off-thread image decode is not UI-thread occupancy. - Process CPU counters include all target threads but do not attribute functions, modules, or waits. Sampled memory/thread maxima can miss brief spikes; missing samples are not zero resource use. - Trace-local element IDs are not UI Automation selectors. - Composition calls are elapsed API scopes, not GPU work or display latency. DComp device commits are notifications, not timed or displayed frames; check `directCompositionProvider` before interpreting missing events. - Call trees are instrumented operation scopes, not CPU stacks or visual trees. Keep exclusive scope time distinct from element self time. - GC is requested by default but may be unavailable. Check `gcCoverage` separately; missing events are not zero pauses. Background GC duration is not suspension time, and overlapping runtime suspension is not proof that GC blocked the native UI. - Keep raw captures local unless the user has reviewed and authorized sharing them. - Use the UI automation skill to interact with the app and troubleshooting/debug output workflows for crashes; neither replaces performance evidence.