From arn-code
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.
npx claudepluginhub appsvortex/arness --plugin arn-codeThis skill uses the workspace's default tool permissions.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
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.
Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/ensure-config.md and follow its instructions. This guarantees a user profile exists and ## Arness is configured with Arness Code fields before proceeding.
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:
Do NOT require answers to all of these. Work with what is available and proceed.
Once the bug is understood, create a project folder for the investigation:
BUGFIX_checkout-500-errors, BUGFIX_stale-cache-after-update).BUGFIX_<name>. Good?"## 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.
Read the project's CLAUDE.md and extract the ## Arness section to find:
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.
Invoke the arn-code-investigator agent with:
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 with:
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:
Then ask: "Does this match what you're seeing? Any additional context or leads?"
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.mdfor the full diagnosis and fix procedure.
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.mdfor the full diagnosis and fix procedure.
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.mdfor the full diagnosis and fix procedure.
Inform the user: "This fix is complex enough to benefit from a structured plan. Let me capture the investigation results in a specification."
Invoke the arn-code-architect agent with:
Present the architectural proposal, highlighting: fix strategy, components to change, integration points, and open questions.
Iterate with the user (same pattern as Step 4):
arn-code-architectarn-code-architect with updated contextWhen the user is ready, write the bug specification:
a. Read the bug spec template at ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-bug-spec/references/bug-spec-template.md.
b. Populate the template with:
c. Write the spec to <specs-dir>/BUGFIX_<name>.md. If the specs directory does not exist, create it: mkdir -p <specs-dir>/
Present a summary and next steps:
"Bug specification saved to <specs-dir>/BUGFIX_<name>.md.
Project folder is at <project-folder>/.
To create a fix plan, run /arn-code-plan BUGFIX_<name>.
The skill will load this spec and your project's codebase patterns, invoke the planner agent to generate a plan, and let you review and refine it before saving."
For the simple path, execution is handled in Step 6A. The task list is created and executed (either directly in the session or via arn-code-bug-fixer). No further handoff is needed.
For the complex path, after the spec is written, the user runs /arn-code-plan to generate the implementation plan. From there, the standard pipeline applies: arn-code-save-plan -> arn-code-review-plan -> arn-code-taskify -> arn-code-execute-plan.
references/agent-invocation-guide.md -- lookup table for when to invoke each agent vs. answer directlyreferences/diagnosis-flow.md -- iterative diagnosis loop, complexity assessment, and simple-fix execution flowreferences/bugfix-plan-template.md -- template for inline fix plans in the simple path (used by arn-code-planner)references/bug-spec-template.md -- template for bug specification documents (complex path)<project-folder>/) so they can delete or resume later. If only the folder skeleton was created (no report or plan yet), note that it can be safely deleted.mkdir -p <specs-dir>/