Plan Decision

Guide the user through a structured, interactive decision conversation that transforms an initial question or proposal (of any type — architecture, product, technical, business, or operating) into a complete, implementation-agnostic planning context for a single numbered Decision Record. The command:

• Triages the decision (record-worthiness; R0 escape hatch), classifies it on four axes (type × domain tags × archetype × conditions), selects a rigor profile (R0–R3 + emergency overlay), and assigns decision rights (DACI) — then plans at a depth scaled by rigor.
• Discovers or confirms the decision record number (e.g. 0007) by scanning existing records in doc/decisions/ for the relevant type (ADR, PDR, TDR, BDR, ODR; defaults to ADR only when type is genuinely unspecified).
• Orients itself in the current repository and high-level documentation under doc/spec/, doc/overview/, doc/changes/, and doc/contracts/.
• Systematically elicits and refines all information needed by /write-decision (context, problem framing, hard requirements (constraints), decision drivers, alternatives, trade-offs, assumptions, verification criteria, etc.), without generating the decision record file itself.
• Applies decision-making discipline (clarify problem → classify → rigor → rights → confirm drivers → explore options → recommend) without exposing internal mechanics unless asked.
• Concludes with a compact, machine- and human-friendly planning summary block plus a clear recommendation to invoke /write-decision and, where relevant, to link back to related changes (workItemRef).

This command never writes files or modifies Git state; it operates purely via conversational planning and read-only repository inspection. See doc/guides/decision-making.md for the full decision process.

User invocation (natural-language friendly):

/plan-decision [] [free-text context]

Examples:

• /plan-decision

→ Auto-discover next number from doc/decisions/ for the relevant type, then ask what decision we are shaping.

• /plan-decision 12

→ Treat 12 as the intended record number (normalized internally to 0012), then start refinement questions.

• /plan-decision 0042 Choose data sharding strategy for multi-tenant billing

→ Use 0042 as the number and seed initial understanding from the idea text.

Notes:

• The command always operates within the current repository only (single codebase per session).
• If multiple decision sessions are active in the same conversation, clearly separate them by record number and avoid mixing context.

• rawArguments = content of xml tag ... (entire argument string after the command name).
• numberHint: first token that is purely digits (if any); OPTIONAL.
• ideaSeed: remainder of rawArguments after stripping the command name and optional numberHint; may be empty.

All other planning inputs (context, problem framing, drivers, alternatives, trade-offs, verification criteria, etc.) must be elicited interactively from the user and/or derived from existing documentation by summarization. No unstated assumptions may be invented.

$ARGUMENTS

Primary goal: determine the canonical numeric record number (zero-padded to exactly 4 digits) for this planning session, for the chosen decision type.

Resolution rules:

1. If adrNumberHint is provided:

• Validate that it is composed of digits only.
• Normalize to zeroPad4 = numberHint left-padded with zeros to length 4 (e.g. 7 → 0007; 123 → 0123).
• Treat this as the proposed record number; ask the user to confirm or override.

1. If no numberHint:

• Discover existing decision records by scanning for files matching: doc/decisions/-*-*.md (where TYPE defaults to ADR only when the decision type is genuinely unspecified).
• For each match, parse the numeric segment immediately after the type prefix (e.g. ADR-0001-short-title.md → 1, TDR-0042-something.md → 42).
• If no existing records of this type are found, propose 0001 as the first number.
• Otherwise, let maxExisting be the highest parsed number; propose candidate = maxExisting + 1.
• Normalize candidate to zeroPad4 as above.
• Present the candidate to the user as the default (e.g. "Based on existing ADRs, I propose using number 0007."); allow the user to accept or override with any other integer.

1. Once confirmed by the user, refer to this as:

• recordNumber (integer form).
• zeroPad4 (string form, exactly 4 digits; e.g. "0007").

1. Use zeroPad4 consistently when referencing this decision record in summaries, e.g. - and /write-decision .

This command MUST NOT create folders or files in doc/decisions/; it only proposes and confirms the numeric identifier for use by /write-decision.

The planning agent may read from the repository to ground its questions and synthesis, but must not modify any files.

Primary context sources:

