SNIPER

Appearance

Troubleshooting ​

Common issues and their solutions when working with SNIPER.

Initialization Issues ​

"SNIPER is not initialized" ​

Problem: A phase command fails with "Run /sniper-init first."

Solution: Ensure .sniper/config.yaml exists and has a non-empty project.name. Run /sniper-init if it does not exist.

Missing framework files after init ​

Problem: /sniper-init reports missing persona, team, or template files.

Solution: Framework files should come from the @sniper.ai/core package. Verify it is installed and that sniper init was run from the CLI (which scaffolds files from core). If files are missing, re-run sniper init from the CLI.

Config schema version mismatch ​

Problem: Commands warn about schema version migration.

Solution: SNIPER automatically migrates v1 configs to v2. If migration fails, check that .sniper/config.yaml is valid YAML with no syntax errors.

Agent Spawning Issues ​

Teammate not responding ​

Problem: An agent has been silent for more than 10 minutes during a phase.

Solutions:

  • The team lead automatically checks on stalled teammates after the coordination_timeout (default: 30 minutes)
  • If a teammate crashes, you can offer to respawn that specific teammate
  • Re-running the phase command starts fresh (artifacts on disk are preserved)

Too many teammates ​

Problem: The sprint needs more teammates than max_teammates allows.

Solution: Reduce the number of stories selected for the sprint, or increase agent_teams.max_teammates in config.yaml. Consider splitting the sprint into two smaller sprints by story ownership area.

Agent writing to wrong files ​

Problem: A teammate modifies files outside their ownership boundary.

Solution: Ownership boundaries are advisory -- they are injected into the spawn prompt but not technically enforced. If an agent crosses boundaries:

  1. Review the output and revert unwanted changes
  2. Check that the team YAML correctly maps owns_from_config to the right ownership key
  3. Verify that config.yaml ownership paths match your actual project structure

File Ownership Conflicts ​

Default ownership paths do not match project ​

Problem: The ownership section in config.yaml uses default paths (src/backend/, src/frontend/) that do not match your project.

Solution: Update the ownership section manually, or run /sniper-ingest which auto-detects your project structure and updates ownership paths.

Stories assigned to wrong teammate ​

Problem: During a sprint, stories are assigned to a teammate whose ownership does not match the story's file touches.

Solution: The sprint command maps stories to teammates based on the "File Ownership" field in each story. If stories were created with incorrect ownership fields, edit the story files in docs/stories/ to correct the ownership, then re-run /sniper-sprint.

Review Gate Issues ​

Gate blocking advancement ​

Problem: A strict review gate has failures that block advancement.

Solutions:

  • Fix the failing items in the artifacts and run /sniper-review again
  • For the plan gate specifically: the checklist is designed to catch cascading problems. Address all FAIL items before advancing -- overriding is not possible on strict gates with failures.

Gate evaluating wrong phase ​

Problem: /sniper-review evaluates a different phase than expected.

Solution: The review command determines the current phase from the last entry in state.phase_log where completed_at is null. Run /sniper-status to verify the current phase state. If the state is incorrect, you may need to manually update state.phase_log in config.yaml.

Checklist file not found ​

Problem: Review fails with "Checklist file not found."

Solution: Verify the checklist file exists at the path shown in the error. Standard checklists are in .sniper/checklists/. If missing, the framework installation may be incomplete -- re-run sniper init from the CLI.

Memory Issues ​

Memory not loading ​

Problem: Spawn prompts do not include memory context.

Solutions:

  • Verify memory.enabled: true in config.yaml
  • Check that .sniper/memory/ directory exists with YAML files
  • The memory system requires at least one entry in any memory file to produce output

Memory exceeding token budget ​

Problem: A warning appears about memory being truncated.

Solution: Increase memory.token_budget in config.yaml (default: 2000). Alternatively, clean up low-priority entries with /sniper-memory --remove {id}.

Retrospective not running ​

Problem: No retrospective runs after sprint completion.

Solutions:

  • Verify memory.auto_retro: true in config.yaml
  • Check that memory.enabled: true
  • If auto_retro is disabled, run manually with /sniper-memory --retro

Sprint Issues ​

Stories not self-contained ​

Problem: Sprint agents ask questions about requirements that should be in the story file.

Solution: The solve phase should embed all context from PRD, architecture, and UX spec into each story. If stories reference other documents instead of embedding content, re-run /sniper-solve or manually edit the story files to embed the missing context.

API contract misalignment ​

Problem: Backend and frontend implementations do not agree on API contracts.

Solutions:

  • The team lead should facilitate contract alignment at the start of each sprint
  • Use the sprint coordination rules: message both agents to share endpoint specs and data shapes before coding
  • Consider adding explicit API contract stories that must complete before frontend stories begin

Tests failing after sprint ​

Problem: The QA engineer reports test failures.

Solution: The team lead messages the implementing teammate with specific failure details. The teammate fixes their code and QA re-tests. This cycle repeats until all tests pass. The sprint review gate will not advance until tests pass.

CLI Errors ​

"Command not found: sniper" ​

Problem: The sniper CLI is not available.

Solution: Verify installation with npm list -g @sniper.ai/cli. If not installed, run npm install -g @sniper.ai/cli.

Slash commands not working ​

Problem: Claude Code does not recognize /sniper-* commands.

Solution: Verify that command files exist in .claude/commands/ (or the project's command directory). These should have been created during sniper init. If missing, re-run the CLI scaffolding.

State Recovery ​

Corrupted config.yaml ​

Problem: Config file has YAML syntax errors or invalid state.

Solutions:

  • Fix YAML syntax errors (common causes: unquoted strings with colons, incorrect indentation)
  • If the state section is corrupted but artifacts are intact on disk, you can reset the state section manually while preserving project configuration
  • As a last resort, re-run /sniper-init (this will overwrite config but preserve artifacts in docs/)

Phase stuck in progress ​

Problem: A phase shows as active but the conversation has ended.

Solution: Find the active entry in state.phase_log (where completed_at is null) and either:

  1. Set completed_at to the current timestamp if the phase's artifacts are complete
  2. Leave it and re-run the phase command -- it will detect the active phase and offer to resume or start fresh

Next Steps ​