56 lines
2.3 KiB
Markdown
56 lines
2.3 KiB
Markdown
# Technical Decision Process
|
|
|
|
## Purpose
|
|
|
|
This document defines the repeatable process for evaluating technical options during phase 1. It exists to keep decisions consistent, reviewable, and useful for both humans and Codex before implementation begins.
|
|
|
|
## When to Use This Process
|
|
|
|
Use this process when a task needs to compare meaningful technical options or establish implementation guidance for later work. It applies to architecture choices, tooling direction, integration patterns, and other decisions that shape future implementation constraints.
|
|
|
|
## Required Evaluation Criteria
|
|
|
|
Every significant technical decision should evaluate at least:
|
|
- simplicity
|
|
- portability across machines
|
|
- maintainability
|
|
- operational complexity
|
|
- testability
|
|
- developer experience
|
|
- cost
|
|
- risk of lock-in
|
|
- fit for the current project phase
|
|
|
|
Additional criteria may be added when a decision requires them, but the standard set should always be considered first.
|
|
|
|
## Decision Format
|
|
|
|
Each decision should document:
|
|
- the question being decided
|
|
- the options considered
|
|
- the trade-offs for each option
|
|
- the evaluation against the required criteria
|
|
- the preferred option
|
|
- any open assumptions or follow-up constraints
|
|
|
|
The result should be recorded in a repository document that is durable and reviewable. Major accepted decisions should be captured in ADRs.
|
|
|
|
## Acceptance Rule
|
|
|
|
A decision becomes accepted when:
|
|
- the alternatives were compared explicitly
|
|
- the trade-offs were documented clearly
|
|
- the standard evaluation criteria were addressed
|
|
- the chosen option is recorded in the repository
|
|
- the outcome is treated as implementation guidance
|
|
|
|
If those conditions are not met, the decision should remain proposed rather than treated as settled.
|
|
|
|
## Relationship to ADRs
|
|
|
|
ADRs are the durable record for important technical decisions. This process explains how to evaluate options before a decision is accepted. The ADR captures the final accepted outcome, context, and consequences once the decision is ready to guide future work.
|
|
|
|
## Relationship to Implementation Tasks
|
|
|
|
Implementation tasks should follow accepted decisions, not reopen them informally. If a task depends on an unresolved technical choice, the decision should be evaluated and documented first. If implementation reveals a new major choice, pause and record it through this process before proceeding.
|