check

name	check
description	<EXTREMELY_IMPORTANT>Check any app, product, or service. Particularly for bugs, performance bottlenecks, and areas for improvement.</EXTREMELY_IMPORTANT>

ReadyCheck: Build, Run, Capture, and Analyze

Purpose

Build and launch an application with ADA tracing enabled, capture execution traces, voice narration, and screen recording in the background, then automatically analyze the session when complete.

MANDATORY: Environment Setup

Before running any ada command, resolve the packaged ReadyCheck release and set the environment:

Bash( command: READYCHECK_PLUGIN_ROOT="$(${CLAUDE_PLUGIN_ROOT}/scripts/ensure_release.sh)", background: true )

Set variable $ADA_BIN_DIR to "${READYCHECK_PLUGIN_ROOT}/bin" Set variable $ADA_LIB_DIR to "${READYCHECK_PLUGIN_ROOT}/lib"

IMPORTANT: Always use the full path {{$ADA_BIN_DIR}}/ada for commands to avoid conflicts with other ada binaries in PATH. ensure_release.sh automatically prefers a valid local dist/ runtime when the plugin is being tested from a ReadyCheck checkout.

MANDATORY: Step 1. Preflight Check

If $PREFLIGHT_CHECK is set to 1, skip to Step 2.

Run the ADA doctor to verify all dependencies:

${ADA_BIN_DIR}/ada doctor check --format json

Parse the JSON output. Check all fields are ok: true.

If any check fails:

1. Show the user which checks failed with fix instructions
2. Stop and ask user to fix issues
3. After fixes, re-run ada doctor check

If all checks pass:

• Set $PREFLIGHT_CHECK = 1
• Continue to Step 2

MANDATORY: Step 2. Project Detection

You MUST explore the project to find the app to run, the build system building it, and the launch arguments required to run it.

Set $LAUNCH_ARGS to the launch arguments string (empty string if none required).

Locate the binary and build system:

You MUST identify the build system (Xcode, SPM, CMake, Cargo, etc.) and the path to the built binary.

Detect launch arguments:

You MUST search for launch arguments in the following sources, in priority order:

1. Xcode scheme files (.xcscheme) — extract enabled CommandLineArgument entries from <LaunchAction>. See Appendix A for search paths and extraction rules.
2. README / documentation — look for documented run commands.
3. Binary help output — if no scheme or docs exist, run the binary with --help or no args and check for usage text.

MANDATORY: Step 3. Build (if applicable)

You MAY use the app's build system to build the app.

MANDATORY: Step 4. Start Capture (Background)

Start capturing with background: true and title "Start ReadyCheck capture session":

Bash( command: export ADA_AGENT_RPATH_SEARCH_PATHS="{{$ADA_LIB_DIR}}" "${{ADA_BIN_DIR}}/ada capture start -- $LAUNCH_ARGS", background: true )

You MUST substitute $ADA_LIB_DIR and $ADA_BIN_DIR in the invocation command with the variable you got in Preflight Check. You MUST substitute $LAUNCH_ARGS with the value detected in Detect launch arguments, and omit -- $LAUNCH_ARGS entirely when $LAUNCH_ARGS is empty. You MUST save the returned task ID as $CAPTURE_TASK_ID.

Report to user:

Capture running

Interact with your app. When you quit the app, capture stops automatically.

MANDATORY: Step 5. Wait for Capture Completion

Wait for the user to finish interacting with their app. When the user indicates they are done, collect the capture output:

TaskOutput( task_id: $CAPTURE_TASK_ID, block: false )

Parse the output for the session directory path.

If capture is still running:

• Inform the user the app is still running
• Wait for user to quit the app, then check again

If capture succeeded:

• Extract the session ID from the session directory path. Append it to $DOCTOR_CAPTURE_SESSIONS (comma-separated).
• Report to user:

  Capture completed

  Session directory path: [session_directory_path]

