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: rules do not load from .claude/rules at all — VS Code cannot read instruction files from that folder. Copilot reaches each rule through its thin loader .github/instructions/<name>.instructions.md (applyTo mirrors the rule's paths: globs; the body points at the .claude/rules single source). Confirm the loader exists and that nothing set .github/instructions to false in chat.instructionsFilesLocations — the shipped .vscode/settings.json enables it explicitly (and deliberately sets .claude/rules to false).

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.

Copilot knows things in a fresh project

That is the copilot-chat extension's local memory tool: user-scope memory files auto-inject their first 200 lines into every session on your machine, in every project — including one you just cloned. Run Chat: Show Memory Files to see what it holds and Chat: Clear All Memory Files to wipe it. The shipped .vscode/settings.json disables the tool (github.copilot.chat.tools.memory.enabled: false), but the switch has known gaps — see Configuration for the two memory systems, the storage paths and the limits. Whatever leaks through, FeatherSpec's guard still applies: a preference claimed from memory is proposed and asked about, never followed.

A spec ended up in two folders

That should not happen — /sdd-lifecycle scans all three folders before every move and removes duplicates, keeping the copy that holds the current working state (normally the one being moved). If it did happen, run /sdd-lifecycle and let its duplicate check do the removal. For a duplicated plan this is the one sanctioned deletion — the never-deleted rule protects the plan's content, not stray redundant copies of it — and the check confirms which copy is current before deleting, then fixes the status lines.

In backlog/ and active/ a .plan.md belongs beside its same-name spec and moves with it. A dated plan in .specs/plan-archive/ lives apart by design — that is the archive, not a stray; do not "fix" it back.

A moved spec or plan reappeared in its old folder

The usual mechanism is not the workflow but your editor: a still-open tab or a pending edit-review buffer of the moved file re-saves it at the old path on the next "save all" — which is why /sdd-lifecycle moves first and edits second, and why its hand-off tells you to close or accept those buffers immediately after every move.

Fix: delete the stray copy through /sdd-lifecycle — its duplicate check is the sanctioned removal, and it confirms which copy holds the current working state first.

Prevention: close or accept those tabs and buffers right after the move, then run /sdd-overview once — its warnings catch strays this entry describes, including orphaned plans (a .plan.md in backlog/ or active/ without its same-name spec beside it, or one with a dated twin in plan-archive/).

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.

/sdd-featherspec-update does not appear after copying it in

VS Code needs a full restart — not a window reload — to discover new prompt files; the loader is invisible until then. Claude Code picks the body up without a restart. See Updating & Versioning for which files to copy.

An update was interrupted

Run /sdd-featherspec-update again — it resumes from the files in .sdd-update/; the files decide where it continues, not the conversation. The version stamp moves only after a successful run, so an interruption never leaves you half-stamped. To restore the old state instead, use the rollback branch featherspec-backup/pre-<version> (or the folder backup the run announced).

The updater says my file conflicts, but I never touched it

Line endings and trailing whitespace are not the cause — files are hashed canonically, so those never count as your edits. The usual real cause is a project adopted from an unreleased mid-cycle state of the template rather than a release tag, so no tag matches your base. The updater detects this and offers a re-baseline.

Still stuck?

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