Troubleshooting

Common issues and solutions for SpecFact CLI.

Installation Issues

Command Not Found

Issue: specfact: command not found

Solutions:

1. Check installation:

   pip show specfact-cli
   

2. Reinstall:

   pip install --upgrade specfact-cli
   

Plan Bundles are Slow or Outdated

Symptom: Project commands take a long time or return stale data.

Cause: Plan bundles may be missing summary metadata (older schema version 1.0).

Solution:

# Regenerate all plan bundles to latest schema
specfact project regenerate

# Verify with health check
specfact project health-check

Performance Improvement: After regenerating, bundles are updated and scale better with large projects.

1. Use uvx (no installation needed):

   uvx specfact-cli@latest --help
   

Permission Denied

Issue: Permission denied when running commands

Solutions:

1. Use user install:

   pip install --user specfact-cli
   

2. Check PATH:

   echo $PATH
   # Should include ~/.local/bin
   

3. Add to PATH:

   export PATH="$HOME/.local/bin:$PATH"
   

Import Issues

Spec-Kit Not Detected

Issue: No Spec-Kit project found when running import from-bridge --adapter speckit

Solutions:

1. Check directory structure:

   ls -la .specify/
   ls -la specs/
   

2. Verify Spec-Kit format:

   • Should have .specify/ directory
   • Should have specs/ directory with feature folders
   • Should have specs/[###-feature-name]/spec.md files

3. Use explicit path:

   specfact code import from-bridge --adapter speckit --repo /path/to/speckit-project
   

Code Analysis Fails (Brownfield) ⭐

Issue: Analysis failed or No features detected when analyzing legacy code

Solutions:

1. Check repository path:

   specfact code import legacy-api --repo . --verbose
   

2. Lower confidence threshold (for legacy code with less structure):

   specfact code import legacy-api --repo . --confidence 0.3
   

3. Check file structure:

   find . -name "*.py" -type f | head -10
   

4. Use CoPilot mode (recommended for brownfield - better semantic understanding):

   specfact --mode copilot code import from-code legacy-api --repo . --confidence 0.7
   

5. For legacy codebases, start with minimal confidence and review extracted features:

   specfact code import legacy-api --repo . --confidence 0.2
   

Sync Issues

Watch Mode Not Starting

Issue: Watch mode exits immediately or doesn’t detect changes

Solutions:

1. Check repository path:

   specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --watch --interval 5 --verbose
   

2. Verify directory exists:

   ls -la .specify/
   ls -la .specfact/
   

3. Check permissions:

   ls -la .specfact/projects/
   

4. Try one-time sync first:

   specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
   

Bidirectional Sync Conflicts

Issue: Conflicts during bidirectional sync

Solutions:

1. Check conflict resolution:

   • SpecFact takes priority by default
   • Manual resolution may be needed

2. Review changes:

   git status
   git diff
   

3. Use one-way sync:

   # Spec-Kit → SpecFact only
   specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo .
   
   # SpecFact → Spec-Kit only (manual)
   # Edit Spec-Kit files manually
   

Enforcement Issues

Enforcement Not Working

Issue: Violations not being blocked or warned

Solutions:

1. Check enforcement configuration (use CLI commands):

   specfact govern enforce show-config
   

2. Verify enforcement mode:

   specfact govern enforce stage --preset balanced
   

3. Run validation:

   specfact code repro --verbose
   

4. Check severity levels:

   • HIGH → BLOCK (in balanced/strict mode)
   • MEDIUM → WARN (in balanced/strict mode)
   • LOW → LOG (in all modes)

False Positives

Issue: Valid code being flagged as violations

Solutions:

1. Review violation details:

   specfact code repro --verbose
   

2. Adjust confidence threshold:

   specfact code import legacy-api --repo . --confidence 0.7
   

3. Check enforcement rules (use CLI commands):

   specfact govern enforce show-config
   

4. Use minimal mode (observe only):

   specfact govern enforce stage --preset minimal
   

Constitution Issues

Constitution Missing or Minimal

Issue: Constitution required or Constitution is minimal when running sync bridge --adapter speckit

Note: specfact spec sdd constitution commands are removed; use specfact govern enforce sdd [BUNDLE] for SDD enforcement.

Solutions:

1. Enforce SDD (recommended):

   specfact govern enforce sdd <bundle-name>
   

   This validates SDD compliance for your bundle.

2. Manual creation (for greenfield):

   • Run /speckit.constitution command in your AI assistant
   • Fill in the constitution template manually

When to use each option:

• SDD enforcement (all cases): Use specfact govern enforce sdd [BUNDLE] to validate compliance
• Manual (greenfield): Use when starting a new project and want full control

Constitution Validation Fails

Issue: Constitution validation reports issues

Solutions:

1. Check for placeholders:

   grep -r "\[.*\]" .specify/memory/constitution.md
   

2. Run SDD enforcement:

   # specfact spec sdd constitution commands are removed; use specfact govern enforce sdd [BUNDLE] for SDD enforcement
   specfact govern enforce sdd <bundle-name>
   

   The output will list specific issues (missing sections, placeholders, etc.).

3. Fix issues manually or re-run enforcement.

Plan Comparison Issues

Plans Not Found

Issue: Plan not found when running plan compare

Solutions:

1. Check plan locations:

   ls -la .specfact/projects/
   ls -la .specfact/projects/<bundle-name>/reports/brownfield/
   

2. Use explicit paths (bundle directory paths):

   specfact project devops-flow --stage plan --action compare \
     --manual .specfact/projects/manual-plan \
     --auto .specfact/projects/auto-derived
   

3. Generate auto-derived plan first:

   specfact code import legacy-api --repo .
   

No Deviations Found (Expected Some)

Issue: Comparison shows no deviations but you expect some

Solutions:

1. Check feature key normalization:

   • Different key formats may normalize to the same key
   • Check reference/feature-keys.md for details

2. Verify plan contents (use CLI commands):

   specfact project devops-flow --stage develop --bundle <bundle-name>
   

3. Use verbose mode:

   specfact project devops-flow --stage plan --action compare --bundle legacy-api --verbose
   

IDE Integration Issues

Slash Commands Not Working

Issue: Slash commands not recognized in IDE

Solutions:

1. Reinitialize IDE integration:

   specfact init ide --ide cursor --force

1. Check command files:

   ls -la .cursor/commands/specfact-*.md
   

2. Restart IDE: Some IDEs require restart to discover new commands

3. Check IDE settings:

   • VS Code: Check .vscode/settings.json
   • Cursor: Check .cursor/settings.json

Command Files Not Created

Issue: Command files not created after specfact init

Solutions:

1. Check permissions:

   ls -la .cursor/commands/
   

2. Use force flag:

   specfact init ide --ide cursor --force

1. Check IDE type:

   specfact init ide --ide cursor  # For Cursor
   specfact init ide --ide vscode  # For VS Code

Mode Detection Issues

Wrong Mode Detected

Issue: CI/CD mode when CoPilot should be detected (or vice versa)

Solutions:

1. Use explicit mode:

   specfact --mode copilot code import from-code my-project --repo .
   

2. Check environment variables:

   echo $COPILOT_API_URL
   echo $VSCODE_PID
   

3. Set mode explicitly:

   export SPECFACT_MODE=copilot
   specfact code import legacy-api --repo .
   

4. See Operational Modes for details

Performance Issues

Slow Analysis

Issue: Code analysis takes too long

Solutions:

1. Use CI/CD mode (faster):

   specfact --mode cicd code import from-code my-project --repo .
   

2. Increase confidence threshold (fewer features):

   specfact code import legacy-api --repo . --confidence 0.8
   

3. Exclude directories:

   # Use .gitignore or exclude patterns
   specfact code import legacy-api --repo . --exclude "tests/"
   

Watch Mode High CPU

Issue: Watch mode uses too much CPU

Solutions:

1. Increase interval:

   specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --watch --interval 10
   

2. Use one-time sync:

   specfact project sync bridge --adapter speckit --bundle <bundle-name> --repo . --bidirectional
   

3. Check file system events:

   • Too many files being watched
   • Consider excluding directories

Terminal Output Issues

SpecFact CLI automatically detects terminal capabilities and adjusts output formatting for optimal user experience across different environments. No manual configuration required - the CLI adapts to your terminal environment.

How Terminal Auto-Detection Works

The CLI automatically detects terminal capabilities in this order:

1. Test Mode Detection:
   • TEST_MODE=true or PYTEST_CURRENT_TEST → MINIMAL mode
2. CI/CD Detection:
   • CI, GITHUB_ACTIONS, GITLAB_CI, CIRCLECI, TRAVIS, JENKINS_URL, BUILDKITE → BASIC mode
3. Color Support Detection:
   • NO_COLOR → Disables colors (respects NO_COLOR standard)
   • FORCE_COLOR=1 → Forces colors
   • TERM and COLORTERM environment variables → Additional hints
4. Terminal Type Detection:
   • TTY detection (sys.stdout.isatty()) → Interactive vs non-interactive
   • Interactive TTY with animations → GRAPHICAL mode
   • Non-interactive → BASIC mode
5. Encoding Safety Detection:
   • UTF-8 capable streams keep Unicode icons and Rich box drawing
   • Legacy encodings (for example cp1252) disable emoji and switch to ASCII-safe box rendering
   • Unicode-unsafe text streams are reconfigured with replacement error handling to avoid hard crashes during output
6. Default Fallback:
   • If uncertain → BASIC mode (safe, readable output)

Terminal Modes

The CLI supports three terminal modes (auto-selected based on detection):

• GRAPHICAL - Full Rich features (colors, animations, progress bars) for interactive terminals
• BASIC - Plain text, no animations, simple progress updates for CI/CD and embedded terminals
• MINIMAL - Minimal output for test mode

Rich output also downgrades symbol rendering when the active terminal encoding is not UTF-8-safe. This keeps Windows legacy consoles and other non-UTF-8 terminals readable instead of failing on icon output.

Environment Variables (Optional Overrides)

You can override auto-detection using standard environment variables:

• NO_COLOR - Disables all colors (respects NO_COLOR standard)
• FORCE_COLOR=1 - Forces color output even in non-interactive terminals
• CI=true - Explicitly enables basic mode (no animations, plain text)
• TEST_MODE=true - Enables minimal mode for testing

Examples

# Auto-detection (default behavior)
specfact code import my-bundle
# → Automatically detects terminal and uses appropriate mode

# Manual override: Disable colors
NO_COLOR=1 specfact code import my-bundle

# Manual override: Force colors in CI/CD
FORCE_COLOR=1 specfact project sync bridge

# Manual override: Explicit CI/CD mode
CI=true specfact code import my-bundle

No Progress Visible in Embedded Terminals

Issue: No progress indicators visible when running commands in Cursor, VS Code, or other embedded terminals.

Cause: Embedded terminals are non-interactive and may not support Rich animations.

Solution: The CLI automatically detects embedded terminals and switches to basic mode with plain text progress updates. If you still don’t see progress:

1. Verify auto-detection is working:

   # Check terminal mode (should show BASIC in embedded terminals)
   python -c "from specfact_cli.runtime import get_terminal_mode; print(get_terminal_mode())"
   

2. Check environment variables:

   # Ensure NO_COLOR is not set (unless you want plain text)
   unset NO_COLOR
   

3. Verify terminal supports stdout:
   • Embedded terminals should support stdout (not stderr-only)
   • Progress updates are throttled - wait a few seconds for updates

4. Manual override (if needed):

   # Force basic mode
   CI=true specfact code import my-bundle
   

Colors Not Working in CI/CD

Issue: No colors in CI/CD pipeline output.

Cause: CI/CD environments are automatically detected and use basic mode (no colors) for better log readability.

Solution: This is expected behavior. CI/CD logs are more readable without colors. To force colors:

FORCE_COLOR=1 specfact code import my-bundle

Azure DevOps Issues

Azure DevOps Token Required

Issue: “Azure DevOps token required” error when running specfact backlog refine ado or specfact backlog map-fields.

Solutions:

1. Use stored token (recommended):

   specfact backlog auth azure-devops
   # Or use PAT token for longer expiration:
   specfact backlog auth azure-devops --pat your_pat_token
   

2. Use explicit token:

   specfact backlog refine ado --ado-org myorg --ado-project myproject --ado-token your_token
   

3. Set environment variable:

   export AZURE_DEVOPS_TOKEN=your_token
   specfact backlog refine ado --ado-org myorg --ado-project myproject
   

Token Resolution Priority:

The command automatically uses tokens in this order:

1. Explicit --ado-token parameter
2. AZURE_DEVOPS_TOKEN environment variable
3. Stored token via specfact backlog auth azure-devops
4. Expired stored token (shows warning with options)

OAuth Token Expired

Issue: “Stored OAuth token expired” warning when using ADO commands.

Cause: OAuth tokens expire after approximately 1 hour.

Solutions:

1. Use PAT token (recommended for automation, up to 1 year expiration):

   specfact backlog auth azure-devops --pat your_pat_token
   

2. Re-authenticate:

   specfact backlog auth azure-devops
   

3. Use explicit token:

   specfact backlog refine ado --ado-org myorg --ado-project myproject --ado-token your_token
   

Fields Not Extracted from ADO Work Items

Issue: Fields like acceptance criteria or assignee are not being extracted from ADO work items.

Solutions:

1. Check field names: ADO field names are case-sensitive and must match exactly:
   • Use specfact backlog map-fields to discover exact field names in your project
   • Common fields: Microsoft.VSTS.Common.AcceptanceCriteria (preferred) or System.AcceptanceCriteria

2. Verify custom mapping: Check if custom mapping file exists and is correct:

   cat .specfact/templates/backlog/field_mappings/ado_custom.yaml
   

3. Reset to defaults: If mappings are corrupted:

   specfact backlog map-fields --ado-org myorg --ado-project myproject --reset
   

4. Check multiple alternatives: SpecFact CLI supports multiple field names for the same canonical field. Both System.AcceptanceCriteria and Microsoft.VSTS.Common.AcceptanceCriteria are checked automatically.

Interactive Mapping Command Fails

Issue: specfact backlog map-fields fails with connection or permission errors.

Solutions:

1. Check token permissions: Ensure your PAT has “Work Items (Read)” permission
2. Verify organization/project names: Check for typos in --ado-org and --ado-project

3. Test API connection:

   curl -u ":{token}" "https://dev.azure.com/{org}/{project}/_apis/wit/fields?api-version=7.1"
   

4. Use explicit token: Override with --ado-token if stored token has issues
5. Check base URL: For on-premise Azure DevOps Server, use --ado-base-url

Custom Mapping Not Applied

Issue: Custom field mapping file exists but is not being used.

Solutions:

1. Check file location: Must be at .specfact/templates/backlog/field_mappings/ado_custom.yaml
2. Verify YAML syntax: Use a YAML validator to check syntax
3. Check file permissions: Ensure the file is readable
4. Validate schema: Ensure the file matches FieldMappingConfig schema
5. Automatic detection: Custom mappings are automatically detected - no restart needed. If not working, check file path and syntax.

Backlog refine or work item PATCH fails (400/422)

Issue: specfact backlog refine ado ... --write or work item update fails with HTTP 400/422 (e.g. “400 Client Error: Bad Request”) or an ADO message like “TF51535: Cannot find field System.AcceptanceCriteria.”

Cause: The Azure DevOps project may use a custom process template where field names or paths differ from defaults (e.g. no System.AcceptanceCriteria). The JSON Patch sent by the CLI targets a field that does not exist or is not writable in that project.

Solutions:

1. Read the console message – The CLI prints the ADO error text and a hint, e.g. “Check custom field mapping; see ado_custom.yaml or documentation.” If a field is named (e.g. “Field ‘System.AcceptanceCriteria’ not found”), that is the one to fix in mapping or template.

2. Run with --debug and inspect the log – This gives you the exact ADO response and the patch paths that were sent:
   • Run: specfact --debug backlog refine ado --ado-org <org> --ado-project <project> ... (or the failing command).
   • Open ~/.specfact/logs/specfact-debug.log and search for "operation": "ado_patch" and "status": "failed".
   • In that line, extra.response_body is a redacted snippet of the ADO error payload; extra.patch_paths lists the JSON Patch paths (e.g. ["/fields/System.AcceptanceCriteria", ...]). Use these to see which field path failed.
3. Fix field mapping – If the error is about a missing or wrong field:
   • Ensure .specfact/templates/backlog/field_mappings/ado_custom.yaml exists and maps your canonical fields to the field names/paths that exist in your ADO project.
   • Use specfact backlog map-fields --provider ado --ado-org <org> --ado-project <project> --non-interactive first to auto-map fields and persist required-field / allowed-values metadata.
   • If auto-mapping exits with unresolved required fields, rerun specfact backlog map-fields --ado-org <org> --ado-project <project> interactively to correct mappings.
   • See Custom Field Mapping and Debug Logging – Examining ADO API Errors.
4. Check project process template – Custom ADO process templates can rename or remove fields. Align your mapping with the actual work item type and process in the project.

CI and GitHub Actions

Downloading test and repro logs from CI

When a PR or push runs the PR Orchestrator workflow, test and repro output are uploaded as workflow artifacts so you can debug failures without re-running the full suite locally.

1. Where to find artifacts

   • Open the workflow run: Actions → select the PR Orchestrator run (e.g. from your PR or branch).
   • Scroll to the Artifacts section at the bottom of the run.

2. Artifact names and contents

   Artifact	Job	Contents
   test-logs	Tests (Python 3.12)	Full test run and coverage logs from hatch run smart-test-full (logs/tests/).
   coverage-reports	Tests (Python 3.12)	Coverage XML for quality gates (when unit tests ran).
   compat-py311-logs	Compatibility (Python 3.11)	Pytest and coverage XML output from the compat job.
   type-check-logs	Type Checking (basedpyright)	Full basedpyright type-check output.
   lint-logs	Linting (ruff, pylint)	Full lint run output.
   quality-gates-logs	Quality Gates (Advisory)	Coverage percentage and advisory message.
   repro-logs	Contract-First CI	Full stdout/stderr of specfact code repro (logs/repro/).
   repro-reports	Contract-First CI	Repro report YAMLs from .specfact/reports/enforcement/.

3. How to use them

   • Download the artifact (e.g. test-logs or repro-logs) from the run page.
   • Unzip and open the log or report files to see the full output that led to the failure.
   • Use this instead of copying snippets from the step log, so you get complete error context before fixing and pushing again.

Getting Help

If you’re still experiencing issues:

1. Check logs:

   • Debug log file (when using --debug): Debug output and structured operation metadata are written to ~/.specfact/logs/specfact-debug.log. See Debug Logging for what is logged and how to use it.
   • Verbose repro (ad-hoc capture):

   specfact --debug <command> <args>   # Writes to ~/.specfact/logs/specfact-debug.log
   specfact code repro --verbose 2>&1 | tee debug.log
   

2. Search documentation:

   • Command Reference
   • Use Cases
   • Workflows

3. Community support:

   • 💬 GitHub Discussions
   • 🐛 GitHub Issues

4. Direct support:

   • 📧 [email protected]

Happy building! 🚀