Analyze

Analyze ADA Capture Session

Purpose

Analyze a captured ADA session using a voice-first workflow that extracts user observations from transcripts, then correlates with trace events and screenshots for evidence-based diagnosis.

MANDATORY: Environment

MANDATORY: Replace ${CLAUDEPLUGINROOT} with the actual path to the source plugin root directory.

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

READYCHECK_PLUGIN_ROOT="$(${CLAUDE_PLUGIN_ROOT}/scripts/ensure_release.sh)"

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: Recognize Session To Analyze

You MUST recognize session to analyze and set $SESSION to the session ID.

To list available sessions: Command: ${ADABINDIR}/ada session list

MANDATORY: Execution Principles

You MUST just follow the skill's workflow without using todo or task tool to plan what the next to do. You MUST spawn subagents with background set to false with the Agent tool. You MUST NOT use the todo or task tool to plan what the next to do. You MUST NOT spawn subagents with background set to true with the Agent tool.

MANDATORY: Step 1. Preflight Check

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

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. Intialization

Run session summary to assess trace data quality:

Command: ${ADABINDIR}/ada query {{$SESSION}} summary --reading-model sonnet --format json

Parse the JSON output. If os_info is present, set $OSCATEGORY to os_info.category. Otherwise, set $OSCATEGORY to "macos" (default for sessions captured before OS metadata was added). You MUST NOT expose os_info and $OS_CATEGORY in the response send to the user.

Create Analysis Session:

Run:

Command: ${ADABINDIR}/ada analysis init --capture-session {{$SESSION}} --format json

Parse the JSON output. Set $ANALYSISSESSIONPATH to the path field. Append the analysis_session_id to $DOCTORANALYSISSESSIONS (comma-separated). Append {{$SESSION}} to $DOCTORCAPTURESESSIONS (comma-separated).

MANDATORY: Step 3. Extract User Observations

Resolve the following variables:

1. Set $CAPTURE_SESSION to the capture_session_id field in {{$ANALYSIS_SESSION_PATH}}/index.json.

Spawn the observation-extractor subagent with the following resolved context. You MUST set background to false when spawning this subagent. You MUST NOT set background to true when spawning this subagent.

**ADA Binary Directory**: ${ADA_BIN_DIR}
**Analysis Session Path**: {{$ANALYSIS_SESSION_PATH}}
**Capture Session**: {{$CAPTURE_SESSION}}
**Output Directory**: {{$ANALYSIS_SESSION_PATH}}

The observation-extractor returns a minimal JSON response: {"status": "complete", "issue_count": N, "has_ambiguities": true|false}. All detail is in {{$ANALYSIS_SESSION_PATH}}/user_observations.json on disk.

CRITICAL: If issue_count > 0:

You MUST go to Step 4: Confirm and Clarify Issues.

MUST:

• You MUST proceed to Step 4: Confirm and Clarify Issues whenever issue_count > 0.

MUST NOT:

• You MUST NOT skip issues based on your own assessment.
• You MUST NOT declare "no actionable issues" when issue_count > 0.

CRITICAL: If issue_count is 0:

You MUST inform the user:

> No issues found in the session. > > You can ask me to output the transcript and identify potential issues in the texts.

Then STOP.

MANDATORY: Step 4. Confirm and Clarify Issues

After the observation-extractor completes, present the extracted issues to the user for confirmation and correction, then resolve any ambiguities on the corrected text before proceeding.

4.1. Confirm and Select Issues

Read all issues from {{$ANALYSIS_SESSION_PATH}}/user_observations.json.

For each issue, you MUST render the details field alongside the description. Format adapts to issue type:

For bug issues:

**ISS-XXX** (bug, {{severity}}) — {{description}}

> User: {{raw_user_quotes}}

- Steps to reproduce: {{details.steps_to_reproduce}}
- Expected: {{details.expected_result}}
- Actual: {{details.actual_result}}

For improvement issues:

**ISS-XXX** (improvement, {{severity}}) — {{description}}

> User: {{raw_user_quotes}}

- Current behavior: {{details.observed_behavior}}
- User difficulty: {{details.user_difficulty}}
- Suggested improvement: {{details.suggested_improvement}}

For feature issues:

**ISS-XXX** (feature, {{severity}}) — {{description}}

> User: {{raw_user_quotes}}

- User story: {{details.user_story}}
- Acceptance criteria: {{details.acceptance_criteria}}

You MUST omit any field whose value is unspecified or missing. You MUST render list-valued fields as bullet sub-lists. You MUST output the rendered issues as text, then present the confirmation gate with the AskUserQuestion tool.

The AskUserQuestion structure adapts to the number of issues.

If 1 issue:

