Richer Spec Validation & Tooling

[clay-good]

Note

Moved from issue #431, originally opened by @mhingston on 2026-01-02. Continuing the conversation here in Discussions — the original issue thread (including any comments) stays available at #431 for the record.

---

Feature Request: Richer Spec Validation & Tooling

Problem Description

Current validation checks are structural (Schema-aware) but lack semantic depth. Specs can be syntactically correct but ambiguous, underspecified, or inconsistent in style.

Proposed Solution

1. Schema-aware Validation: Extend validation to semantic scenarios, check for edge case coverage.
2. Ambiguous Terms Detection: Warn on terms like "should", "may", "could" in requirements (enforce "SHALL/MUST").
3. Underspecified Checks: Warn if requirements lack scenarios or acceptance criteria.
4. Automated Quality Rules: Lint specs for completeness and cohesion.

Benefits

• Catches gaps early in the design phase.
• Ensures consistency across large spec suites.
• Reduces "prompt drift" when specs are passed to AI assistants.

Industry Inspiration

• Traycer: "Automated quality rules" - linting specs for completeness and testability.

Related Issues

• Feature request: Include acceptance verification instructions for each task in AGENTS.md prompts #345: Feature request for including acceptance verification instructions. This aligns with our "Underspecified Checks".