magnus919_agent-skills/spec-driven-development/references/format-translation.md

Format Translation

Specifications in an AI software factory come in multiple formats. This reference covers how to translate between formats, when to use each, and the conversion loss risks.

Translation Map

                    ┌─────────────────┐
                    │   Human PRD     │ (natural language)
                    └────────┬────────┘
                             │ (lossy — interpretation required)
                             ▼
                    ┌─────────────────┐
                    │   SPEC.md       │ (structured markdown)
                    └───┬──────┬──────┘
                        │      │
               ┌────────┘      └────────┐
               ▼                         ▼
     ┌──────────────────┐     ┌──────────────────┐
     │  Gherkin .feature│     │  OpenAPI YAML     │
     │  (behavior)      │     │  (API contracts)  │
     └────────┬─────────┘     └────────┬─────────┘
              │                        │
              ▼                        ▼
     ┌──────────────────┐     ┌──────────────────┐
     │  Step definitions│     │  Server stubs    │
     │  + test cases    │     │  + client SDKs   │
     └──────────────────┘     └──────────────────┘

Directional Conversions

Human PRD → SPEC.md

Loss: HIGH. A PRD is narrative, opinionated, and assumes shared context. Converting to structured SPEC.md requires:

1. Extract explicit requirements from narrative prose
2. Identify implicit assumptions and make them explicit
3. Decompose vague statements into testable ACs
4. Add edge cases the PRD author didn't consider
5. Define measurable NFR thresholds from qualitative descriptions

Risk: Interpretation loss. The PRD author's intent may not survive the translation. Solution: Send the SPEC.md to the PRD author for Gate 1 review.

SPEC.md → Gherkin Feature Files

Loss: LOW (for behavioral sections). Gherkin maps directly to the user stories and ACs in SPEC.md.

Mapping:

SPEC.md user story → Gherkin Feature (with narrative)
SPEC.md acceptance criteria → Gherkin Scenario (Given/When/Then)
SPEC.md edge cases → Additional Scenarios or Scenario Outline

Translation example:

SPEC.md	Gherkin
"US-001: As a user, I want to reset my password"	Feature: Password Reset
"AC-001.1: Given I'm on the login page, When I click 'Forgot Password', Then I see an email input field"	Scenario: Initiate password reset with Given/When/Then
"Edge case: email not found"	Scenario: Reset with unregistered email

SPEC.md → OpenAPI YAML

Loss: LOW-MEDIUM. The Data Contracts & Interfaces section of SPEC.md maps directly to OpenAPI paths, schemas, and responses.

Mapping:

SPEC.md "Data Contracts" API spec → OpenAPI paths
SPEC.md request/response schemas → OpenAPI components/schemas
SPEC.md auth requirements → OpenAPI securitySchemes
SPEC.md error formats → OpenAPI responses with examples

Translation example:

## Data Contracts

### POST /api/users
- Request: { name: string, email: string }
- Response 201: { id: uuid, name: string, email: string, created_at: datetime }
- Error 409: { error: "email_taken", message: "..." }

→ OpenAPI YAML with the path, requestBody schema, and response schemas for 201 and 409.

Gherkin ↔ OpenAPI (cross-format verification)

Gherkin scenarios can validate OpenAPI contracts and vice versa:

• An OpenAPI 400 response definition implies a Gherkin scenario: "When I send an invalid request, Then I receive 400"
• A Gherkin scenario about successful creation implies an OpenAPI 201 response with a specific schema

Trick: Generate Gherkin scenarios directly from OpenAPI response codes and schemas. Every documented error code should have a corresponding negative test scenario.

SPEC.md → TASK-PLAN.md tasks

Loss: MINIMAL (intentional). Each AC in SPEC.md becomes one or more tasks in TASK-PLAN.md. This is not a lossy conversion — it's a decomposition.

Rule: Every AC must appear in at least one task. The spec-to-tasks.sh script validates this coverage.

SPEC.md → JSON Schema (data contracts)

Loss: NONE for structural types. JSON Schema losslessly represents the type constraints in SPEC.md data contracts.

Mapping:

SPEC.md field type constraints → JSON Schema type/format/enum
SPEC.md required fields → JSON Schema required array
SPEC.md validation rules → JSON Schema pattern/minLength/maxLength

Conversion Ordering

For a new feature, the recommended conversion sequence:

1. Human conversation → SPEC.md (structured markdown)
2. SPEC.md behavioral ACs → Gherkin .feature files (spec-as-tests)
3. SPEC.md data contracts → OpenAPI YAML + JSON Schema (for code gen)
4. SPEC.md → TASK-PLAN.md (for implementation sequencing)

Steps 2 and 3 can happen in parallel since they target different concerns.

Format Selection Guide

Format	Best For	Worst For
SPEC.md (markdown)	Complete spec with all concerns	Machine automation without human review
Gherkin	Behavioral requirements, executable tests	Architecture, NFRs, data contracts
OpenAPI	REST API contracts, client/server code gen	Internal business logic, UI, async events
AsyncAPI	Event-driven systems, message queues	Request/response APIs
JSON Schema	Data validation, type safety	Behavior, orchestration, side effects
Protocol Buffers	High-performance RPC, cross-language schemas	Human readability, quick iteration
TLA+	Distributed systems, protocol verification	Full-system specification, non-critical code

Translation Risks

Conversion	Risk	Mitigation
Human prose → structured spec	Intent loss	Review Gate 1 with domain expert
SPEC.md → Gherkin	ACs that don't map to scenarios	Cover every AC in at least one scenario
SPEC.md → OpenAPI	Missing error paths	Derive error responses from edge cases, not just happy path
Gherkin → step definitions	Brittle UI-coupled steps	Implement at the API/domain layer, not UI layer
OpenAPI → client stubs	Stale SDKs when API changes	Regenerate stubs from spec, keep generation in CI

Brownfield: Reverse-Engineering Specs from Code

When working with existing codebases that have no specs, the conversion direction reverses:

Code → API surface (OpenAPI from routes/swagger/middleware)
Code → Behavioral spec (Gherkin from tests or observed behavior)
Code → Architecture decisions (ADRs from code review & commit history)

This is never lossless. The resulting spec captures what the code does, not what it should do. Treat reverse-engineered specs as starting points for refinement, not ground truth. See ai-factory-pipeline.md for brownfield feature additions.