write-decision

Generate a COMPLETE, rationale-focused Decision Record for a given decision number, strictly from planning-session context and existing documentation. Supports all five decision types: ADR (Architecture), PDR (Product), TDR (Technical), BDR (Business), and ODR (Operational).

User invocation: /write-decision

Inputs other than MUST be sourced from the active technical-decision planning context (especially the <technical_decision_planning_summary> block) and relevant repository docs; NOTHING may be invented.

The resulting decision record becomes the canonical record of the decision and its rationale, and should be linked from related changes and specs.

- number='$1': string — REQUIRED (digits only; will be normalized and zero-padded to 4 digits) - allArguments='$ARGUMENTS': string — starts with number and may be followed by user hints (e.g., title refinements, decision type override) - previous conversation context from /plan-decision planning session, including ``

<directory_rules>

• Normalize number: strip non-digits; pad left with '0' to length 4.
• groupFolder is NOT used; all decision records live directly under doc/decisions/.
• decisionType defaults to ADR; may be overridden to PDR, TDR, BDR, or ODR based on planning context or user input.
• slug = normalized-from-title (lowercase ASCII kebab-case, <=60 chars), derived from the decision title.
• filename = --.md (e.g., ADR-0001-event-bus.md, TDR-0001-state-mgmt.md)
• fullPath = doc/decisions/--.md </directory_rules>

<front_matter_rules> A YAML front matter block MUST precede the decision record body and include at least these keys:

id: - # e.g., ADR-0001, PDR-0001, TDR-0001 decision_type: <adr|pdr|tdr|bdr|odr> created: # UTC date when file is first created decision_date: null | # Date when status changed to Accepted; may be null for Proposed last_updated: # UTC date of last modification status: <Proposed|Under Review|Accepted|Deprecated|Superseded> summary: owners: [] service: <primary impacted service, system, or domain> links: related_changes: ["PDEV-123", ...] supersedes: ["-####", ...] superseded_by: ["-####", ...] spec: ["doc/spec/...", ...] contracts: ["doc/contracts/...", ...] diagrams: ["doc/diagrams/...", ...] decisions: ["-####", ...] # other relevant decision records

Validation:

• id MUST be exactly <TYPE>-<number> where TYPE is ADR/PDR/TDR/BDR/ODR and is the zero-padded string form.
• decision_type MUST be one of: adr, pdr, tdr, bdr, odr (lowercase).
• created and last_updated MUST be valid dates in ISO format YYYY-MM-DD (UTC calendar date).
• On first creation:
  • status MUST be "Proposed".
  • decision_date SHOULD be null (or omitted) until status becomes Accepted.
• owners MUST contain at least one entry (e.g., a team or person handle).
• related_changes MAY be empty; when present, values MUST be valid workItemRef identifiers (e.g., PDEV-123, GH-456).
• Additional front-matter fields allowed by doc/documentation-handbook.md (e.g., tags, security) MAY be added but MUST NOT replace the keys above. </front_matter_rules>

<context_lookup> The decision record generator must base its content on:

