om-spec-writing

To write an architectural spec following Martin Fowler's design principles, use a skeleton-first approach to generate a minimal testable structure, enforce Open Questions gating to resolve critical unknowns, and validate data models through compliance checklists. This ensures Fowler-inspired rigor and prevents architectural drift.

The best way to structure an Open Mercato feature spec is to start with a skeleton containing a TLDR and scope, answer explicit Open Questions to gate progress, then advance through research, design, and compliance review using provided templates and checklists to validate data models and commands.

Open Questions gating reduces rework by enforcing explicit Q&A before advancing to research and design phases. This mechanism ensures critical unknowns are resolved early in the architectural spec workflow, preventing costly design changes and compliance failures later in development.

You can use this spec writing workflow for both major system rewrites and new features. The skeleton-first approach and compliance checklists guide architectural spec generation and risk mitigation regardless of whether the project involves building new capabilities or restructuring existing systems.

You do not need external dependencies to generate compliant architectural specs. The workflow is self-contained, providing built-in templates, compliance checklists, and risk mitigation validation tools to guide data model design and documentation consistency without requiring additional software packages.

You should avoid a skeleton-first approach for spec writing when a project lacks defined scope or constraints. The workflow requires describing feature scope upfront to generate the initial spec skeleton, meaning highly ambiguous research tasks without architectural targets will struggle to pass Open Questions gating.