arn-code-bug-spec

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 Task tool, passing the model from .arness/agent-models/code.md as the model parameter (see plugins/arn-code/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 Task tool, passing the model from .arness/agent-models/code.md as the model parameter (see plugins/arn-code/skills/arn-code-ensure-config/references/ensure-config.md "Dispatch convention" for fallback). Context:

Feature idea: The investigator's findings -- root cause, scope assessment, and proposed fix direction.

Codebase context: The stored architecture documentation (architecture.md, code-patterns.md, and ui-patterns.md if present).

Specific question: "Does this proposed fix direction align with the system architecture? Is it a proper fix or a workaround/hack? Are there architectural concerns or better approaches?"

Present the combined results to the user, highlighting:

1. Root cause (or top hypothesis) -- from the investigator
2. Evidence (file paths and line numbers) -- from the investigator
3. Scope assessment -- from the investigator
4. Test coverage gaps -- from the investigator
5. Architectural assessment -- from the architect: does the fix align with system design, any concerns, recommended approach
6. Open questions -- from both the investigator and the architect

Then ask: "Does this match what you're seeing? Any additional context or leads?"

Step 4: Diagnosis Phase (Iterative)

Iterate with the user in a conversation loop: listen for confirmations, corrections, or new symptoms, then invoke arn-code-investigator or arn-code-architect as appropriate. Summarize the current state after each exchange and check for convergence (root cause confirmed + architect validated). When converged, proceed to Step 5.

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-bug-spec/references/diagnosis-flow.md for the full diagnosis and fix procedure.

Step 5: Complexity Assessment (Internal)

Internally assess whether the fix is simple or complex based on the architect's validation and six complexity questions (file count, architectural changes, pattern repetition, dependencies, description length, test work). Route to Step 6A for simple fixes or Step 6B for complex ones.

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-bug-spec/references/diagnosis-flow.md for the full diagnosis and fix procedure.

Step 6A: Simple Fix Path

Present the fix proposal with specific files and test plan, offer the user a choice between writing a small plan first or fixing directly, create a task list, and execute either in-session or via arn-code-bug-fixer. The bug fix report is written to <project-folder>/reports/BUGFIX_REPORT.json.

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-bug-spec/references/diagnosis-flow.md for the full diagnosis and fix procedure.

Step 6B: Complex Fix Path — Write Bug Specification

1. Inform the user: "This fix is complex enough to benefit from a structured plan. Let me capture the investigation results in a specification."

1. Invoke t