SpecDDTroubleshooting
Short, practical fixes for common SpecDD problems: setup issues, editor recognition, CLI installs, Node versions, spec resolution, stale specs, agent behavior, and plugin or skill discovery.
- How to fix an agent that ignores your specs
Troubleshoot agents that ignore SpecDD by verifying setup files, plugin or skill loading, the correct project root, local spec placement, and task-focused prompts.
Read guide - How to fix .sdd files not being recognized or highlighted
Troubleshoot .sdd highlighting in VS Code-compatible editors and JetBrains IDEs by checking installation, enablement, associations, trust, reloads, and extension.
Read guide - How to fix a failing SpecDD CLI install or "command not found"
Troubleshoot SpecDD CLI install problems by checking install method, Node version, global package path, shell PATH, terminal reload, Docker fallback, and help output.
Read guide - How to fix SpecDD Node version errors
Resolve SpecDD Node.js errors by confirming the active runtime is version 22 or newer, upgrading the right environment, and retesting the CLI install.
Read guide - How to resolve ambiguous spec match warnings
Fix ambiguous SpecDD matches when multiple case-insensitive same-basename specs could govern one target by renaming files and preserving exact local authority.
Read guide - How to fix path references that do not resolve
Troubleshoot unresolved SpecDD paths by checking ./, ../, and / references, content root assumptions, renamed files, case differences, and malformed globs.
Read guide - How to debug spec resolution problems
Fix spec resolution by walking from the content root to the target, checking directory and same-basename specs, explicit references, globs, and write authority.
Read guide - How to fix specs that are too vague to be useful
Turn vague .sdd specs into useful local contracts by adding scope, ownership, observable behavior, boundaries, tasks, scenarios, and completion criteria.
Read guide - How to fix a spec that conflicts with a parent spec
Resolve parent-child SpecDD conflicts by preserving inherited constraints, treating Must not and Forbids as stronger than tasks, and fixing the owning rule.
Read guide - How to fix an agent that cannot find the right local spec
Troubleshoot local spec discovery by confirming the agent starts from the right root, targets the right path, and can resolve same-basename and referenced specs.
Read guide - How to fix stale Done when criteria
Refresh stale Done when criteria so completion signals match current behavior, tasks, tests, and review expectations.
Read guide - How to fix broken SpecDD plugin or skill installs
Troubleshoot SpecDD plugins and universal Agent Skills by checking the install method, target scope, skill directory, reload behavior, and whether the agent can use a SpecDD skill.
Read guide
More How-To categories
- Getting started
Start with spec-driven development, write your first local SpecDD spec, and run a small end-to-end change with human-and-agent-friendly guardrails.
11 guides - Install and setup
Install the SpecDD CLI, prepare Node.js when needed, initialize or update projects, and verify the framework files are wired correctly.
9 guides - Set up your agent
Set up Claude Code, Codex, GitHub Copilot, Cursor, Windsurf, Gemini CLI, OpenCode, Junie, Cline, Antigravity, and universal Agent Skills for SpecDD.
15 guides - Editor setup
Install SpecDD editor support, validate .sdd files, resolve path warnings, and use completions and section hints while writing specs.
4 guides - Agent workflows
Use SpecDD with agents by keeping prompts short, plans spec-bound, file changes authorized, context durable, and reviews tied to local .sdd contracts.
15 guides - Write specs by level
Write SpecDD specs at the right level: root specs for project context, module specs for area boundaries, and focused specs for local behavior and contracts.
14 guides - Use spec sections
Use SpecDD sections correctly: write only sections that add local value, keep authority clear, and express behavior, boundaries, tasks, scenarios, paths, and examples.
25 guides - Spec-writing technique
Improve SpecDD craft with techniques for small specs, right-level placement, naming, splitting, explicit rules, draft review, edge cases, and compatibility.
16 guides - Spec-driven workflows
Use SpecDD workflows to draft, review, implement, synchronize, and evolve local specs without losing source-of-truth context.
11 guides - Work with SpecDD skills
Use SpecDD skills deliberately: choose the right skill for the phase, keep authority clear, chain skills safely, and verify each result against local specs.
17 guides - Software design practices
Use SpecDD to make software design decisions operational: responsibility, boundaries, layers, cohesion, debt prevention, public APIs, and dependency direction.
20 guides - Adopt SpecDD on existing projects
Adopt SpecDD gradually in live codebases by starting with active areas, reviewing generated specs, expanding folder by folder, and measuring practical review and delivery signals.
10 guides - Testing and quality
Turn SpecDD specs into practical quality work: TDD and BDD loops, acceptance criteria, coverage tracing, CI checks, regression tests, and testability review.
11 guides - Code review and governance
Use SpecDD in code review and governance by checking local authority, behavior, boundaries, spec updates, agent output, and high-risk contract changes.
9 guides - Refactoring and maintenance
Use SpecDD to keep maintenance safe: preserve specified behavior, maintain authority while moving code, keep specs current, and delete obsolete contracts carefully.
9 guides - Security and risk
Use SpecDD to make security and risk constraints local, explicit, reviewable, and hard for humans or agents to weaken accidentally.
13 guides - Teams and process
Use SpecDD as a team process by keeping durable behavior in specs, project planning in tickets, conventions in bootstrap.project.md, and reviews lightweight but consistent.
13 guides