55-Decision & Change Log Template v1.0 | Chapter 3 Record Structure (Human-Readable + Machine-Readable)

Home ／ Docs-Technical WhitePaper ／ 55-Decision & Change Log Template v1.0

Chapter 3 Record Structure (Human-Readable + Machine-Readable)

I. Chapter Goals & Boundaries (Mandatory)

• One Decision Record (DR) serves human and machine consumers simultaneously: human—for decision, communication, and archiving; machine—for validation, search, statistics, and audit export.
• This chapter defines field list, value constraints, minimum required set, state machine & gates alignment, sample snippets, and export formats (YAML/JSON equivalence).

II. Human-Readable Structure (Mandatory, fixed order)

• Cover & Abstract: DR ID, title, status, requester & date, abstract.
• Problem / Motive: scenario, triggers, boundaries, non-goals.
• Alternatives & Evidence: ≥2 comparable options, assumptions/constraints, evidence list & sources.
• Impact Assessment: objects × dimensions (performance/cost/time/risk/dependencies), priority & scope.
• Decision & Non-Do List: ruling, coverage, exceptions, exit conditions.
• Rollback Design: monitoring metrics & thresholds, triggers, rollback steps, recovery criteria.
• Implementation & Verification: milestones, resources, verification scripts & benchmarks, gates.
• References & Notes: cite with “Volume + Version + Anchor (S/P/M/I)”; machine see aligns with human text.

III. Machine-Readable Structure (Mandatory: schema & minimums)

• Identity & Meta (required): id, title, status, requester, created_at.
• Decision Area (at least one): options, decision.
• Validation Area (recommended required): impact, verification, rollback, references.see.
• State Machine & Gates (auto/manual compatible): sign_chain.states, sign_chain.transitions.

IV. Field List & Constraints (copy-ready)

V. Machine-Readable Schema (YAML; JSON equivalent)

decision_record:

id: "DR-2025-0001"

title: ""

status: "Draft" # Draft/Review/Approved/Implemented/Verified/Archived/RolledBack

requester: { name: "", role: "Requester" }

approvers: [{ name: "", role: "Approver" }]

created_at: "YYYY-MM-DD"

effective_at: "YYYY-MM-DD"

scope: ["volume/module/artifact"]

motive: "Problem & motive (structured paragraph)"

options:

- name: "Option A"

assumptions: []

pros: []

cons: []

- name: "Option B"

assumptions: []

pros: []

cons: []

decision: "Decision & non-do (structured paragraph)"

rollback:

triggers: ["metric@threshold@window"]

steps: ["rollback step 1","rollback step 2"]

impact:

dimensions: ["performance","cost","time","risk","dependencies"]

dependencies:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

verification:

gates: ["gate_latency<…","gate_accuracy>…"]

regression_suite: ["dataset@version","script@commit"]

references:

see:

- "EFT.WP.Core.Terms v1.0:P10-3"

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

- "EFT.WP.Core.DataSpec v1.0:I30-2"

export:

artifacts: ["yaml","json","pdf"]

sign_chain:

states: ["Draft","Review","Approved","Implemented","Verified","Archived","RolledBack"]

transitions:

- { from: "Draft", to: "Review", gate: ["completeness_check","see_refs_present"] }

- { from: "Review", to: "Approved", gate: ["risk_accepted","consistency_ok"] }

- { from: "Approved", to: "Implemented", gate: ["plan_ready","resources_locked"] }

- { from: "Implemented", to: "Verified", gate: ["verification_pass","regression_ok"] }

- { from: "Verified", to: "Archived", gate: ["audit_ok","export_artifacts"] }

- { from: "Implemented", to: "RolledBack", gate: ["trigger_threshold","rollback_plan_ready"] }

VI. Human × Machine Alignment (Mandatory mapping)

VII. Minimal Required Example (copy-ready)

decision_record:

id: "DR-2025-0123"

title: "Unify T_arr to the general form"

status: "Review"

requester: { name: "Alice Zhang", role: "Requester" }

created_at: "2025-09-27"

motive: "Cross-volume inconsistency in arrival-time expressions affects reproducibility; unify the caliber."

options:

- name: "A - Constant factored"

assumptions: ["c_ref constant within segment"]

pros: ["Concise"]

cons: ["Sensitive to spatial drift in c_ref"]

- name: "B - General form"

assumptions: []

pros: ["Handles spatially varying c_ref and n_eff"]

cons: ["Slightly higher complexity"]

decision: "Adopt general form: T_arr = ( ∫ ( n_eff / c_ref ) d ell ); record exceptions where factoring is required."

impact:

dimensions: ["performance","risk","dependencies"]

dependencies:

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

rollback:

triggers: ["gate_accuracy<0.98@7d"]

steps: ["Revert to A - constant factored","Sync export templates"]

verification:

gates: ["gate_accuracy>=0.99@CMB-Set","gate_latency<=2h@pipeline"]

regression_suite: ["cmb_set_v3","arrive_time_check.py@a1b2c3"]

references:

see:

- "EFT.WP.Core.Terms v1.0:P10-3"

- "EFT.WP.Core.Equations v1.1:S20-1"

- "EFT.WP.Core.Metrology v1.0:check_dim"

VIII. Field Validation Rules (regex/enums/consistency, Mandatory)

• ID: ^DR-[0-9]{4}-[0-9]{4}$
• Status: status ∈ {Draft,Review,Approved,Implemented,Verified,Archived,RolledBack}
• References: references.see[*] = "^EFT\.WP\.[\w\.]+ v\d+\.\d+(?:\.\d+)?:[PSMI]\d+(?:-\d+)?$"
• Dates: created_at ≤ effective_at (if present)
• Options: if decision present, options may be ≥1; if decision empty, options must be ≥2
• Gates: each verification.gates[*] includes metric + comparator + threshold + optional window

IX. Export & Audit (minimum requirements)

• Artifacts: yaml/json/pdf. PDF contains cover, signature page, body, appendices; YAML/JSON serve automated audits and replay.
• Audit focus: unique ID, traceable FSM, quantifiable gates, parsable references, complete impact & rollback loop.

X. Sample Prose Snippets (human text × aligned citations)

• Arrival-time caliber: See 《EFT.WP.Core.Equations v1.1》 Ch.2 S20-1; adopt T_arr = ( ∫ ( n_eff / c_ref ) d ell ); path gamma(ell) and measure d ell defined in “Implementation & Verification”.
• Dimensional check: See 《EFT.WP.Core.Metrology v1.0》 Ch.1–3, check_dim.
• Data contract: See 《EFT.WP.Core.DataSpec v1.0》 I30-*; export fields align with export.artifacts.