{
  "question": "Review the issue above. Confirm to proceed with analysis. To correct any inaccurate text, select \"Type something.\" and describe what needs to be fixed.",
  "header": "Confirm",
  "multiSelect": false,
  "options": [
    {
      "label": "Confirm",
      "description": "The description is accurate. Proceed to analyze this issue."
    },
    {
      "label": "Skip",
      "description": "Do not analyze this issue."
    }
  ]
}

• "Confirm" → set $TARGET_ISSUES to the issue ID. Proceed to 4.2.
• "Skip" → set $TARGET_ISSUES to empty. Proceed to 4.2.
• "Type something." → the user typed corrections. Apply corrections (see Handling Corrections below), then re-present.

If 2 issues:

{
  "question": "Review the issues above. Select which issues to analyze. To correct any inaccurate text, select \"Type something.\" and describe what needs to be fixed.",
  "header": "Confirm",
  "multiSelect": true,
  "options": [
    {
      "label": "{{issues[0].id}} ({{issues[0].type}}, {{issues[0].severity}})",
      "description": "{{issues[0].description}}\n{{one_key_detail}}"
    },
    {
      "label": "{{issues[1].id}} ({{issues[1].type}}, {{issues[1].severity}})",
      "description": "{{issues[1].description}}\n{{one_key_detail}}"
    }
  ]
}

• User selects issues → set $TARGET_ISSUES to the selected issue IDs. Proceed to 4.2.
• "Type something." → corrections. Apply corrections, then re-present.

If 3 issues:

{
  "question": "Review the issues above. Select which issues to analyze. To correct any inaccurate text, select \"Type something.\" and describe what needs to be fixed.",
  "header": "Confirm",
  "multiSelect": true,
  "options": [
    {
      "label": "{{issues[0].id}} ({{issues[0].type}}, {{issues[0].severity}})",
      "description": "{{issues[0].description}}\n{{one_key_detail}}"
    },
    {
      "label": "{{issues[1].id}} ({{issues[1].type}}, {{issues[1].severity}})",
      "description": "{{issues[1].description}}\n{{one_key_detail}}"
    },
    {
      "label": "{{issues[2].id}} ({{issues[2].type}}, {{issues[2].severity}})",
      "description": "{{issues[2].description}}\n{{one_key_detail}}"
    }
  ]
}

3 options + auto "Type something." = 4 (the maximum). Same pattern as 2 issues.

If 4 and 4+ issues:

{
  "question": "Review the issues above. Choose how to proceed. To correct any inaccurate text, select \"Type something.\" and describe what needs to be fixed.",
  "header": "Confirm",
  "multiSelect": false,
  "options": [
    {
      "label": "Analyze all",
      "description": "All descriptions are accurate. Analyze every issue."
    },
    {
      "label": "Chat to select",
      "description": "I'd like to discuss which issues to analyze."
    }
  ]
}

• "Analyze all" → set $TARGET_ISSUES to all issue IDs. Proceed to 4.2.
• "Chat to select" → drop into regular conversation. The user specifies which issues to analyze in their own words. Set $TARGET_ISSUES from the user's response. Proceed to 4.2.
• "Type something." → corrections. Apply corrections, then re-present.

Where one_key_detail is:

• Bug: "Expected: {{details.expected_result}}" (or "Actual: {{details.actual_result}}" if expected is unspecified)
• Improvement: "Suggestion: {{details.suggested_improvement}}"
• Feature: "Story: {{details.user_story}}"

Handling Corrections:

When the user selects "Type something." and types corrections:

1. Spawn a subagent to apply the corrections:

Agent(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Apply user corrections to user_observations.json",
  background: false,
  prompt: """
  The user corrected the following in their extracted issues:

  {{for each correction}}
  - Issue {{issue_id}}: {{what the user wants changed}}
  {{end for}}

  Update user_observations.json at {{$ANALYSIS_SESSION_PATH}}/user_observations.json:
  1. Apply the corrections to the specified issue(s).
  2. Only modify these fields: severity, short_description, description, focus_elements, details.*.
  3. Do NOT modify: id, discourse_id, type, is_input_event_triggered, temporal_nature, raw_user_quotes, intervals, round_2_intervals.
  """
)

1. Wait for the subagent to complete. Do NOT use sleep or poll.
2. Re-read {{$ANALYSIS_SESSION_PATH}}/user_observations.json, re-render all issues, and present the confirmation gate again (same structure adapted to issue count).
3. In the re-presentation, process the user's response as a confirmation only — do not apply further corrections.

You MUST identify if the user's text field response contains issue analysis. If it does, set it to $USER_ANALYSIS.

4.2. Resolve Extraction-Level Ambiguities

Check user_observations.json for:

1. Per-issue ambiguities arrays (non-empty)
2. Top-level unattached_ambiguities array (non-empty)

If no ambiguities exist, proceed to Step 5.

For each ambiguity, present it using AskUserQuestion. Ask one question per message.

