Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/specify_cli/init.py
• spec-driven.md
• templates/plan-template.md
• templates/spec-template.md
• templates/tasks-template.md
• scripts/check-task-prerequisites.sh
• SUPPORT.md

This document provides guidance for troubleshooting common issues encountered during environment setup and while using the Spec-Driven Development (SDD) workflow with spec-kit. It covers problems related to the specify CLI, the core /specify, /plan, and /tasks commands, and general development workflow challenges.

For a complete overview of the methodology, refer to the Complete Spec-Driven Development Methodology.

Environment and Setup Issues

This section addresses problems that may occur when initializing a new project or checking the development environment.

specify init Command

The specify init command bootstraps a new project. Issues during this phase are typically related to missing prerequisites, directory permissions, or incorrect arguments.

The following diagram illustrates the initialization flow, including validation checks and user selections.

init Command Options

Option	Description	Source
project_name	Name for the new project directory.	src/specify_cli/__init__.py:609
`--ai [claude	gemini	copilot]`
--ignore-agent-tools	Skips checks for AI agent tools like the Claude or Gemini CLI.	src/specify_cli/__init__.py:611
--no-git	Skips git repository initialization.	src/specify_cli/__init__.py:612
--here	Initializes the project in the current directory.	src/specify_cli/__init__.py:613

specify check Command

The specify check command verifies that all required and optional tools are installed. It checks for internet connectivity, git, and AI assistant CLIs.

Git Credential Manager on Linux

If you encounter Git authentication issues on Linux, you can install and configure the Git Credential Manager. The README.md provides a script to automate this process.

#!/usr/bin/env bash
set -e
echo "Downloading Git Credential Manager v2.6.1..."
wget https://github.com/git-ecosystem/git-credential-manager/releases/download/v2.6.1/gcm-linux_amd64.2.6.1.deb
echo "Installing Git Credential Manager..."
sudo dpkg -i gcm-linux_amd64.2.6.1.deb
echo "Configuring Git to use GCM..."
git config --global credential.helper manager
echo "Cleaning up..."
rm gcm-linux_amd64.2.6.1.deb

Sources: README.md:255-267

Spec-Driven Development (SDD) Workflow Issues

Troubleshooting the SDD workflow involves identifying at which stage—specification, planning, or tasking—a failure occurs. Each phase has defined error conditions.

The /specify Phase

This phase translates a user's feature description into a formal specification. Errors often stem from ambiguous prompts or missing information.

The execution flow for generating a specification is designed to catch ambiguity early.

A common issue is the AI making incorrect assumptions. The process is designed to prevent this by forcing the AI to mark ambiguities with [NEEDS CLARIFICATION: specific question]. If the output is wrong, review the spec and add these markers yourself, then re-run the generation.
Sources: templates/spec-template.md:36-39, spec-driven.md:314-321

The /plan Phase

The /plan command converts the specification into a technical implementation plan. Failures can occur if the spec is incomplete or if the proposed plan violates the project's constitution.

This diagram shows the planning flow, including constitutional checks and artifact generation.

If the AI gets stuck in a research loop or generates an over-engineered plan, you may need to intervene with more specific instructions to break down the problem or ask it to justify its choices against the constitution.
Sources: spec-driven.md:188-200, spec-driven.md:214-216

The /tasks Phase

The /tasks command breaks the implementation plan into a list of executable tasks. The most common failure is the absence of a plan.md file.

The check-task-prerequisites.sh script is run first to ensure the necessary plan exists.

General Guidance and Support

Common Problems and Resolutions

The detailed walkthrough in spec-driven.md highlights several common issues and how to guide the AI to resolve them.

| Problem | Recommended Action - - - - -'- -
| AI agent is stuck in a research loop. | Provide more specific, targeted instructions. Break the problem down into smaller steps and ask the agent to research each one in parallel instead of a broad topic. -
| AI agent adds unrequested components (over-eager). | Ask the agent to clarify the rationale for the change and its source. Remind it to adhere to the project's constitution.md. -
| Implementation fails with build or runtime errors. | For build errors, paste the CLI logs into the agent and ask it to resolve them. For runtime errors (e.g., in browser console), copy and paste the error message to the agent for resolution. -
Sources: spec-driven.md:188-241

Getting Help

If the troubleshooting steps in this guide do not resolve your issue, you can seek support by opening a GitHub issue. Before filing a new issue, please search existing ones to avoid duplicates.

When filing a bug report or feature request, provide as much detail as possible.
Sources: SUPPORT.md:3-5