How do I install the Bug Session skill?

Run npx skillmds@latest add garyld1962/bug-session in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Bug Session safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Bug Session?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Bug Session free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Bug Session?

garyld1962 (@garyld1962) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Bug Session by garyld1962 — Agent Skill

Name: Bug Session
Author: garyld1962

Bug Session

Interactive bug-reporting session: user describes problems conversationally, agent explores the codebase for domain context, and files durable GitHub issues. Use when user wants to report bugs, do QA testing, capture defects — phrases like 'let's do a bug session', 'I found some issues', 'QA session', 'help me file these bugs'. When NOT to Use: single known bug to investigate (use /triage); existing issue to fix (use /hotfix or /execute-prd).

garyld1962 e5680ca 3.0 KB Updated Sep 17, 2026

File contents

/bug-session -- Conversational Bug Capture

Purpose: Run an interactive session where the user describes bugs in plain language. For each issue, ask minimal clarifying questions, explore the codebase in the background for domain context, then file a durable GitHub issue. Issues are written to survive refactors — no file paths, no internal module names.

When to Use

User wants to report multiple bugs they've found
Running QA on a feature before shipping
Capturing defects from manual testing
Handing off bugs from user testing into GitHub

When NOT to Use

One known bug that needs investigation — use /triage
Already have a GitHub issue and need to fix it — use /hotfix or /execute-prd

Per-Issue Workflow

1. Listen

Let the user describe the problem in their own words. Don't interrupt or ask anything yet.

2. Clarify (max 2-3 questions)

Ask only what's needed to file a good issue:

What did you expect vs what actually happened?
Steps to reproduce, if not obvious
Consistent or intermittent?

If the description is clear enough to file, skip the questions and move on.

3. Explore in Background

While talking, spawn an Explore sub-agent to:

Read UBIQUITOUS_LANGUAGE.md if it exists
Find the feature area in the codebase
Learn the domain terms used there

Goal: Write a better issue — not find a fix. The filed issue must NOT reference specific files, line numbers, or internal module names. Those rot after the next refactor.

4. Single Issue or Breakdown?

Decide before filing.

Break down when:

The fix spans multiple independent areas
Different people could reasonably work on separate parts
There are distinct failure modes with different root causes

Keep single when:

One behavior is wrong in one place
All symptoms trace to the same root cause

When breaking down: create issues in dependency order (blockers first) so you can reference real issue numbers.

5. File the Issue

Use gh issue create. Don't ask the user to review first — file and share the URL.

## What happened
[Actual behavior the user experienced, plain language]

## What I expected
[Expected behavior]

## Steps to reproduce
1. [Concrete numbered steps]
2. [Use domain terms, not internal module names]
3. [Include relevant inputs, flags, or config]

## Additional context
[Observations that help frame it — domain language only, no file paths]

Session Flow

Repeat the per-issue workflow until the user says they're done. At the end, share all filed issue URLs as a list.

---name: bug-sessiondescription: Interactive bug-reporting session: user describes problems conversationally, agent explores the codebase for domain context, and files durable GitHub issues. Use when user wants to report bugs, do QA testing, capture defects — phrases like 'let's do a bug session', 'I found some issues', 'QA session', 'help me file these bugs'. When NOT to Use: single known bug to investigate (use /triage); existing issue to fix (use /hotfix or /execute-prd).---# /bug-session -- Conversational Bug Capture**Purpose:** Run an interactive session where the user describes bugs in plain language. For each issue, ask minimal clarifying questions, explore the codebase in the background for domain context, then file a durable GitHub issue. Issues are written to survive refactors — no file paths, no internal module names.## When to Use- User wants to report multiple bugs they've found- Running QA on a feature before shipping- Capturing defects from manual testing- Handing off bugs from user testing into GitHub## When NOT to Use- One known bug that needs investigation — use `/triage`- Already have a GitHub issue and need to fix it — use `/hotfix` or `/execute-prd`## Per-Issue Workflow### 1. ListenLet the user describe the problem in their own words. Don't interrupt or ask anything yet.### 2. Clarify (max 2-3 questions)Ask only what's needed to file a good issue:- What did you expect vs what actually happened?- Steps to reproduce, if not obvious- Consistent or intermittent?If the description is clear enough to file, skip the questions and move on.### 3. Explore in BackgroundWhile talking, spawn an Explore sub-agent to:- Read `UBIQUITOUS_LANGUAGE.md` if it exists- Find the feature area in the codebase- Learn the domain terms used there**Goal:** Write a better issue — not find a fix. The filed issue must NOT reference specific files, line numbers, or internal module names. Those rot after the next refactor.### 4. Single Issue or Breakdown?Decide before filing.**Break down** when:- The fix spans multiple independent areas- Different people could reasonably work on separate parts- There are distinct failure modes with different root causes**Keep single** when:- One behavior is wrong in one place- All symptoms trace to the same root causeWhen breaking down: create issues in dependency order (blockers first) so you can reference real issue numbers.### 5. File the IssueUse `gh issue create`. Don't ask the user to review first — file and share the URL.```markdown## What happened[Actual behavior the user experienced, plain language]## What I expected[Expected behavior]## Steps to reproduce1. [Concrete numbered steps]2. [Use domain terms, not internal module names]3. [Include relevant inputs, flags, or config]## Additional context[Observations that help frame it — domain language only, no file paths]```## Session FlowRepeat the per-issue workflow until the user says they're done. At the end, share all filed issue URLs as a list.

Frequently asked questions