U Spec Review

SKILL: Specification Review

Purpose

Provide the Spec Reviewer with checklists and objective criteria for evaluating specs.

Checklist -- OpenAPI

Structure

• [ ] openapi version present and >= 3.0.0
• [ ] info with title, version, and description
• [ ] servers with at least 1 entry
• [ ] All $ref resolve correctly
• [ ] No orphan schemas (defined but not referenced)

Endpoints

• [ ] Every endpoint has a unique operationId
• [ ] Every endpoint has tags, summary, description
• [ ] HTTP verbs are correct:
• GET: read-only, no state change
• POST: creation or named action (e.g., /archive, /cancel)
• PUT: full replacement of resource
• PATCH: partial update or state transition
• DELETE: permanent removal only — soft delete must use PATCH or POST
• [ ] Responses cover: 200/201, 400, 401, 404, 422, 500 (as applicable)
• [ ] Error response follows standard ErrorResponse schema
• [ ] example present in every response

Schemas

• [ ] required explicit in every schema
• [ ] Every field has type and description
• [ ] Dates use format: date-time, IDs use format: uuid
• [ ] Enums documented
• [ ] No duplicate schemas (use $ref)

Security

• [ ] securitySchemes defined if needed
• [ ] security applied to endpoints that require auth
• [ ] Public endpoints have explicit security: []

Checklist -- .spec.md

Completeness

• [ ] Overview with 3-5 sentences
• [ ] Actors table with permissions
• [ ] At least 1 UC with main flow + alternative flow
• [ ] Every UC references an endpoint (operationId)
• [ ] Errors cover all status >= 400 from openapi.yaml
• [ ] Out of Scope present
• [ ] Changelog present

Consistency UC OpenAPI

• [ ] Every endpoint has at least 1 UC
• [ ] Every UC references a valid operationId
• [ ] UC parameters match the schema
• [ ] UC errors match the endpoint’s status codes

Writing Quality

• [ ] No ambiguous terms ("may", "generally", "adequate", "etc.")
• [ ] Business rules are testable and objective
• [ ] Preconditions are programmatically verifiable
• [ ] Postconditions describe an observable change

Ambiguity Detection

| Forbidden term | Replace with | |----------------|-------------| | "may" / "might" | "must" (mandatory) or "optionally" | | "generally" | List all cases | | "adequate" | Objective criteria | | "etc." | List all items | | "similar to" | Reference specific spec | | "soon" | Specific version or Out of Scope |

Severity Levels

| Level | Criterion | Action | |-------|----------|--------| | Blocking | Contradiction, endpoint without UC, invalid schema | REJECTED | | Major | Ambiguity in business rule, unmapped error | REVISION REQUIRED | | Minor | Typo, short description, missing example | Fix and document |

Report Format

# Review: {domain} v{version}
> Reviewer: Spec Reviewer | Date: {date}
> Status: APPROVED | REJECTED | REVISION REQUIRED

## Summary
{1-2 sentences}

## Issues Found
| # | File | Location | Severity | Description | Suggestion |
|---|------|----------|----------|-------------|------------|

## Automatic Corrections Applied
| # | File | What was corrected |
|---|------|--------------------|

## Approval
- [ ] OpenAPI valid
- [ ] UC  endpoints coverage complete
- [ ] Error codes in global catalog
- [ ] No blocking ambiguities

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zig999
• Source: zig999/siegard-code
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.