Spec Standards Review Checklist
Orchestrata Ultimate / Specs / Spec Standards Review Checklist
Verbatim from specs/SPEC_REVIEW_CHECKLIST.md; headings are pushed down one level.
Spec Standards Review Checklist
Comprehensive checklist derived from spec-review/spec-standards.yaml, SPEC_STANDARD.md,
and the four original review scripts. Use this as the single reference when writing or
reviewing any specification in orchestrata-ultimate.
| Check |
ID |
Criteria |
| [ ] |
META-01 |
Spec ID present (XXX-name) |
| [ ] |
META-02 |
Title present |
| [ ] |
META-03 |
Author: Mohamed |
| [ ] |
META-04 |
Status: Draft / In Review / Complete / Deprecated |
| [ ] |
META-05 |
Created date (YYYY-MM-DD) |
| [ ] |
META-06 |
Last Updated date (YYYY-MM-DD) |
| [ ] |
META-07 |
Priority: P0 / P1 / P2 / P3 |
| [ ] |
META-08 |
Version: X.Y.Z (semver) |
| [ ] |
META-09 |
Components listed |
| [ ] |
META-10 |
Dependencies listed |
2. Overview (Required)
| Check |
ID |
Criteria |
| [ ] |
OVR-01 |
What section — what the spec covers |
| [ ] |
OVR-02 |
Why section — motivation and justification |
| [ ] |
OVR-03 |
How section — high-level approach |
3. Terminology / Glossary (std_08)
| Check |
ID |
Criteria |
| [ ] |
TERM-01 |
Terminology / Glossary section present |
| [ ] |
TERM-02 |
All domain-specific terms defined |
| [ ] |
TERM-03 |
Table format: Term / Definition columns |
4. User Scenarios (std_01)
| Check |
ID |
Criteria |
| [ ] |
US-01 |
Minimum 3 user scenarios |
| [ ] |
US-02 |
Format: US-NNN with descriptive title |
| [ ] |
US-03 |
Each has As a [role] |
| [ ] |
US-04 |
Each has I want to [action] |
| [ ] |
US-05 |
Each has So that [benefit] |
| [ ] |
US-06 |
Each has Acceptance Criteria (AC-NNN or bullet list) |
| [ ] |
US-07 |
Acceptance criteria are testable (pass/fail, not vague) |
5. Data Models (std_02)
| Check |
ID |
Criteria |
| [ ] |
DM-01 |
Data Model / Interface Definition section present |
| [ ] |
DM-02 |
JSON Schema for all data structures |
| [ ] |
DM-03 |
Required fields marked |
| [ ] |
DM-04 |
Validation rules included |
| [ ] |
DM-05 |
"type": "object" or type: object schema definitions |
| [ ] |
DM-06 |
Example values for non-obvious fields |
6. Functional Requirements
| Check |
ID |
Criteria |
| [ ] |
FR-01 |
Numbered requirements (FR-001, FR-002, ...) |
| [ ] |
FR-02 |
Each requirement is testable with clear success criteria |
| [ ] |
FR-03 |
No ambiguous language ("should", "might", "probably") |
| [ ] |
FR-04 |
Requirements traceable to user scenarios |
7. Requirement Traceability
| Check |
ID |
Criteria |
| [ ] |
REQ-01 |
Requirements use REQ-NNN-XXX format |
| [ ] |
REQ-02 |
Each requirement maps to a user story (US-NNN) |
| [ ] |
REQ-03 |
Requirements grouped under FR headings |
| [ ] |
REQ-04 |
Checklist format: - [ ] **REQ-NNN-XXX**: description |
8. Error Conditions (std_03)
| Check |
ID |
Criteria |
| [ ] |
ERR-01 |
Error Conditions section present |
| [ ] |
ERR-02 |
Minimum 10 error conditions |
| [ ] |
ERR-03 |
Table format: ID / Condition / Handling |
| [ ] |
ERR-04 |
Error IDs: ERR-001, ERR-002, ... or E-00N |
| [ ] |
ERR-05 |
Edge cases documented |
| [ ] |
ERR-06 |
Failure modes described with recovery actions |
9. API Contracts (std_13)
| Check |
ID |
Criteria |
| [ ] |
API-01 |
API Contracts section present |
| [ ] |
API-02 |
Method signatures for all public interfaces |
| [ ] |
API-03 |
Parameters with types documented |
| [ ] |
API-04 |
Return types documented |
| [ ] |
API-05 |
Interface contracts defined (schema / contract keyword) |
| Check |
ID |
Criteria |
| [ ] |
PERF-01 |
Performance Requirements section present |
| [ ] |
PERF-02 |
Latency targets specified |
| [ ] |
PERF-03 |
Throughput targets specified |
| [ ] |
PERF-04 |
Response time limits defined |
| [ ] |
PERF-05 |
Performance requirement IDs: PR-00N |
11. Non-Functional Requirements (std_09)
| Check |
ID |
Criteria |
| [ ] |
NFR-01 |
Non-Functional Requirements section present |
| [ ] |
NFR-02 |
Security requirements (authentication, authorization) |
| [ ] |
NFR-03 |
Reliability targets |
| [ ] |
NFR-04 |
Scalability considerations |
| [ ] |
NFR-05 |
NFR IDs: NFR-001, NFR-002, ... |
12. Security Requirements
| Check |
ID |
Criteria |
| [ ] |
SEC-01 |
Authentication requirements |
| [ ] |
SEC-02 |
Authorization requirements |
| [ ] |
SEC-03 |
Input validation rules |
| [ ] |
SEC-04 |
Audit logging requirements |
13. Dependencies (std_06)
| Check |
ID |
Criteria |
| [ ] |
DEP-01 |
Dependencies section present |
| [ ] |
DEP-02 |
Table format: Dependency / Version / Purpose |
| [ ] |
DEP-03 |
Environmental assumptions stated |
| [ ] |
DEP-04 |
Prerequisites listed |
14. Testing Requirements (std_05)
| Check |
ID |
Criteria |
| [ ] |
TEST-01 |
Testing Requirements section present |
| [ ] |
TEST-02 |
Test scenarios defined (TC-00N) |
| [ ] |
TEST-03 |
Coverage targets stated |
| [ ] |
TEST-04 |
Quality gates defined |
| [ ] |
TEST-05 |
Test strategy described |
15. Diagrams (std_07)
| Check |
ID |
Criteria |
| [ ] |
DIAG-01 |
At least one Mermaid diagram |
| [ ] |
DIAG-02 |
Sequence diagrams for key flows |
| [ ] |
DIAG-03 |
Class diagrams for data models |
| [ ] |
DIAG-04 |
Flowcharts for decision logic |
16. Examples (std_10)
| Check |
ID |
Criteria |
| [ ] |
EX-01 |
Examples section present |
| [ ] |
EX-02 |
Request/Response examples |
| [ ] |
EX-03 |
JSON code blocks with sample payloads |
| [ ] |
EX-04 |
Multiple examples covering happy path and error cases |
17. Versioning (std_11, std_14)
| Check |
ID |
Criteria |
| [ ] |
VER-01 |
Spec Version stated |
| [ ] |
VER-02 |
Revision History section |
| [ ] |
VER-03 |
API Version metadata (if applicable) |
| [ ] |
VER-04 |
Backward compatibility notes |
18. Definition of Done (std_12)
| Check |
ID |
Criteria |
| [ ] |
DOD-01 |
Definition of Done section present |
| [ ] |
DOD-02 |
Done criteria are concrete and verifiable |
| [ ] |
DOD-03 |
Completion criteria checklist format |
19. Observability (std_15)
| Check |
ID |
Criteria |
| [ ] |
OBS-01 |
Observability section present |
| [ ] |
OBS-02 |
Logging requirements |
| [ ] |
OBS-03 |
Metrics to collect |
| [ ] |
OBS-04 |
Tracing requirements |
| [ ] |
OBS-05 |
Health check endpoints |
Quality Gate Summary
Must Have (spec fails review without these)
- All metadata fields (META-01 through META-08)
- Overview with What/Why/How (OVR-01 through OVR-03)
- 3+ user scenarios with acceptance criteria (US-01 through US-07)
- JSON schemas for all data models (DM-01 through DM-04)
- 10+ error conditions (ERR-01 through ERR-06)
- API contracts for all interfaces (API-01 through API-05)
- Security requirements (SEC-01 through SEC-04)
- Dependencies documented (DEP-01 through DEP-04)
Should Have
- Performance benchmarks (PERF-01 through PERF-05)
- Diagrams (DIAG-01 through DIAG-04)
- Multiple examples (EX-01 through EX-04)
- Observability (OBS-01 through OBS-05)
- Testing requirements (TEST-01 through TEST-05)
Nice to Have
- Definition of Done (DOD-01 through DOD-03)
- Revision History (VER-02)
- Backward compatibility notes (VER-04)
Automated Validation
Run the consolidated review script to validate any spec:
# Single spec
uv run python specs/spec-review/review_spec.py specs/028-llm-client/spec.md
# All specs
uv run python specs/spec-review/review_spec.py --all
# JSON output
uv run python specs/spec-review/review_spec.py --all --json
# With requirement parsing
uv run python specs/spec-review/review_spec.py specs/028-llm-client/spec.md --requirements
Section Order (Canonical)
- Metadata
- Overview (What / Why / How)
- Terminology
- User Scenarios
- Data Models
- Functional Requirements
- Error Conditions
- API Contracts
- Non-Functional Requirements
- Technical Design
- Examples
- Security
- Governance
- Dependencies
- Testing
- Observability
- Integration Points
- Definition of Done
- Revision History
Derived from: validate_spec_standards.py, verify_all_specs.py, parse_spec_requirements.py, verify_requirements.py, spec-standards.yaml, SPEC_STANDARD.md