Troubleshooting

Hooks never engage on a fresh clone

Cause: The v0.48.3 hook activation guard requires both silver-bullet.md and .silver-bullet.json. Cloning a repo without running init leaves enforcement inactive by design.

Fix: Run /silver:init in the project root. Re-run bash scripts/sb-diagnostics.sh and confirm tier 2 (hook-enforced) on Cursor/Codex/Claude when hooks are merged.

Cursor hooks not merged

Cause: ~/.cursor/hooks.json does not include SB entries, or install used an old checkout path.

Fix: Run bash scripts/install-cursor.sh --public-release, then bash scripts/sb-diagnostics.sh. Expect tier 2 (hook-enforced) when hooks are present.

Low capability tier (guidance-only)

Cause: Host session lacks hook delivery (tier 0) or skill markers are not recording (tier 1).

Fix: Install from the public marketplace for your host, run /silver:init, and use explicit /silver or Skill-tool invocation so record-skill can write state.

"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 ${SB_RUNTIME_HOME_ROOT}/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 ${SB_RUNTIME_HOME_ROOT}/.silver-bullet/state may be stale from a previous session.

Fix: Delete the state file: rm ${SB_RUNTIME_HOME_ROOT}/.silver-bullet/state. It will be recreated on the next skill invocation.

"External review helper requested"

Cause: An explicit external review-helper request was made, or an older project still references an obsolete helper name.

Fix: Use the Silver Bullet equivalent (silver:review-request, silver:review-triage, silver:completion-audit, silver:branch-finish, or tdd) unless you explicitly want supplemental external tooling.

"Engineering plugin not found"

Cause: An explicit external Engineering plugin request was made, or an older workflow still references old knowledge-work skill names.

Fix: Use quality gates for docs, testing, release, and DevOps readiness unless you explicitly want the external plugin as supplemental tooling.

"Design plugin not found"

Cause: An explicit external Design plugin request was made, or an older workflow still references old design helper names.

Fix: Use silver:ui-contract, silver:ui-review, and review-design for UI/design checks unless you explicitly want supplemental external design review.

"Legacy Product Management command requested"

Cause: An explicit external product-management request was made, or an older workflow still references old PM helper names.

Fix: Use silver:clarify, silver:spec, and silver:deep-research for product framing and research synthesis unless you explicitly want supplemental external PM tooling.

"External lifecycle command not found"

Cause: An explicit external lifecycle command was requested, or an older project still has direct references to retired helper commands.

Fix: Route ordinary lifecycle work through /silver or lifecycle skills. Install supplemental tooling only when the selected workflow explicitly needs it.

"Graphify is not installed"

Cause: Silver Bullet uses Graphify for project-memory retrieval before planning, editing, debugging, review, and shipping.

Fix: Install it with uv tool install graphifyy or python3.12 -m pip install graphifyy, then rerun /silver:init. See Graphify Retrieval for query and fallback behavior.

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 /silver: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 ask /silver for current status or inspect .planning/workflows/ and .planning/STATE.md. Then use /silver:forensics for session/workflow reconstruction if the interruption left unclear state.

Verification failed and I'm stuck in a loop

Cause: /silver:verify failed and the workflow is retrying execute + verify repeatedly.

Fix: Invoke /silver:forensics for session/workflow failures or /silver:debug for an active reproducible bug to identify the root cause. If the root cause is in the plan or design, return to /silver:context or /silver:plan 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: Use /silver:forensics to diagnose the current state. If unrecoverable, restore or archive the bad phase-specific files and re-run the phase from /silver:context and /silver:plan.

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:update or re-run /silver:init to refresh config to v0.48.3. For catalog drift, regenerate views with python3 scripts/generate-apo-artifacts.py in the SB repo and verify docs/apo-catalog.json is the source of truth — use AF-*/WF-* IDs, not legacy FLOW names, in new workflow docs.

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 SB skill explicitly, or ask /silver for the next required workflow 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.

"silver:branch-finish blocked on main"

Cause: /silver:branch-finish 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 lightweight work, Tier 2 bounded work, 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.