Merge branch 'feature/phase-1-technical-decision-process' into develop

docs/DECISION_PROCESS.md

@@ -0,0 +1,55 @@
+# 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.

docs/PHASE_1.md

@@ -28,6 +28,7 @@ Until the phase-1 decision framework is complete, do not:
 
 Phase 1 should produce:
 - a maintained phase-1 decision plan
+- a documented technical decision process
 - a central architecture overview document
 - a set of ADRs covering major technical choices
 - clear implementation preconditions for the next phase
@@ -37,15 +38,17 @@ Phase 1 should produce:
 Make decisions in this order:
 
 1. Define the required decision areas.
-2. Record the ADR process and naming conventions.
+2. Record the technical decision process and evaluation criteria.
-3. Establish the architecture overview and its relationship to ADRs.
+3. Record the ADR process and naming conventions.
-4. Document major technical decisions in ADRs.
+4. Establish the architecture overview and its relationship to ADRs.
-5. Confirm that implementation-critical choices are explicit and aligned.
+5. Document major technical decisions in ADRs.
+6. Confirm that implementation-critical choices are explicit and aligned.
 
 ## Exit Criteria for Phase 1
 
 Phase 1 is complete when:
 - the decision framework is documented
+- the technical decision process is documented and usable
 - the architecture overview exists and points to ADRs
 - required major technical decisions are recorded as ADRs
 - implementation can begin without relying on undocumented assumptions

docs/adr/README.md

@@ -11,6 +11,8 @@ Create an ADR when a decision:
 - changes implementation constraints for future work
 - needs durable reviewable documentation in the repository
 
+Before an ADR is accepted, compare alternatives using the technical decision process in `docs/DECISION_PROCESS.md`.
+
 ## Minimum ADR Template
 
 Each ADR should include at least:
@@ -18,6 +20,7 @@ Each ADR should include at least:
 - status
 - date
 - context
+- options considered
 - decision
 - consequences
 
@@ -33,6 +36,10 @@ Minimal example:
 
 What problem or uncertainty is being resolved?
 
+## Options Considered
+
+What meaningful alternatives were compared and why?
+
 ## Decision
 
 What was chosen?
@@ -61,4 +68,4 @@ ADR-0002-another-decision.md
 
 ## Relationship to Implementation Tasks
 
-Implementation tasks should follow documented ADRs when they depend on architecture decisions. If an implementation task exposes a new major technical decision, record the decision first or explicitly resolve it as part of the task before implementation proceeds.
+Implementation tasks should follow documented ADRs when they depend on architecture decisions. If an implementation task exposes a new major technical decision, evaluate the options first, then record the accepted outcome in an ADR before implementation proceeds.