Debugging Failures

This guide helps you interpret SpecLeft failures and fix them quickly.

1. Planning failures (specleft plan)

Common cause: missing prd.md in the repository root.

Fix:

# Create prd.md and try again
specleft plan --dry-run

2. Validation errors (specleft features validate)

Common causes:

• Missing required frontmatter fields
• Duplicate IDs
• Invalid ID format (must match ^[a-z0-9-]+$)

Fix workflow:

specleft features validate --format json

Then open the referenced file and fix the field or ID.

3. Enforcement failures (specleft enforce)

Enforcement fails when required intent is missing or coverage is below threshold.

Fix workflow:

specleft status
specleft coverage

Focus on the missing scenarios and implement the highest priority first.

4. CI log readability

Use JSON output in CI for predictable parsing:

specleft enforce --format json

5. Common quick checks

specleft doctor
specleft features list
specleft next --priority high