fission-ai__openspec/openspec/changes/archive/2025-08-19-improve-validate-error-messages/tasks.md

1. Enhance validation messages

• 1.1 Add remediation guidance for "No deltas found"
• 1.2 Include file path and structured path in all issues
• 1.3 Improve messages for missing required sections (Spec, Change)
• 1.4 Detect likely misformatted scenarios and warn with conversion example
• 1.5 Add "Next steps" footer for non-JSON invalid output

2. Update constants and helpers

• 2.1 Centralize guidance snippets in VALIDATION_MESSAGES
• 2.2 Provide minimal skeleton examples for missing sections

3. Parser integration

• 3.1 Capture parser-thrown errors and wrap with richer context
• 3.2 Add file/section references to surfaced parser errors

4. Tests

• 4.1 Unit tests for validator message composition
• 4.2 CLI integration tests for human-readable output (with footer)
• 4.3 JSON mode tests (structure unchanged, content enriched)