Troubleshooting

Troubleshooting

Quick diagnostics

Goal	How
Verify what actually loaded (Claude Code)	/context
Verify what actually loaded (VS Code Copilot)	right-click in the Chat view → Diagnostics — lists every loaded agent, skill and instruction file with its load status
Manage / inspect Claude Code memory	/memory
Something in the setup looks broken (Claude Code)	/doctor
Prompt-file discovery errors (VS Code)	Chat view ellipsis menu → Show Agent Debug Logs

A /sdd-* command does not appear

In VS Code Copilot

1. Did you open the project folder itself? Opening a parent folder is the most common cause — slash commands are discovered from the workspace root.
2. Restart VS Code completely. Not a window reload — a full restart. New prompt files are frequently only picked up that way.
3. Confirm the file is .github/prompts/<name>.prompt.md. The .prompt.md extension is required for discovery; a plain .md file is invisible.
4. Confirm nothing removed .github/prompts from chat.promptFilesLocations in user or workspace settings.
5. Check the Agent Debug Log (Chat view ellipsis menu → Show Agent Debug Logs) for discovery errors.

In Claude Code

1. Confirm the body sits directly in .claude/commands/ and ends in .md. The command name is the file name without the extension.
2. Claude Code picks up new command files without a restart — if it still does not appear, the file is in the wrong place or the frontmatter is malformed.
3. Run /doctor.

A .claude/rules rule did not apply

Rules are path-scoped and load on read. Two things to check:

1. Was a matching file actually read in this session? A rule with paths: [.specs/**/*.md] does not load until the assistant reads a spec. This is by design — and it is why /sdd-specify, /sdd-plan, /sdd-setup and /sdd-lifecycle restate or explicitly read their essentials inline, since they create the files their rules describe. See Design Decisions.
2. In VS Code: confirm nothing set .claude/rules to false in chat.instructionsFilesLocations. The two official VS Code pages disagree on whether .claude/rules is a default location, which is exactly why the shipped .vscode/settings.json enables it explicitly.

If a rule genuinely needs to be always-on, it belongs in AGENTS.md, not in a rule file.

The assistant ignores AGENTS.md

Claude Code: run /context and confirm AGENTS.md is listed. If not, check that CLAUDE.md contains exactly @AGENTS.md and that you opened the repository root.

VS Code Copilot: confirm chat.useAgentsMdFile is true (the shipped .vscode/settings.json sets it). Then use Chat → Diagnostics to see whether it loaded.

The assistant answers in the wrong language

DocLanguage in AGENTS.md governs the language of your project documentation — Memory Bank, specs, plans, README. Check the value:

DocLanguage: English

Change the line directly, or re-run /sdd-setup. Note that FeatherSpec's own wiring (the command bodies, the constitution's own headings) stays English on purpose — only your project's documents follow DocLanguage.

Hooks do not fire

1. In VS Code, hooks are a Preview feature. Check the chat.useClaudeHooks setting.
2. VS Code ignores matcher values — hooks fire on every tool invocation there. A shared hook must filter on tool_name inside the script itself.
3. The input shape differs: VS Code uses camelCase (tool_input.filePath) and its own tool names; Claude Code uses snake_case (tool_input.file_path). A shared hook has to handle both.

See Configuration.

A spec ended up in two folders

That should not happen — /sdd-lifecycle scans all three folders before moving and deletes copies in less-advanced folders (done > active > backlog). If it did happen, delete the copies manually so exactly one remains, keeping the most advanced folder, then re-run /sdd-lifecycle to fix the status lines.

If a .plan.md file ended up in a different folder than its spec, move it back next to the spec. A plan must never live apart from its spec.

The plan says one thing, the code says another

The plan file wins as the record, but reality wins as the fact. Run /sdd-plan in resume mode: it reads the plan, verifies Current step and Session handoff against git status --short and the actual code, and reports the discrepancy. Then correct the file.

This is why the rule is to update the plan in the same change set as the code — a plan that quietly drifts is worse than no plan.

/sdd-plan says it cannot research

That is correct behaviour, not a failure. When no web search or fetch capability is available, the workflow is required to say so plainly and mark the affected steps as assumptions rather than presenting a guess as fact.

In Claude Code, WebSearch is US-only; WebFetch works more broadly. In VS Code, use agent mode so the web tool and #fetch are available.

Still stuck?

Open an issue: https://github.com/GregorBiswanger/featherspec/issues