/arn-code-bug-spec

name: arn-code-bug-spec
description: >-
  This skill should be used when the user says "bug spec", "arness code bug spec",
  "investigate this bug", "help me debug", "trace this bug", "diagnose this
  issue", "I found a bug", "something is broken", "why is X not working",
  "fix this bug", "debug this", "why is this not working",
  or wants to iteratively investigate a bug through guided conversation
  with diagnostic analysis. Bridges the gap between a bug report and either
  a direct fix or a structured bug specification for the Arness pipeline.
version: 1.0.0

Arness Bug Spec

Investigate a bug through iterative conversation, aided by diagnostic analysis from the `arn-code-investigator` agent, architectural validation from the `arn-code-architect` agent, and optional automated fix execution from the `arn-code-bug-fixer` agent. Every bug investigation gets its own project folder (`BUGFIX_<name>/`) in the plans directory. For simple bugs, the artifact is a fix plus a bug fix report. For complex bugs, the artifact is a **bug specification** written to `.arness/specs/` that informs plan creation via the `/arn-code-plan` skill.

This is a conversational skill. It runs in normal conversation (NOT plan mode). A `BUGFIX_<name>/` project folder is created at the start of every investigation. For simple bugs, the folder holds the fix report. For complex bugs, a specification document is written to `<specs-dir>/BUGFIX_<name>.md`, and the project folder is used later by `arn-code-save-plan` after the plan is generated via `/arn-code-plan`.

Step 0: Ensure Configuration

Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md` and follow its instructions. This guarantees a user profile exists and `## Arness` is configured with Arness Code fields before proceeding.

Workflow

Step 1: Capture the Bug Report

Accept the user's bug description. This can be anything from "X is broken" to a detailed report with stack traces, error messages, and reproduction steps. Do not require a specific format.

If the user already provided the bug description in their trigger message (e.g., "bug spec: users are getting 500 errors on checkout"), use that directly without asking again.

Acknowledge the report with a brief restatement to confirm understanding. Ask targeted follow-up questions ONLY if critical information is missing:

• What is expected vs actual behavior?
• Any error messages or stack traces?
• When did it start? (recent change, always broken, intermittent)

Do NOT require answers to all of these. Work with what is available and proceed.

Establish Project Folder

Once the bug is understood, create a project folder for the investigation:

1. Auto-generate a project name from the bug description (e.g., `BUGFIX_checkout-500-errors`, `BUGFIX_stale-cache-after-update`). 2. Suggest it to the user: "I'll create a bug investigation project called `BUGFIX_<name>`. Good?" 3. Once confirmed, read the `## Arness` section from CLAUDE.md to get the plans directory path, then create the project folder:

mkdir -p <plans-dir>/BUGFIX_<name>/reports

This folder is the home for all artifacts produced during this investigation. Hold the project path (`<project-folder>`) for use throughout the workflow.

---

Step 2: Load Codebase Context

Read the project's CLAUDE.md and extract the `## Arness` section to find:

• Code patterns path
• Specs directory
• Template path
• Template version (if present)
• Template updates preference (if present)

**Template version check:** If `Template version` and `Template updates` fields are present, run the template version check procedure documented in `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-save-plan/references/template-versioning.md` before proceeding. If `## Arness` does not contain these fields, treat as legacy and skip.

Read the stored pattern documentation:

• `<code-patterns-dir>/code-patterns.md`
• `<code-patterns-dir>/testing-patterns.md`
• `<code-patterns-dir>/architecture.md`
• `<code-patterns-dir>/ui-patterns.md` (if it exists)

**If pattern documentation files are missing** (no `code-patterns.md`, `testing-patterns.md`, or `architecture.md` in the Code patterns directory):

Inform the user: "This is the first time pattern documentation is being generated for this project. Analyzing your codebase to understand its patterns, conventions, and architecture. This is a one-time operation — future invocations will use the cached results."

Then invoke the `arn-code-codebase-analyzer` agent (existing codebase) or `arn-code-pattern-architect` (greenfield) to generate fresh analysis. Write the results to the Code patterns directory. Summarize the key findings relevant to the bug.

Hold this context for use throughout the conversation. Do not dump all of it on the user -- reference specific parts when relevant.

---

Step 3: Initial Investigation + Architectural Validation

Invoke the `arn-code-investigator` agent via the Agent tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:

**Bug description:** The user's report from Step 1.

**Codebase context:** The full content of the stored pattern documentation files loaded in Step 2 (code-patterns.md, testing-patterns.md, architecture.md, and ui-patterns.md if present). If these were not available and `arn-code-codebase-analyzer` was used instead, pass that output.

**Specific hypothesis:** None for the initial invocation.

Once the investigator returns with a root cause and proposed fix direction, invoke the `arn-code-architect` agent via the Agent tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:

**Feature idea:** The investigator's fin