• The <technical_decision_planning_summary> block produced by /plan-decision <number> in the current or recent conversation.
• Relevant change specs under doc/changes/**/*--*--*/chg-*-spec.md when related_changes are present.
• Existing decision records under doc/decisions/** referenced from planning context (for supersedes/related decisions).
• Use doc/templates/decision-record-template.md as the structural guide for generating the decision record body.
• System specs under doc/spec/** and contracts under doc/contracts/** where the decision materially affects them.

If a <technical_decision_planning_summary> for this number is NOT available in context, the command MUST:

• Ask the user to either:
  • Re-run /plan-decision <number> and complete the planning summary, OR
  • Provide the missing fields explicitly.
• REFUSE to generate the decision record purely from vague or partial inputs. </context_lookup>

<decision_structure> The decision record markdown body (after front matter) MUST follow this structure and order:

1. # <TYPE>-<number>: <Title>
2. ## Context
3. ## Problem Framing (Clarified)
4. ## Decision Drivers
5. ## Mental Models & Techniques Used
6. ## Alternatives Considered
7. ## Decision
8. ## Trade-offs & Consequences
9. ### Positive Outcomes
10. ### Negative Outcomes
11. ### Unresolved Questions
12. ## Implementation Plan
13. ## Verification Criteria
14. ## Confidence Rating
15. ## Lessons Learned (Retrospective)
16. ## Examples & Usage (Optional)
17. ## References

No extra top-level sections may be introduced before or between these headings. Additional subsections may be added within these sections if they are clearly nested and consistent with the template. </decision_structure>

<authoring_rules>

• Use ONLY planning context and existing documentation; do not invent new requirements, drivers, or constraints.
• "Context" MUST describe the situation (architectural, product, technical, business, or operational as appropriate to the decision type), why the decision is needed now, and relevant constraints.
• "Problem Framing (Clarified)" MUST reframe the user problem in objective technical terms, highlighting underlying causes.
• "Decision Drivers" MUST list explicit, prioritized drivers (business, technical, operational, organizational) that the decision optimizes for.
• "Mental Models & Techniques Used" should summarize which reasoning tools were applied (e.g., First Principles, Inversion, Second-Order Thinking, 5 Whys) as captured in planning.
• "Alternatives Considered" MUST:
  • Include at least two substantive alternatives plus a "do nothing / keep current approach" baseline when applicable.
  • For each alternative, include summary, pros, cons, and why it was rejected or chosen.
• "Decision" MUST:
  • State the final decision clearly.
  • Tie rationale explicitly back to decision drivers.
  • List key assumptions.
• "Trade-offs & Consequences" MUST:
  • Separate positive outcomes, negative outcomes, and unresolved questions.
  • Make second-order and operational consequences explicit where known.
• "Implementation Plan" MUST remain high-level:
  • Requirements, refactors, migrations, rollout concepts, and risk mitigations.
  • NO low-level tasks, file names, or code instructions.
• "Verification Criteria" MUST list concrete KPIs or signals, with targets and timeframes, for evaluating the impact of the decision.
• "Confidence Rating" MUST state Low / Medium / High and be justified by reference to data, precedent, or gaps.
• "Lessons Learned (Retrospective)" MAY initially contain a brief TODO-style note if the decision has not yet been implemented; this section is expected to evolve over time.
• "Examples & Usage (Optional)" MAY be omitted for early decision records, but when present should reference representative scenarios, not code internals.
• "References" MUST link to relevant changes, specs, contracts, decision records, and external sources.
• Where planning context contains explicit labels like FACT, ASSUMPTION, TO CONFIRM, these MAY be retained as bold labels in the ADR where useful. </authoring_rules>

<placeholder_rules>

• Template placeholders such as <...> MUST NOT appear in final decision record content.
• If required information is genuinely unavailable (e.g., decision not yet fully implemented so Lessons Learned are unknown):
  • Use explicit TODO-style sentences (e.g., "TODO: Populate lessons learned after first production rollout.").
  • Add any significant unknowns to "### Unresolved Questions" with owners where possible.
• Under no circumstances may the decision record omit a required section; minimal but honest content is preferred over silence. </placeholder_rules>

1. Read `$1` as rawNumber; normalize to digits-only and zero-pad to 4 digits. 2. Obtain or reconstruct the `` for this number from the planning session or explicit user-provided data. 3. Derive: - decisionType from planning summary `decision_type` field (defaults to ADR if not specified). - Title from planning summary title field. - slugHint from slug_hint or by slugifying the title. - owners, service, labels, related_changes, decision_scope, and other meta fields from the planning summary. 4. Compute slug from title/slugHint; validate length (<=60 chars) and allowed charset (lowercase letters, numbers, hyphens). 5. Compute fullPath = `doc/decisions/--.md` (TYPE from step 3). 6. Determine whether the decision record file already exists: - If it exists: load existing front matter and body; treat this as an UPDATE, preserving historical narrative and only appending/adjusting content where appropriate. - If it does not exist: treat this as a NEW decision record. 7. Construct front matter per : - On creation: set created = today (UTC); last_updated = today; status = Proposed; decision_date = null; decision_type from step 3. - On update: preserve created; set last_updated = today; retain existing status and decision_date unless explicitly overridden by user. 8. Generate or update decision record body using , , and planning context: - For NEW records: synthesize complete sections from planning summary and referenced docs. - For UPDATES: merge new planning information without rewriting historical sections; append to "Unresolved Questions", "Lessons Learned", and "References" instead of erasing prior content. 9. Write decision record markdown to fullPath. 10. Stage ONLY this decision record file. 11. Commit with message: - On creation: `docs(): add --` (e.g., `docs(adr): add ADR-0001-event-bus`) - On update: `docs(): refine --` 12. Stop. Do not modify change specs, implementation plans, or system specs in this command; those are updated via their dedicated commands.

<embedded_template format="markdown">

id: - decision_type: <adr|pdr|tdr|bdr|odr> created: decision_date: last_updated: status: <Proposed|Under Review|Accepted|Deprecated|Superseded> summary: owners:

service: links: related_changes: - supersedes: [] superseded_by: [] spec: [] contracts: [] diagrams: [] decisions: []

-:

Context

Concise description of the technical/architectural situation, triggers for this decision, and relevant constraints.

Problem Framing (Clarified)

Objective reframing of the problem, focusing on underlying causes rather than symptoms.

Decision Drivers

• Business drivers (e.g., cost, time-to-market, risk).
• Technical drivers (e.g., performance, reliability, coupling).
• Operational and organizational drivers (e.g., operability, cognitive load).

Mental Models & Techniques Used

• List of mental models and techniques applied (e.g., First Principles, Inversion, Second-Order Thinking, 5 Whys).

Alternatives Considered

1. Alternative A —

   • Summary:
   • Pros:
   • Cons:
   • Why rejected / chosen:

2. Alternative B —

   • ...

3. Alternative 0 — Do nothing / keep current approach (if applicable)

   • Summary:
   • Pros / Cons compared to other options.

Decision

• Final decision statement.
• Core rationale, explicitly linked to decision drivers.
• Explicit assumptions acknowledged.

Trade-offs & Consequences

Positive Outcomes

• Benefits expected from this decision.

Negative Outcomes

• Known downsides, additional complexity, or risks introduced by this decision.

Unresolved Questions

• Remaining risks, information gaps, or areas requiring validation, each with an owner where possible.

Implementation Plan

1. High-level requirements and refactors implied by the decision.
2. Rollout strategy and guardrails.
3. Risk mitigation during implementation.
4. Design details at the conceptual/architecture level (no low-level tasks or code).

Verification Criteria

• KPIs or metrics to track decision impact.
• Timeframe and tools to validate success or failure.

Confidence Rating

• Confidence: <Low|Medium|High>.
• Factors influencing confidence: data, precedent, validation.

Lessons Learned (Retrospective)

• To be populated as the decision is implemented and observed.

Examples & Usage (Optional)

• Representative flows, configurations, or scenarios where this decision is applied.

References

• Linked change specs, technical docs, diagrams, prior decision records.
• External sources or research influencing the decision.

</embedded_template>

<output_contract>

• Writes exactly one decision record file: <TYPE>-<adrNumber>-<slug>.md.
• File is placed under: doc/decisions/.
• Content follows <decision_structure> and is semantically aligned with doc/templates/decision-record-template.md.
• No <...> placeholders remain; any missing information is called out explicitly as TODO or unresolved questions. </output_contract>

- Directory + filename follow . - Front matter validates per (including allowed value sets and required keys). - Section order EXACT per (no missing / extra top-level sections). - Alternatives section includes at least two real options plus baseline (where applicable). - Decision section clearly references decision drivers. - Verification criteria include measurable targets and timeframes. - No low-level implementation tasks, file paths, or git commands appear in the body. - If confirmUpdate=true (optional future flag), show diff prior to write. - Only the target decision record file is staged & committed; abort if other staged changes exist. - This command formalizes technical and non-technical decisions into repository-native decision records under `doc/decisions/`. - It relies on `/plan-decision` for high-quality planning context; do not bypass planning by inventing content. - After a decision record is Accepted, follow up with `/sync-docs ` (when related to a change) to reconcile `doc/spec/**` and `doc/contracts/**` with the decided approach.