decision-workflow

---
name: decision-workflow
description: |
  Create a structured decision workflow for design-heavy repositories. Use when
  the user needs to compare options with tradeoff analysis, assign a decision
  owner, and track consequences. Produces a DW-NNN document with options, pros,
  cons, and tradeoff analysis.
---

# decision-workflow

## Purpose

Produce a decision document that records a pending or completed design decision with enough structure that future readers understand what was decided, why, what was rejected, and what consequences follow.

## Required Reads

- `.agents/project.json` -- confirm design facet is enabled
- `.agents/pm/pm-decisions.md` -- existing project decisions for context and to avoid duplication
- `docs/` directory listing -- locate related design documents
- `.agents/pm/pm-current-state.md` -- understand current project state

## Procedure

1. Ask the user to describe the decision topic. Collect: the question being decided, the context or trigger, and the decision owner (person or role responsible for the final call).
2. Generate a decision ID using the format `DW-<NNN>` where NNN is the next sequential number based on existing decisions in `docs/decisions/`.
3. Create the decision file at `docs/decisions/DW-<NNN>-<slug>.md`.
4. Write the document with these sections:
   - **Status**: one of `proposed`, `accepted`, `superseded`, `rejected`.
   - **Context**: what prompted this decision and why it matters now.
   - **Options**: list each option with a description, pros, and cons.
   - **Tradeoff Analysis**: compare options on the dimensions that matter (cost, risk, complexity, reversibility).
   - **Decision**: the chosen option (leave blank if status is `proposed`).
   - **Decision Owner**: who makes or made the final call.
   - **Rationale**: why this option was chosen over the alternatives.
   - **Consequences**: what changes, follow-up work, or constraints result from this decision.
   - **Open Questions**: anything unresolved.
5. If a `docs/decisions/` directory does not exist, create it.
6. Update `docs/decisions/index.md` (create if missing) to list the new decision.
7. If the decision is accepted, add a summary entry to `.agents/pm/pm-decisions.md`.
8. Present the draft to the user for review.

## Output

- Decision document: `docs/decisions/DW-<NNN>-<slug>.md`
- Updated `docs/decisions/index.md`
- Updated `.agents/pm/pm-decisions.md` (if decision is accepted)

## Completion Criteria

- The decision document contains all required sections.
- At least two options are described with pros and cons.
- The document is listed in the decisions index.
- The status field is set correctly.

## Error Handling

- If the design facet is not enabled, warn the user and ask whether to proceed.
- If a decision with the same topic already exists, show it to the user and ask whether to update the existing record or create a new one.
- If the user cannot identify at least two options, note this gap explicitly and set status to `proposed` with an open question about alternatives.