Update to Build macOS Apps

{
  "name": "telemetry",
  "description": "Add and verify lightweight macOS runtime telemetry. Use when wiring Logger events or inspecting logs for windows, sidebars, menus, and actions.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 343
    }
  ],
  "skill_md_contents": "---\nname: telemetry\ndescription: Add and verify lightweight macOS runtime telemetry. Use when wiring Logger events or inspecting logs for windows, sidebars, menus, and actions.\n---\n\n# Telemetry\n\n## Quick Start\n\nUse this skill to add lightweight app instrumentation that helps debug behavior\nwithout turning the codebase into a logging landfill. Prefer Apple's unified\nlogging APIs and verify the events after a build/run loop.\n\n## Core Guidelines\n\n- Prefer `Logger` from the `OSLog` framework for structured app logs.\n- Give each feature a clear subsystem/category pair so runtime filtering stays easy.\n- Log meaningful user and app lifecycle events: window opening, sidebar selection changes, menu commands, menu bar extra actions, sync/load milestones, and unexpected fallback paths.\n- Keep info logs concise and stable. Use debug logs for noisy state details.\n- Do not log secrets, auth tokens, personal data, or raw document contents.\n- Add signposts only when measuring timing or performance spans; do not overinstrument by default.\n\n## Minimal Logger Pattern\n\n```swift\nimport OSLog\n\nprivate let logger = Logger(\n  subsystem: Bundle.main.bundleIdentifier ?? \"SampleApp\",\n  category: \"Sidebar\"\n)\n\n@MainActor\nfunc selectItem(_ item: SidebarItem) {\n  logger.info(\"Selected sidebar item: \\(item.id, privacy: .public)\")\n  selection = item.id\n}\n```\n\nUse feature-specific categories like `Windowing`, `Commands`, `MenuBar`, `Sidebar`,\n`Sync`, or `Import` so logs can be filtered quickly.\n\n## Workflow\n\n1. Identify the behavior that needs observability.\n   - Window open/close\n   - Sidebar or inspector selection changes\n   - Menu or keyboard command actions\n   - Menu bar extra actions\n   - Background load/sync/import events\n   - Error and recovery paths\n\n2. Add the smallest useful instrumentation.\n   - Create one `Logger` per feature area or type.\n   - Log action boundaries and key state transitions.\n   - Prefer one high-signal line per user action over noisy value dumps.\n\n3. Build and run the app.\n   - Use `build-run-debug` for the build/run loop.\n   - If `script/build_and_run.sh` exists, prefer `./script/build_and_run.sh --telemetry` for live telemetry checks or `./script/build_and_run.sh --logs` for broader process logs.\n   - Exercise the UI or command path that should emit telemetry.\n\n4. Read runtime logs and verify the event fired.\n   - Use Console.app with a process/subsystem filter when that is the fastest manual check.\n   - Use `log stream --style compact --predicate 'process == \"AppName\"'` for live terminal verification.\n   - Prefer tighter predicates when you know the subsystem/category:\n     `log stream --style compact --predicate 'subsystem == \"com.example.app\" && category == \"Sidebar\"'`\n\n5. Tighten or remove instrumentation.\n   - If the event fires, keep only the logs that remain useful for future debugging.\n   - If it does not fire, move the log closer to the suspected control path and rerun.\n\n## Verification Checklist\n\n- The app builds after telemetry changes.\n- The relevant action emits exactly one clear log line or a small bounded sequence.\n- The log can be filtered by process, subsystem, or category.\n- No sensitive payloads are written to unified logs.\n- Noisy temporary debug logs are removed or demoted before finishing.\n\n## Guardrails\n\n- Do not use `print` as the primary app telemetry mechanism for macOS app code.\n- Do not leave a dense trail of permanent debug logs around every state mutation.\n- Do not claim an event is wired correctly until you have a concrete verification path through Console, `log stream`, or captured process output.\n- If the debugging task is mostly about crash/backtrace analysis rather than action telemetry, switch to `build-run-debug`.\n"
}