decisions

ai-dp:decisions

The decisions step. This pipeline is autonomous — it never asks the user. Instead of deferring hard calls to a person, you make them yourself and write them down so they are auditable and overridable. The output, decisions.md, is the contract the plan is built on.

Inputs

• RUN_DIR — run directory.
• <RUN_DIR>/context.md — investigation output. Read in full, especially Risks & unknowns.
• <RUN_DIR>/state.json — for args (the original feature request).

Procedure

Session id: if a AIDP_SESSION_ID=<id> line is present in your conversation context, substitute it for every <AIDP_SESSION_ID> placeholder below. If absent, drop the --session "<AIDP_SESSION_ID>" argument; advance.ts falls back to process.env.AIDP_SESSION_ID.

1. Mark running

bun ${AIDP_PLUGIN_ROOT}/scripts/cli/advance.ts set <RUN_DIR> steps.decisions.status running --session "<AIDP_SESSION_ID>"

2. Enumerate the hard decisions

Read context.md and the feature request. Surface every decision where a competent engineer could reasonably choose differently and the choice materially shapes the implementation. Typical categories:

• Architecture / pattern — where the logic lives, which layer owns it, sync vs async, etc.
• Library / dependency — build vs reuse vs add a package.
• Data model / schema — new fields/tables, shape, migration/back-compat strategy.
• Interface / API shape — endpoint/signature/return shape, naming of public surfaces.
• Scope boundaries — what is in scope vs deferred.
• Behavior on ambiguity — every interpretation the investigation step had to guess (pulled from Risks & unknowns).
• Error handling / edge cases — fail-soft vs fail-loud, retries, validation strategy.
• Testing strategy — what kind of tests, what to cover.

Skip the obvious and trivial. Do not pad the list with decisions that have only one sensible answer.

3. Decide each one yourself

For every decision: lay out the realistic options with a one-line pro/con each, then pick one and give a short rationale. Bias toward the thorough, maintainable choice (reuse existing code, no shortcuts, no divergent shapes) — the same discipline the plan step will apply. When a decision depends on a fact you can check in the repo, check it rather than guessing.

4. Write <RUN_DIR>/decisions.md

# Decisions: <feature name>

> Autonomous run — every decision below was made by the agent, not a human. Each lists the options considered and marks the one selected. To override, edit the **SELECTED** marker (and rationale) here, then re-run from the plan step.

## 1. <the decision, as a question>
- Option A — <description> — <pro / con>
- **Option B — SELECTED** — <description> — <pro / con>
- Option C — <description> — <pro / con>

**Rationale:** <one or two sentences: why B over the others.>

## 2. <next decision>
...

Rules:

• Every decision MUST have at least two real options and exactly one marked SELECTED.
• Options must be genuine alternatives, not strawmen.
• Rationale is one or two sentences — why the selected option wins.
• If there are genuinely no material decisions, write a single section: ## None — the implementation path is unambiguous followed by one sentence saying why. Still write the file.
• If a decision changed an assumption the investigation made, also patch context.md so the two documents stay consistent.

5. Record the artifact and advance

bun ${AIDP_PLUGIN_ROOT}/scripts/cli/advance.ts set <RUN_DIR> steps.decisions.artifact "decisions.md" --session "<AIDP_SESSION_ID>"
bun ${AIDP_PLUGIN_ROOT}/scripts/cli/advance.ts advance <RUN_DIR> decisions --session "<AIDP_SESSION_ID>"

6. Hand off — do not text-stop

After advance, state.steps.plan.status === "pending". Print a one-liner referencing decisions.md as a markdown link:

Decisions recorded — see [decisions.md](${AIDP_STATE_DIR}/ai-feature-pipeline/<feature>/decisions.md). Drafting the plan now.

Your very next action MUST be a Skill-tool invocation in this same turn:

Skill(skill_name = "ai-dp:plan")