Skill

ship-bug

Report a bug or production issue with minimal ceremony. Creates a spec entry and optional fix task. Use when the user reports something broken, a defect, unexpected behavior, a regression, or needs to file a hotfix for production. Also use for --hotfix emergency production issues.

Install

npx claudepluginhub acendas/shipyard --plugin shipyard

Tool Access

This skill is limited to using the following tools:

ReadWriteEditGrepGlobAskUserQuestionBash(shipyard-context:*)

Preview

Create a minimal bug report. The spec already describes correct behavior — bugs are deviations from it.

SKILL.md

Similar Skills

skill-lookup

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.

prompts.chat

159.9k

prompt-lookup

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.

prompts.chat

159.9k

using-git-worktrees

Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.

superpowers

158.9k

Stats

Parent Repo Stars0

Parent Repo Forks0

Last CommitApr 15, 2026

Actions

View Source View Plugin View on GitHub View README

Shipyard: Report Bug

Create a minimal bug report. The spec already describes correct behavior — bugs are deviations from it.

Context

!shipyard-context path

!shipyard-context count-of bugs !shipyard-context view sprint 10

Paths. All file ops use the absolute SHIPYARD_DATA prefix from the context block. No ~, $HOME, or shell variables in file_path. No bash invocation of shipyard-data or shipyard-context — use Read / Grep / Glob. Never use echo/printf/shell redirects to write state files — use the Write tool (auto-approved for SHIPYARD_DATA).

Input

$ARGUMENTS

Detect Mode

No input → AskUserQuestion: "What's broken? Describe the bug you're seeing."
If input contains --hotfix → HOTFIX mode (production emergency)
Otherwise → NORMAL mode

NORMAL Mode

Generate ID — Next available BNNN (B001, B002, etc.)
Try to match feature — Search spec features for the area this bug relates to. If ambiguous with multiple plausible matches, use AskUserQuestion: "Which feature does this bug relate to?" Otherwise, best-guess the match and note it.
Create bug file — use the Write tool with the literal path <SHIPYARD_DATA>/spec/bugs/BNNN-[slug].md (substitute SHIPYARD_DATA from the context block):

---
id: BNNN
title: "[title]"
type: bug
feature: [matched feature ID or "unknown"]
task: ""
severity: [infer from description: critical|high|medium|low]
hotfix: false
status: open
found_during: [current sprint ID or "manual report"]
created: [today]
---

# [Title]

## Bug
[Description from user]

## Steps to Reproduce
[Infer from description. If unclear, write "To be determined" — don't ask, keep it fast]

## Expected (from spec)
[Pull from the matched feature's acceptance criteria if possible]

## Actual
[What the user described happening]

Confirm:

✓ Bug reported: BNNN — [title] (severity: [level])
  Feature: [ID] — [feature title]
  Fix options:
    - Urgent: /ship-bug --hotfix [description] to re-file as hotfix, then /ship-execute --hotfix B-HOT-NNN
    - Sprint fix: create a fix task in the current sprint
    - Backlog: defer to next sprint planning

HOTFIX Mode

Generate ID — B-HOT-NNN format
Create bug file with severity: critical and hotfix: true in frontmatter
Auto-start debug session — use the Write tool to create <SHIPYARD_DATA>/debug/B-HOT-NNN.md (literal path from context block) with symptoms from the bug report. This ensures systematic investigation instead of guessing at fixes.
Confirm with urgency:

🚨 HOTFIX: B-HOT-NNN — [title]
  Debug session started: <SHIPYARD_DATA>/debug/B-HOT-NNN.md
  Investigating now — /ship-debug --resume to continue if interrupted

Then immediately begin the debug investigation (Step 3 of ship-debug: form hypothesis → test → record → repeat). When root cause is found, fix with TDD (regression test first), commit as fix(B-HOT-NNN): [description].

Capture the repro. When running the repro command during investigation, wrap it: shipyard-logcap run bhot-NNN-repro --max-size <S> --max-files <N> -- <command>. Bug repros are often flaky — the captured file lets you re-inspect a different signal without re-triggering the bug, which is the most expensive part of debugging. If the first repro run shows something unexpected, shipyard-logcap grep the capture with a wider pattern before you re-run. Full guide and decision table for bounds: ${CLAUDE_PLUGIN_ROOT}/skills/ship-execute/references/live-capture.md.

Rules

Be fast. Bug reporting should take seconds.
Infer severity from keywords: "broken", "can't", "crash" → high/critical. "Wrong color", "typo" → low.
Don't ask unnecessary questions. Capture what you have, refine later.
Link to spec — if you find the related feature, pull its acceptance criteria as the "Expected" section.

Next Up (after bug filed)

Suggest the right path based on severity:

For critical/hotfix bugs:

▶ NEXT UP: Fix it now (bypasses sprint planning)
  /ship-execute --hotfix B-HOT-NNN
  (tip: /clear first for a fresh context window)

For high severity bugs in an active sprint:

▶ NEXT UP: Add to the current sprint
  /ship-execute (the bug will be picked up as a patch task)
  (tip: /clear first for a fresh context window)

For medium/low severity bugs:

▶ NEXT UP: Plan the fix in the next sprint
  /ship-sprint (the bug will show up as a candidate)
  (tip: /clear first for a fresh context window)