• Continue to Step 6

If capture failed:

You MUST execute this ONLY when the capture is failed. You MUST NOT execute this until the capture is failed.

1. Show the error message to the user.

2. Entitlement Diagnosis (macOS only):

   Run entitlement inspection on the target binary:

   Bash( command: "codesign -d --entitlements - 2>&1" )

   Parse the output:

   • If codesign is not found or exits non-zero with "not signed at all": set $MISSING_ENTITLEMENTS to all three required keys. Proceed to step 3.
   • Otherwise: check the XML output for presence of:
     • com.apple.security.cs.disable-library-validation
     • com.apple.security.cs.allow-dyld-environment-variables
     • com.apple.security.get-task-allow

   Set $MISSING_ENTITLEMENTS to the list of keys NOT present.

   • If $MISSING_ENTITLEMENTS is empty: entitlements are not the cause. Show raw error, stop.

3. Report missing entitlements:

   Report to user:

   Capture failed — likely cause: missing code-signing entitlements

   The target binary is missing entitlements required for instrumentation:

   [list each from $MISSING_ENTITLEMENTS]

   Without these, macOS blocks dynamic library injection into hardened-runtime processes.

4. Offer re-signing:

   Ask the user whether to re-sign the binary with ad-hoc signing and the required entitlements.

   If user consents:

   Bash( command: "ENTITLEMENTS=$(mktemp /tmp/ada_entitlements.XXXXXX.plist) && cat > \"$ENTITLEMENTS\" <<'PLIST'\n\n\n\n\n com.apple.security.get-task-allow\n \n com.apple.security.cs.disable-library-validation\n \n com.apple.security.cs.allow-dyld-environment-variables\n \n\n\nPLIST\ncodesign --force --sign - --entitlements \"$ENTITLEMENTS\" && rm \"$ENTITLEMENTS\"" )
   • If signing succeeds: inform user, return to Step 4 (retry capture).
   • If signing fails: show codesign error, stop.

   If user declines: Stop.

MANDATORY: Step 6. Auto-Analyze

Automatically invoke the /readycheck:analyze skill:

Skill(skill: "analyze")

Follow the analyze skill workflow from there.

Error Handling

• Build failure: Show build errors, suggest fixes
• Binary not found: Guide user to specify path manually
• Capture failure (entitlement issue): Diagnose missing entitlements on the target binary, offer re-signing with user consent
• Capture failure (other): Show error output, suggest re-running

Appendix A: Xcode Scheme Launch Argument Extraction

Search paths:

You MUST search these paths (relative to the project root) for .xcscheme files, excluding .build/ and DerivedData/ directories:

• .swiftpm/xcode/xcshareddata/xcschemes/*.xcscheme
• *.xcodeproj/xcshareddata/xcschemes/*.xcscheme
• *.xcworkspace/../*.xcodeproj/xcshareddata/xcschemes/*.xcscheme

Extraction rules:

You MUST parse <LaunchAction> > <CommandLineArguments> > <CommandLineArgument> elements. You MUST include only entries where isEnabled="YES". You MUST concatenate the argument attribute values in document order, space-separated. You MUST skip entries where isEnabled="NO". You MUST set $LAUNCH_ARGS to empty string if <CommandLineArguments> is absent from <LaunchAction>.

Given this .xcscheme fragment inside <LaunchAction>:

<CommandLineArguments>
   <CommandLineArgument argument="--arg1" isEnabled="YES"/>
   <CommandLineArgument argument="--arg2" isEnabled="YES"/>
   <CommandLineArgument argument="--arg3" isEnabled="NO"/>
</CommandLineArguments>

Set $LAUNCH_ARGS to: --arg1 --arg2

(--arg3 is excluded because isEnabled="NO")

Given a <LaunchAction> with no <CommandLineArguments> element (typical for GUI apps):

Set $LAUNCH_ARGS to: (empty string)