Troubleshooting

"jq: command not found"

Cause: The jq JSON processor is not installed. Most hooks use jq to read .silver-bullet.json.

Fix: Install jq: brew install jq (macOS) or apt install jq (Linux).

"Permission denied" on hook scripts

Cause: Hook shell scripts lost their executable permission, often after a git clone on certain filesystems.

Fix: Run chmod +x hooks/*.sh hooks/session-start from the plugin cache directory (usually ~/.claude/plugins/cache/alo-exp/silver-bullet/hooks/).

Hooks not firing at all

Cause: Silver Bullet was not initialized in this project, or .silver-bullet.json is missing from the project root.

Fix: Run /silver:init in your project. This creates the config file and activates enforcement.

Compliance status shows wrong progress

Cause: The state file at ~/.claude/.silver-bullet/state may be stale from a previous session.

Fix: Delete the state file: rm ~/.claude/.silver-bullet/state. It will be recreated on the next skill invocation.

"Superpowers plugin not found"

Cause: The Superpowers plugin is not installed. Silver Bullet requires it for selected helper gates such as review framing/triage, TDD discipline, verification-before-completion, and branch finishing.

Fix: Run /plugin install obra/superpowers in your host coding agent.

"Engineering plugin not found"

Cause: The Engineering plugin provides /testing-strategy, /tech-debt, /documentation, /deploy-checklist, and related engineering support skills.

Fix: Run /plugin install anthropics/knowledge-work-plugins/tree/main/engineering.

"Design plugin not found"

Cause: The Design plugin provides /design-system, /ux-copy, /accessibility-review, and design critique support for UI work.

Fix: Run /plugin install anthropics/knowledge-work-plugins/tree/main/design.

"GSD plugin not found"

Cause: GSD (Get Shit Done) is the primary execution engine. Without it, no workflow commands work.

Fix: Run npx get-shit-done-cc@latest to install GSD.

CI check blocks push but CI is actually green

Cause: The hook checks GitHub Actions via gh run list. If gh is not authenticated or not installed, the check may fail.

Fix: Ensure GitHub CLI is installed (brew install gh) and authenticated (gh auth login). On macOS, use /opt/homebrew/bin/gh if the bare gh command fails.

CI is red and Silver Bullet won't let me proceed

Cause: This is intentional. The CI gate emits a hard stop (decision: "block") when CI is failing.

Fix: Fix the CI failure first. Use /gsd:debug for active bugs or inspect the failing GitHub Actions job. Commits for CI fixes are allowed; PR/deploy/release gates remain blocked until CI is green.

No CI workflow exists yet

Cause: The project does not have a .github/workflows/ci.yml file. The CI hook gracefully skips when no CI is configured.

Fix: Run /silver:init which auto-generates a CI workflow based on your tech stack (Node, Python, Go, Rust, and 8 more).

Session timed out or was interrupted

Cause: Context window exhaustion, network interruption, or the autonomous mode timeout sentinel fired.

Fix: Start a new session and run /gsd:next to find where you left off. GSD tracks progress in .planning/ files that persist across sessions. Then use /silver:forensics for session/workflow reconstruction if the interruption left unclear state.

Verification failed and I'm stuck in a loop

Cause: /gsd:verify-work failed and the workflow is retrying steps 6-7 (execute + verify) repeatedly.

Fix: Invoke /silver:forensics for session/workflow failures or /gsd:debug for an active reproducible bug to identify the root cause. If the root cause is in the plan or design (not implementation), return to step 3 (discuss) rather than re-executing.

.planning/ directory is corrupted or missing files

Cause: Manual edits to planning files, or a merge conflict left files in a bad state.

Fix: Run /gsd:next to diagnose the current state. If unrecoverable, delete the phase-specific files (e.g., .planning/phase-1-PLAN.md) and re-run the phase from /gsd:discuss-phase.

Wrong files triggering enforcement

Cause: The src_pattern in .silver-bullet.json does not match your project structure. Default is /src/.

Fix: Edit .silver-bullet.json and change src_pattern to match your source directory (e.g., /app/, /lib/, /packages/).

Test files triggering enforcement

Cause: The src_exclude_pattern does not match your test file naming convention.

Fix: Edit .silver-bullet.json and update src_exclude_pattern. Default is __tests__|\.test\.. Add your patterns with pipe separators (e.g., __tests__|\.test\.|\.spec\.).

Config is outdated (old skill names, wrong version)

Cause: The .silver-bullet.json was created by an older version and has not been regenerated.

Fix: Run /silver:init and choose to refresh the config. It will preserve your project-specific values while updating the schema and skill lists.

Project instruction file conflicts with project instructions

Cause: Silver Bullet's host project instruction file may override or conflict with your existing project instructions.

Fix: During /silver:init setup, choose Append mode for existing projects. This adds Silver Bullet rules below your existing instructions. Both sets of rules will be active.

"HARD STOP — Planning incomplete"

Cause: You are editing source files before completing quality gates. The stage enforcer hook blocks this.

Fix: Run /silver:quality-gates for software work, or /silver:blast-radius plus /devops-quality-gates for DevOps/IaC work before editing source code.

"COMPLETION BLOCKED — Workflow incomplete"

Cause: You are trying to create a PR, deploy, or create a release before completing all required workflow steps.

Fix: Check which steps are missing from the error output. Run each missing skill explicitly. Use /gsd:next to find the next required step.

Note on commits vs releases: Enforcement uses two tiers. git commit and git push only require quality gates to have run. gh pr create, deploys, and releases require the full required skill list. If commits work but release is blocked, that's expected — you haven't completed the full workflow yet.

"finishing-a-development-branch blocked on main"

Cause: /finishing-a-development-branch is designed for feature branches. It has no meaningful work to do on main/master.

Fix: This step is automatically skipped when you're on main or master. If enforcement is still blocking, verify your branch name with git branch --show-current.

Compliance status shows wrong progress after switching branches

Cause: The session state file is branch-scoped and resets when you switch branches. Skills recorded on the previous branch don't carry over.

Fix: This is expected behaviour — each branch tracks its own workflow progress independently. Start a new session on the new branch and run the required skills for that branch's work.

Using the fast path for small changes

Cause: You need to make a small or bounded fix without running the full composed workflow.

Fix: Route the change through /silver:fast so SB can classify it as Tier 1 (gsd:fast), Tier 2 (gsd:quick with flags), or Tier 3 escalation to silver:feature. Note: In devops-cycle mode, .yml/.yaml/.json/.toml files are still treated as infrastructure code and must go through the DevOps workflow.