Purpose
Specifications exist to formalize approved engineering knowledge into a single, authoritative form. A Specification is the canonical source of engineering guidance for the domain it governs: once accepted, it is what AAOE work is expected to follow, superseding informal understanding or prior practice.
This specification governs the lifecycle of specifications themselves: how they are created, evolved, versioned, superseded, and retired.
Principles
- Specifications represent approved knowledge, not proposals.
- Every specification has a unique identity, independent of its content.
- Specifications evolve incrementally rather than being replaced wholesale.
- History is preserved; nothing is silently overwritten.
- Supersession is explicit, never implied.
- Specifications remain traceable to the discoveries and architectural decisions that justified them.
Specification States
Draft
↓
Accepted
↓
Revised
↓
Superseded
↓
Archived- Draft — introduced and under refinement; not yet authoritative.
- Accepted — approved and in effect as canonical guidance.
- Revised — an accepted specification has been incrementally updated while retaining its identity and history.
- Superseded — replaced by a newer specification that now carries authority in its place.
- Archived — retained for historical reference only; no longer consulted for current guidance.
Lifecycle
Discovery
↓
Architectural Decision
↓
Draft Specification
↓
Review
↓
Accepted Specification
↓
Revision
↓
Superseded
↓
Archived- Discovery — an observation is captured, as defined by the Discovery Lifecycle.
- Architectural Decision — the discovery is evaluated and, if warranted, decided upon.
- Draft Specification — the decision is formalized into a draft specification.
- Review — the draft is evaluated for completeness, consistency, and fidelity to the architectural decision behind it.
- Accepted Specification — the specification becomes canonical guidance.
- Revision — the accepted specification is incrementally updated as understanding matures.
- Superseded — a later specification takes over its authority.
- Archived — the specification is retained for history once no longer in effect.
Versioning
- Major versions represent significant semantic evolution of a specification's guidance.
- Minor versions represent compatible refinements that do not change its meaning.
- Version history remains preserved alongside the specification.
- Every revision is traceable to the decision that produced it.
Relationships
- Discoveries feed Architectural Decisions with evidence.
- Architectural Decisions determine whether a Specification should exist or change.
- Specifications formalize accepted Architectural Decisions into authoritative guidance.
- Work Orders are scoped in accordance with applicable Specifications.
- Implementation Reports are evaluated, in part, for consistency with the Specifications relevant to the work performed.
Governance
- Specifications evolve through governance, not unilateral edits.
- Specifications are never modified without traceability to the decision behind the change.
- Superseded specifications remain part of engineering history rather than being deleted.
- Accepted specifications are canonical until explicitly superseded.
Outputs
- New specifications.
- Revised specifications.
- Superseded specifications.
- Canonical engineering knowledge.
Future Evolution
Specification management may evolve — for example, in how review, acceptance, or supersession are carried out — while preserving traceability and governance as its foundation.