playbooks

home / skills / dyad-sh / dyad / session-debug

session-debug skill

/.claude/skills/session-debug

This skill analyzes session debugging data to identify errors and issues causing user-reported problems, offering actionable insights and prioritized fixes.

npx playbooks add skill dyad-sh/dyad --skill session-debug

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.9 KB
---
name: dyad:session-debug
description: Analyze session debugging data to identify errors and issues that may have caused a user-reported problem.
---

# Session Debug

Analyze session debugging data to identify errors and issues that may have caused a user-reported problem.

## Arguments

- `$ARGUMENTS`: Two space-separated arguments expected:
  1. URL to a JSON file containing session debugging data (starts with `http://` or `https://`)
  2. GitHub issue number or URL

## Instructions

1. **Parse and validate the arguments:**

   Split `$ARGUMENTS` on whitespace to get exactly two arguments:
   - First argument: session data URL (must start with `http://` or `https://`)
   - Second argument: GitHub issue identifier (number like `123` or full URL like `https://github.com/owner/repo/issues/123`)

   **Validation:** If fewer than two arguments are provided, inform the user:

   > "Usage: /dyad:session-debug <session-data-url> <issue-number-or-url>"
   > "Example: /dyad:session-debug https://example.com/session.json 123"

   Then stop execution.

2. **Fetch the GitHub issue:**

   ```
   gh issue view <issue-number> --json title,body,comments,labels
   ```

   Understand:
   - What problem the user is reporting
   - Steps to reproduce (if provided)
   - Expected vs actual behavior
   - Any error messages the user mentioned

3. **Fetch the session debugging data:**

   Use `WebFetch` to retrieve the JSON session data from the provided URL.

4. **Analyze the session data:**

   Look for suspicious entries including:
   - **Errors**: Any error messages, stack traces, or exception logs
   - **Warnings**: Warning-level log entries that may indicate problems
   - **Failed requests**: HTTP errors, timeout failures, connection issues
   - **Unexpected states**: Null values where data was expected, empty responses
   - **Timing anomalies**: Unusually long operations, timeouts
   - **User actions before failure**: What the user did leading up to the issue

5. **Correlate with the reported issue:**

   For each suspicious entry found, assess:
   - Does the timing match when the user reported the issue occurring?
   - Does the error message relate to the feature/area the user mentioned?
   - Could this error cause the symptoms the user described?

6. **Rank the findings:**

   Create a ranked list of potential causes, ordered by likelihood:

   ```
   ## Most Likely Causes

   ### 1. [Error/Issue Name]
   - **Evidence**: What was found in the session data
   - **Timestamp**: When it occurred
   - **Correlation**: How it relates to the reported issue
   - **Confidence**: High/Medium/Low

   ### 2. [Error/Issue Name]
   ...
   ```

7. **Provide recommendations:**

   For each high-confidence finding, suggest:
   - Where in the codebase to investigate
   - Potential root causes
   - Suggested fixes if apparent

8. **Summarize:**
   - Total errors/warnings found
   - Top 3 most likely causes
   - Recommended next steps for investigation

Overview

This skill analyzes session debugging data to identify errors and issues that may have caused a user-reported problem. It combines GitHub issue context with a fetched session JSON, surfaces suspicious events, and ranks likely causes. The goal is a concise, evidence-backed investigation that points engineers to the most promising next steps.

How this skill works

It validates two arguments: a session-data URL and a GitHub issue identifier. It fetches the issue metadata to understand the user report, then downloads the session JSON and inspects logs, errors, network requests, timings, and user actions. Findings are correlated with the issue timeline and ranked by likelihood, with concrete recommendations for code investigation and fixes.

When to use it

  • A user files a bug report and a session trace URL is available.
  • You need to triage a single-session failure to determine root cause quickly.
  • Reproductions are intermittent and you want evidence from the user's actual session.
  • You must prioritize fixes by likelihood and impact.
  • You want step-by-step correlation between reported steps and session events.

Best practices

  • Ensure the session JSON is accessible via HTTPS and contains timestamps, logs, and request/response details.
  • Include the full GitHub issue number or URL so the tool can fetch title, body, comments, and labels.
  • Provide sessions shortly after failures to preserve timing and context.
  • Enrich session logs with user actions and request IDs to improve correlation accuracy.
  • Use this analysis as a starting point; reproduce high-confidence findings in a controlled environment before deploying fixes.

Example use cases

  • A user reports a payment flow failure; analyze session traces to find network 502s or backend errors at the same timestamp.
  • Intermittent UI freezing: detect long-running operations or blocking synchronous tasks in the session logs.
  • API authorization errors: surface 401/403 responses correlated with user actions and token refresh attempts.
  • Null reference exceptions in production: locate stack traces and the exact input/state that triggered them.
  • Timeouts on third-party services: identify repeated failed requests and recommend retries or fallback logic.

FAQ

What arguments are required?

Provide two space-separated arguments: the session JSON URL (http/https) and the GitHub issue number or URL. If missing, the skill returns usage instructions.

What does the skill look for in session data?

It inspects errors, warnings, failed HTTP requests, unexpected nulls or empty responses, timing anomalies, and user actions immediately before failures.