Skip to main content

​
SpecKit Process Enforcement & Feature 049 Remediation

​
Overview

SpecKit Process Enforcement stops you from building features on unvalidated requirements. This feature blocks common workflow mistakes - like skipping quality validation or jumping to implementation with incomplete specs - that cost Feature 049 four weeks of wasted time and $45,000. Every spec now requires a B+ grade certificate before you can plan or build, and all process violations are logged for review.

​
Step-by-Step Guide

​
Running /speckit.specify with Automatic Validation

  1. Generate your specification: Run /speckit.specify in your AI assistant after uploading your requirements documents.
  2. Wait for automatic validation: The command now automatically runs hybrid validation after generating your spec.md file - you cannot skip this step.
  3. Review your certificate: Check the generated spec-certificate.json file. Look for the overallScore field (must be 80 or higher) and criticalIssues count (must be 0).
  4. Fix any issues: If your grade is below B+ or critical issues exist, revise your spec and run /speckit.specify again.

​
Transitioning to Planning

  1. Attempt to run /speckit.plan: Try running the planning command after your spec is complete.
  2. Pass pre-flight checks: The system automatically blocks if no certificate exists, if your grade is below 80, or if critical issues remain unresolved.
  3. See the error message: If blocked, you’ll see “Run /speckit.specify first” or details about which quality requirements failed.
  4. Fix and retry: Address the blockers and try again - there is no override option.

​
Converting Legacy Documents

  1. Identify legacy TSD documents: If you have Requirements/, Solution Design/, or similar directories without a spec.md file, the system detects this automatically.
  2. Run the conversion tool: Use /speckit.convert to transform your BRS/FRS/TRS/FSD/TSD documents into the new spec.md format.
  3. Review extracted requirements: The tool extracts requirements only - tech stack, API endpoints, and architecture patterns are excluded.
  4. Validate the converted spec: Run /speckit.specify to validate the converted spec and generate your certificate.

​
Checking Process Compliance

  1. Navigate to Analytics Dashboard (/analyticsdashboard): Access the main dashboard from your project menu.
  2. Query process violations: Use the audit endpoint to view all violations from the last 7 days: GET /api/v1/speckit/audit/violations
  3. Review violation details: See which teams or features skipped quality steps, when violations occurred, and what blockers were hit.
  4. View Feature 049 case study: Read SPECKIT_ENFORCEMENT.md to understand why each enforcement rule exists.

​
Retroactive Validation for Feature 049

  1. Access Feature 049 data: Navigate to the feature evaluation page for Feature 049.
  2. Run retroactive validation: Apply the SpecKit process to existing Feature 049 requirements to generate a quality certificate.
  3. Review the certificate: Check whether requirements were strong (B+ grade) - proving the issue was lack of validation, not weak requirements.
  4. Compare ROI metrics: View quantified costs of not using SpecKit vs. using it, showing the $45,000 in lost productivity.

​
Common Questions

Q: What happens if I try to bypass the quality checks?
A: You cannot. All soft warnings have been replaced with hard blocks. Commands like /speckit.plan exit with error status code 1 if requirements aren’t met. There is no “proceed anyway” option - the system forces you to fix quality issues before moving forward. Q: Can I still use my old TSD/FSD documents?
A: Yes, but you must convert them first. The system detects legacy document structures and blocks progression if no spec.md exists. Use the conversion tool to extract requirements from your existing documents into the new format, then validate. Q: Why was Feature 049 used as the example?
A: Feature 049 was built without following the SpecKit process it was designed to enable. AI assistants ignored soft warnings 45+ times, resulting in 9 documented failures, 4 weeks of wasted development time, and a 30% contract test failure rate. The real-world costs prove why enforcement is necessary. Q: How do I know my spec is good enough to proceed?
A: Your spec-certificate.json file contains the verdict. You need an overallScore of 80 or higher (B+ grade), zero criticalIssues, and a valid certificate file. The system validates these automatically when you try to run /speckit.plan. Q: What gets logged in the audit trail?
A: Every workflow transition, including phase changes, blocked attempts, validation failures, and certificate generations. The audit log tracks feature ID, phases, timestamps, and the specific blockers that stopped progression. Query the audit endpoint to see compliance history.

​
Troubleshooting

Issue: “Run /speckit.specify first” error when running /speckit.plan
Solution: You don’t have a spec-certificate.json file yet. Run /speckit.specify to generate your spec and automatically create the certificate. The certificate must exist before planning can start. Issue: “Grade below B+ (score < 80)” blocks planning
Solution: Your spec quality is insufficient. Review the issues listed in your spec-certificate.json file under verificationSummary. Fix the identified problems in your spec.md file, then run /speckit.specify again to regenerate the certificate. Issue: “Critical issues detected” prevents progression
Solution: Check the criticalIssues count in your spec-certificate.json. Critical issues include missing sections, contradictory requirements, or undefined terms. Address each critical issue listed in the certificate before attempting to proceed. Issue: Legacy TSD documents detected but cannot convert
Solution: The conversion tool extracts requirements only. If your TSD contains mostly design details (tech stack, API endpoints, architecture), you’ll need to manually write requirements in spec.md format. Use the extracted sections as reference, then run validation. Specification Management (/specification): After your spec passes quality gates, use this feature to track versions, add clarifications, and generate PDF exports. Your validated spec becomes the single source of truth for development. Planning Artifact Review (/sherpaplanningreview): Once /speckit.plan succeeds, Sherpa experts review your planning artifacts against the validated spec. This feature ensures implementation plans match your certified requirements. Analytics Dashboard (/analyticsdashboard): Track compliance metrics, view process violations, and see ROI calculations comparing SpecKit vs. non-SpecKit workflows. Use this to justify investment in quality processes.