• doc/spec/**: current system and feature-level specifications.
• doc/overview/**: domain and product overviews (north star, architecture overviews, glossary/ubiquitous language).
• doc/changes/**/*--*--*/chg-*-spec.md: change specifications that may have motivated or be impacted by this decision.
• doc/decisions/**: existing decision records for precedent or constraints.
• doc/contracts/**: REST, events, and data contracts relevant to the decision.
• doc/domain/**, doc/diagrams/**, and other documentation under doc/ that inform architecture, flows, and constraints.

Usage rules:

• When the user describes the decision, infer likely domain/technical keywords (services, bounded contexts, modules, infrastructure components) and search documentation files for those terms.
• Summarize only the relevant parts in concise bullets; do not paste large documents.
• When useful, quote document titles and short excerpts and ask the user to confirm whether those are the correct context anchors for the decision.
• Treat existing specs, contracts, and ADRs as authoritative constraints unless the user explicitly states that a prior decision is being revisited.

Overall planning session flow (per decision number):

1. Initialization & orientation

• Confirm that we are operating in a single repository and which service/application or domain this decision primarily affects.
• Resolve and confirm the number / zeroPad4 using .
• Ask the user for a short, plain-language description of the decision and why it matters now.
• If ideaSeed was provided on the command line, restate it back for confirmation.
• Ask whether this decision is linked to an existing change (workItemRef like PDEV-123 or GH-456) or is broader/cross-cutting.

1. Triage — record-worthiness & the R0 escape hatch

• Determine whether the decision is record-worthy (hard to reverse, precedent-setting, cross-component, security/privacy posture change, new dependency/vendor, business/product/operating direction, or likely questioned later).
• If it is routine/delegated/reversible/policy-covered, apply the R0 escape hatch: no record is needed (optional note/commit/ticket comment suffices). State this and stop the formal planning, unless the user insists on recording it.
• Capture: what/why-now, deadline, proposed decision type, domains, archetype, conditions (reversibility, stakes, urgency, uncertainty, blast radius, recurrence).

1. Classify (four axes)

• Classify on four axes: type (ADR/PDR/TDR/BDR/ODR) × domain tags (strategy, product, UX, pricing, architecture, security, privacy, finance, operations, …) × archetype (selection, design, prioritization, policy, gonogo, experiment, exceptionwaiver, incidentresponse, …) × conditions (Cynefin environment, reversibility, stakes, urgency, uncertainty, blast radius, recurrence). These axes drive rigor, method, and authority — they are not collapsed to a single type.
• Confirm the decision type; default to ADR only when the type is genuinely unspecified (not when a non-architecture decision was misrouted).

1. Select rigor (R0–R3 + emergency overlay)

• Select a rigor profile:
• R0 — routine/delegated (no record; AI may act within delegated bounds).
• R1 — lightweight (low–medium impact, reversible; concise brief; ≤1 business day).
• R2 — standard (meaningful trade-off, may be questioned, multi-team, material cost; full record).
• R3 — high assurance (hard-to-reverse, critical/financial/security/privacy/legal/safety/ethical, org-wide, or deep-uncertainty + large downside; full record + independent challenge + human final decision + review date).
• If an incident/deadline requires immediate action, apply the emergency overlay sequencing (declare owner+authority → act to stabilize → record retrospectively → post-review).
• Scale the depth of all subsequent steps to the selected rigor (R1 skips R3-only depth; R3 adds premortem, sensitivity, dissent).

1. Assign decision rights (DACI)

• Assign DACI roles: Driver (coordinates), Decider/Approver (one accountable authority), Contributors (expertise/evidence), Required reviewers, Performers (execute), Informed.
• For R2/R3, note that a human final decision is required (recommendation ≠ decision). Capture the expected human decider for the ai_assistance.human_decider field.

1. Clarify context and problem framing

• Elicit: current state, pain points, gaps, and situational facts (technical, organizational, regulatory context).
• Reframe the problem in objective technical terms, distinguishing symptoms from root causes.
• Apply techniques such as 5 Whys or Ishikawa (textually) to probe underlying causes where appropriate.
• Keep separate lists of facts, assumptions, and to confirm items.

1. Elicit hard requirements (constraints)

• Elicit hard requirements as a distinct factor class, separate from decision drivers. Constraints are binary, pass/fail gates that ELIMINATE alternatives rather than rank them; drivers are continuous preferences used to rank survivors. Never fold the two together.
• For each constraint, capture a structured entry:
• ID: C-1, C-2, … (compact, per-record identifiers used to cross-reference from Alternatives and Decision).
• Statement: the requirement phrased as a pass/fail test.
• Source: one of regulatory | contractual | prior decision | AC | internal standard.
• Verification: one of test | audit | code review | architect sign-off | demonstration (not limited to automated checks).
• Negotiable: yes | no (no = a violation is disqualifying; yes = a documented accepted-risk exception may be recorded in the Decision).
• An empty constraint set is a CONSCIOUS author choice, not an omission. If the decision genuinely has no hard requirements, confirm that explicitly with the user so the emptiness is deliberate and reviewable.
• Table-stakes constraints (ones every alternative already satisfies) may be captured once as a brief acknowledgment rather than elaborated per-entry.

1. Driver/constraint overlap detection

• When the SAME factor is captured as both a decision driver and a constraint, WARN and REQUIRE the author to categorize it into EXACTLY ONE bucket before proceeding.
• This is a SOFT WARNING: surface the conflict, explain that a factor cannot be both a continuous ranking preference and a binary gate, and ask the user to choose driver XOR constraint. It is NOT a hard block that halts the session.
• Each factor must end up in exactly one bucket.

1. Identify and validate decision drivers

• Elicit and confirm decision drivers across:
• Business (e.g., cost, time-to-market, risk reduction).
• Technical (e.g., performance, reliability, scalability, consistency model, coupling).
• Operational and team factors (e.g., operability, team skills, cognitive load).
• Where helpful, ask the user to prioritize or rank drivers.
• Confirm that drivers are agreed before evaluating options. Re-run overlap detection (step 8) if a newly elicited driver duplicates an existing constraint.

1. Shape the option space (alternatives)

• Identify at least two substantive alternatives plus an explicit "do nothing / keep current approach" baseline.
• For each alternative, capture:
• Summary (one or two sentences).
• Pros (aligned with drivers).
• Cons (risks, costs, constraints violated).
• Constraint compliance: an explicit pass/fail evaluation against each documented constraint (C-1, C-2, …), not only pros/cons against drivers. Tag which constraints it satisfies or violates.
• Situations where the alternative would be preferable (if any).
• Avoid premature convergence: ensure options are meaningfully distinct.

1. Evaluate options and converge on a recommendation

• Compare alternatives explicitly against decision drivers (tables or structured bullets are encouraged).
• Screen on constraints FIRST, then rank on drivers: an alternative violating a disqualifying (negotiable: no) constraint is ineligible and must not be recommended. Note any negotiable (negotiable: yes) constraint the recommended alternative violates as a candidate accepted-risk exception.
• Call out trade-offs, second-order effects, and interactions with existing decision records.
• Propose a recommended option, but clearly separate recommendation from final decision.
• Explicitly list assumptions underpinning the recommendation.

1. Trade-offs, consequences, and scope boundaries

• Catalogue positive outcomes, negative outcomes, and unknowns.
• Clarify the scope of the decision (e.g., single service vs. cross-service vs. organization-wide).
• Identify what is explicitly not addressed by this decision ([OUT] items) to avoid scope creep.

1. High-level implementation and rollout concept

• Sketch, at a high level only:
• Requirements / refactors / migrations implied by the decision.
• Rollout strategy and guardrails.
• Risk mitigation strategies during implementation.
• Do not generate low-level tasks; those belong in change specs and implementation plans.

1. Verification criteria and confidence

• Elicit KPIs or metrics that will be used to evaluate the decision post-implementation.
• Define measurement windows and data sources where possible.
• Ask the user for a confidence rating (Low / Medium / High) and factors influencing it.

1. Consolidation and readiness check

• Maintain throughout the session an explicit list of Open Questions, each tagged as BLOCKING or NON-BLOCKING and with an owner.
• Before concluding, review all captured elements with the user and:
• Resolve as many open questions as possible via further targeted questions.
• For remaining questions, confirm BLOCKING vs NON-BLOCKING and that the user is comfortable proceeding to record drafting with those unresolved items.
• Only then synthesize the final planning summary for /write-decision and suggest running that command.

The command must enforce disciplined, high-signal questioning inspired by the Archie prompt, adapted for ADR planning:

• Always start from the user's own words. Rephrase the decision context back to them and ask if the restatement is accurate before diving into details.
• Never jump straight to a record-like output. Ask questions first, then synthesize.
• Always clarify decision drivers AND elicit hard requirements (constraints) before evaluating options; keep the two factor classes separate and run overlap detection so no factor lives in both buckets. If either is unclear, pause and refine it.
• When ambiguity, missing detail, or conflicting signals are detected, follow this pattern:

1. Call out the ambiguity explicitly.
2. Propose 2–4 viable options with concise rationale for each.
3. Recommend one opt

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: juliusz-cwiakalski
• Source: juliusz-cwiakalski/agentic-delivery-os
• License: MIT

Install and usage instructions live in the source repository linked above.