The orchestrator formulates the question from the structured ambiguity data:

{
  "question": "Regarding {{ambiguity.subject}}:\n\nYou said:\n{{ambiguity.relevant_quotes, each on its own line, quoted}}\n\n{{ambiguity.tension}}\n\nWhich interpretation is correct?",
  "header": "Clarification",
  "multiSelect": false,
  "options": [
    // **MUST:**
    // - You **MUST** ask yourself if the options suffice the following requirements. If they not, redsign it.
    //   - The options **CAN** resolve the ambiguity.
    //   - The options **MUST** be grounded in best practices for the relevant domain and workflow, while also accounting for the surrounding operational context and the appropriate time horizon for the decision.
    //   - The options **MUST** describe the outcome from the user's perspective.
    // - You **MUST** provide a free-text option (the "Type something." option) for each question so the user can provide a custom response.
    // - You **MUST** frame each question with:
    //   - The analysis findings.
    //   - The remaining ambiguity.
    //   - The design implications of each option.
    // - You **MUST** ensure each option resolves only the ambiguity being asked about.
    //
    // **MUST NOT:**
    // - You **MUST NOT** describe options in technical languages **UNLESS** you can identity the user has relevant technical background (programming language, framework, tech stack) in user observations.
    // - You **MUST NOT** include conclusions about aspects the user already specified or aspects outside the ambiguity's scope in an option's description.
  ]
}

Questions Presentation Rules:

MUST:

• You MUST resolve the dependencies of all the questions, grouping them into batches, asking one batch in a single message.
• Each option's description MUST describe a user-visible outcome — what the user sees, hears, or experiences. If a direction must be named, describe it as a behavior from the user's perspective, not as a technique from the implementer's perspective.
• You MUST pireview options with ASCII diagrams (markdown) whenever the content is inherently structural—such as flows, hierarchies, decision trees, state transitions, spatial layouts, or side-by-side comparisons—and would lose clarity if described only in prose.

MUST NOT:

• You MUST NOT present the option preview in question.
• You MUST NOT present options in the question field.
• Each option's description MUST NOT contain:
• Specific numeric values, durations, thresholds, or units when those values did not appear in the user's input or in an analyzer artifact.
• Identifiers from the target codebase (type names, enum cases, function or method names, parameter names, file paths).
• Technique labels that pre-commit to an implementation approach.
• Exception: a specific value or identifier MAY appear in an option's description if it is quoted verbatim from a file under {{$ANALYSIS_SESSION_PATH}}/issues/*/ produced by the issue-analyzer. When this exception is used, cite the artifact path inline.

After resolving all ambiguities, spawn a subagent to apply the clarifications.

Agent(
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Apply ambiguity clarifications to user_observations.json",
  background: false,
  prompt: """
  The developer clarified the following ambiguities:

  {{for each resolved ambiguity}}
  - {{ambiguity.subject}}: {{user's answer}}
  {{end for}}

  Update user_observations.json at {{$ANALYSIS_SESSION_PATH}}/user_observations.json:
  1. Update each issue's `details` field to reflect the resolved interpretation.
  2. Remove the resolved ambiguities from each issue's `ambiguities` array.
  """
)

Inform the user: "I've spawned a subagent to update user_observations.json with your clarifications. I'll continue once it finishes."

Wait for the subagent to complete. You will be automatically notified when it finishes. Do NOT use sleep or poll — the notification arrives on its own.

Record each resolution in a $EXTRACTION_CLARIFICATIONS array following this schema:

[
  {
    "issue_id": "ISS-XXX or null",
    "subject": "[ambiguity subject]",
    "question": "[the question asked]",
    "answer": "[the user's answer]",
    "design_constraint": "[one-sentence actionable constraint derived from the answer]"
  }
]

After all ambiguities are resolved, proceed to Step 5.

MANDATORY: Step 5. Evidence Witness

Step 5.1. Read Pre-Computed Intervals

For each issue ID in $TARGET_ISSUES:

1. Read the issue entry from {{$ANALYSIS_SESSION_PATH}}/user_observations.json.
2. If issue.focus_elements is empty (pure non-visual symptom), skip to Step 5.4 for that issue — no witnesses, no aggregation.
3. Each entry of issue.focus_elements is an object {element, observable} — forward the whole list verbatim to the spawn record; the witness's narration table will have one column per pair.
4. Read the issue's intervals array. Each entry is one spawn record:

```json {"id": "E-NNN", "witnesstag": "E-NNN", "startsec": [number: startsec], "endsec": [number: endsec], "startns": [number: startns], "endns": [number: endns], "source": "eventtriggered|speech_triggered", "i

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: readycheck-dev
• Source: readycheck-dev/skills
• License: Apache-2.0
• Homepage: https://readycheck.dev

Install and usage instructions live in the source repository linked above.