Ref-001: ADR Template Structure & Authoring Process

Type

Reference Documentation

Purpose

Defines the canonical template structure for Architectural Decision Records (ADRs) and the process for generating them within the SEA-Forge™ ecosystem.

Template Structure

Required Fields

Each ADR MUST contain the following sections:

ADR-XXX — [Decision Title]

• Decision: [What was decided]
• Context: [Why this decision was needed, what problem it solves]
• Rationale: [Why this option was chosen over alternatives]
• DX Impact: [How this affects developer experience]
• Trade-offs: [What we gain vs what we lose]

• Status: [Proposed

  Accepted

  Rejected

  Superseded]

• Date: YYYY-MM-DD
• Related Specs: [PRD-XXX, SDS-XXX, TS-XXX]

Authoring Process

Generation Methods

ADRs can be generated through the following approved workflows:

1. Chat Mode Integration
   • Use @workspace #spec.lean for focused ADR generation
   • Use @workspace #spec.wide for comprehensive context-aware ADRs
2. Prompt-Based Generation
   • Execute .github/prompts/spec.plan.adr.prompt.md
   • Ensures consistency and completeness
3. Manual Creation
   • Follow the template structure defined above
   • Ensure all required fields are populated

Status Lifecycle

1
2
3
4
5
Proposed → Accepted
         ↓
      Rejected
         ↓
    Superseded (by ADR-XXX)

Example

See template source for canonical TypeScript strict mode example (ADR-001).

Traceability Requirements

• Each ADR MUST link to related PRDs, SDSs, and Technical Specs where applicable
• Status changes MUST be timestamped
• Superseded decisions MUST reference the replacing ADR