Decision MD

Task: Generate decisions/D-NNN-slug/DECISION.md — Cross-Cutting Open-Question Resolver

Objective

Produce one decisions/D-{NNN}-{slug}/DECISION.md file per invocation that resolves one Open Question (or one batch of dependent questions sharing a single decision) carried by an upstream artifact. The skill is bias-free: invoked fresh, with no prior conversation context, it reads the question(s) verbatim, gathers evidence using the broadest tool surface in ADD (web search, codebase grep + targeted read, execution sandbox, prior decision files), reasons from the evidence — not from what an upstream agent might have implied — and either lands on a clearly-evidenced option (status: accepted) or hands off to the human via the asynchronous user-question mechanism (status: awaiting-user). The output is an audit trail: a future reader, looking only at the file, can reconstruct what was asked, what evidence was gathered, why a particular option won (or why the agent declined to decide), and what artifacts must change as a result.

DECIDE exists because two upstream failure modes proved costly during ADD pipeline testing: silent wrong picks (an upstream skill chose an answer without admitting alternatives existed, blocking only later when the choice failed downstream) and stuck pipelines (the orchestrator could not move forward but had no domain-specific tool to investigate). DECIDE concentrates the investigative tools — web for current docs and standards, codebase grep for existing conventions, runtime sandbox for empirical claims, file-based user-question for genuine product-direction calls — into one purposeful skill. The defining discipline — and the commonest violation — is no silent picks: when multiple options are valid and evidence cannot decide, the skill MUST hand off to the user via the YAML mechanism. It MUST NOT pad rationale to disguise a guess as a decision.

Inputs

The orchestrator passes these per invocation. The skill does NOT auto-discover the full design suite; reads are scoped.

1. Source artifact (required, primary subject) — the artifact carrying the Open Question(s) being resolved. Typically a path at the project root (e.g., units/<area>/u03/SPEC.md, INTERFACES.md, ARCHITECTURE.md, roadmap/<NNN>-<slug>/ROADMAP.md, issues/<NNN>-<slug>/ISSUE.md). The skill quotes the question verbatim from this file.
2. Cited artifacts (required, 1–4 typically) — artifacts the question text references or that are needed to understand the question. The orchestrator scopes this. Examples:
   • For a wire-format question: INTERFACES.md
   • For a domain-invariant question: DOMAIN.md
   • For a state-machine question: BEHAVIOR.md
   • For a unit-scope question: the unit's units/<area>/u<NN>/SPEC.md
3. Prior dependent decisions (optional, auto-passed when sequenced) — when this invocation depends on a previously-resolved decision, the prior decisions/D-NNN-slug/DECISION.md file is in the input set. The skill cites it under § 4 Prior Decisions.
4. decisions/ directory (auto-discovered) — existing decisions at decisions/D-*/DECISION.md. Read for two purposes: (a) idempotency check in Phase 1 (has this question already been resolved?), (b) NNN computation in Phase 5 (next available number).

Read-set size: 1 source + 1–4 cited + 0–2 prior decisions + tool reads (web, codebase, runtime) + glob of decisions/. Within ADD's read-set budget (1–5 declared reads + tools).

Workflow

Five phases, single-agent (no subagents — the agent is investigator and decision-maker, both roles in one). Phases are sequential; Phase 4 may loop back to Phase 3 if evidence is insufficient.

Phase 1: Read the Question(s) and Check for Duplicates

Read the source artifact, especially its Open Questions section. Read the cited artifacts. If sequenced, read the prior decision files passed as input.

Quote the question(s) verbatim into an in-agent working note. When multiple questions are batched into this invocation, identify whether they truly share a single decision (one answer resolves them all) or whether they are really separate decisions that the orchestrator batched incorrectly.

• If one decision resolves all batched questions: question_origin will be a YAML list in frontmatter; § 1 Question quotes every batched question with its source citation.
• If the batch is incorrect (the questions are independent and need separate decisions): do NOT silently split them within this file. Surface in § 9 Open Questions: "Orchestrator batched these questions but they are independent decisions. Recommend orchestrator dispatch them as separate decide invocations." Decline to decide; emit status: awaiting-user with user_question describing the batching error.