ADR-001: PRD to TypeSpec Transformation Strategy

[ForestMars]

Context

We need to decide on the approach for transforming Product Requirements Documents (PRDs) into TypeSpec model files. This is a critical architectural decision that will impact the entire pipeline.

Decision Options

Option 1: PRD → AST → TypeSpec

• Parse PRD into an Abstract Syntax Tree (AST)
• Transform AST into TypeSpec

Option 2: PRD → TypeSpec (Direct)

• Direct transformation from PRD to TypeSpec

Decision

[To be decided after discussion]

Consequences

Option 1: PRD → AST → TypeSpec

Positive

• Clear separation of concerns
• Structured intermediate representation
• Better error handling and reporting
• More flexible for future transformations
• Easier to validate PRD structure

Negative

• Additional complexity
• Need to maintain AST schema
• Extra transformation step

Option 2: PRD → TypeSpec (Direct)

Positive

• Simpler pipeline
• Fewer moving parts
• Potentially faster processing

Negative

• Less flexibility
• Harder to validate intermediate states
• More complex error handling
• Less reusable for other transformations

Implementation Notes

• If Option 1 is chosen, we will need to:

  • Define AST schema
  • Implement PRD parser
  • Create AST to TypeSpec transformer
  • Add validation at each stage

• If Option 2 is chosen, we will need to:

  • Implement direct PRD to TypeSpec transformation
  • Add comprehensive error handling
  • Ensure robust validation

Related Issues

• PRD Schema Definition #11: PRD Schema Definition

Status

Proposed

[ForestMars]

After reviewing the tradeoffs, I recommend we adopt Option 1: PRD → AST → TypeSpec as the foundation for our transformation pipeline.

While this does add initial complexity, it's not accidental complexity but rather offers major long-term advantages:

• Separation of concerns: Parsing a PRD & generating TypeSpec are fundamentally different tasks. Introducing an intermediate AST layer helps isolate responsibilities. So Uncle Bob won't be tempted to do a morning bathrobe rant about us.
• Improved debuggability†: Intermediate representations allow us to trace and diagnose issues more precisely during parsing or transformation.
• Validation and enforcement: We can validate structure, invariants, and constraints at the AST level before committing to TypeSpec generation.
• Future-proofing: An AST allows us to reuse the parsed model for alternate outputs (e.g. OpenAPI, GraphQL, documentation, visualizations) without re-parsing the PRD.

Option 2 (direct PRD → TypeSpec) is attractive for its simplicity, but becomes brittle as requirements grow. Without an intermediate representation, validation and error handling are harder to implement cleanly, and reuse across toolchains becomes more difficult.

Recommendation: Let's proceed with Option 1 and begin by defining a versioned AST schema aligned to the current PRD structure. This provides a clean foundation for both transformation logic and future extensibility.

† (No, I have never seen anyone use the word debuggability before.)

[ForestMars]

ADR added & merged; this issue can be closed. @cleanupbot