Skip to content

Decision Brief

Purpose

Answers: Given this context, which option do we recommend, why, on what conditions, and what would change the answer? It sits before an ADR. It is the argument; the ADR is the record of what was decided.

Example

Show a worked example of this artifact
---
ddx:
  id: DB-001
  type: decision-brief
  authoring:
    home: repo
  links:
    - {id: component-profile-postgresql-reusable, kind: evaluates, rev: example}
---

# DB-001: Which database should the document-search service use?

## Context

A small team is building a document-search service that stores documents
and their metadata and serves interactive queries from a web application. The
team already runs a relational database for its other services and wants to
avoid operating a second kind of store unless the benefit is clear. This brief
covers the choice of database engine for the service. Where it is hosted is a
separate decision and out of scope.

| Bound | Source | Effect on the choice |
|-------|--------|----------------------|
| Transactions must be atomic across a document and its metadata | PRD, Data Integrity | Excludes options without multi-row transactions |
| Metadata varies by document type | PRD, Search | Favors options with a native semi-structured type |
| Team operates one relational engine today | Current state | Adds cost to a second engine |

## Decision

Choose the database engine for the document-search service. The service
owner decides.

## Options

- **Extend the existing relational engine.** Use the engine already in
  production for the service's tables. Evidence: the engine's technology brief.
- **PostgreSQL.** A separate relational engine with a native binary JSON type.
  Evidence: PostgreSQL technology brief (component-profile-postgresql-reusable).
- **Status quo plus a search index.** Keep the current engine and add a
  separate search service for metadata queries. Evidence: none yet.

## Evaluation

| Criterion | Existing engine | PostgreSQL | Existing engine plus search index |
|-----------|-----------------|------------|-----------------------------------|
| Atomic multi-row transactions | Unknown (not researched) | Documented transactions and constraints | Unknown (not researched) |
| Semi-structured metadata | Unknown (not researched) | `jsonb` with indexing and containment operators | Unknown (not researched) |
| Added operating cost | None | A second engine to run | A second service to run |

The only option with cited evidence here is PostgreSQL; the other two need
their own briefs before the comparison is complete.

## Recommendation

**Recommendation**: Do not decide yet. PostgreSQL meets the transaction and
metadata bounds on the public record, but the existing engine has not been
researched, and it carries no added operating cost. Write the existing
engine's technology brief, then re-evaluate.

What would change it: a brief showing the existing engine lacks a native
semi-structured type or multi-row transactions would make PostgreSQL the
recommendation.

## Risks and Unknowns

| Risk or unknown | Bears on | Route |
|-----------------|----------|-------|
| Existing engine not researched | All criteria | Write its technology brief |
| Search-index option has no evidence | All criteria | Write a brief if it stays in scope |

## Evidence

| Reference | Kind | Revision | Used for |
|-----------|------|----------|----------|
| PostgreSQL technology brief (component-profile-postgresql-reusable) | Technology brief | example | Transactions, semi-structured metadata |

Reference

ActivityDesign — Decide how to build it. Capture trade-offs, contracts, and architecture decisions.
Default locationdocs/helix/02-design/decision-brief-DB-{number}-{decision-name}.md
RequiresNone
EnablesNone
InformsADR
Solution Design
Deliverable
Generation prompt
Show the full generation prompt
# Decision Brief Generation Prompt

Frame one decision in one context, compare the options against that context
on cited evidence, and recommend, so a reviewer can check the argument before
the decision is made. The brief is advisory.

## Storage Location

Store at: `docs/helix/02-design/decision-brief-DB-{number}-{decision-name}.md`,
or the path the flow's graph profile sets for this type (`locations:`).

## Purpose

Answers: **Given this context, which option do we recommend, why, on what
conditions, and what would change the answer?** It sits before an ADR. It is
the argument; the ADR is the record of what was decided.

## Role Boundary

A [[component-profile]] (reusable or contextual) records what is known about
one component; the brief uses it as evidence and does not restate it. An ADR
records a decision once taken; a brief recommends before one is. The brief
never overrides requirements, approved decisions, or concerns: it names them
as bounds in Context and reasons within them. If the recommendation
conflicts with an approved decision, say so as a risk and route it to the
owner; do not argue the decision away inside the brief.

## Method

1. **Frame the decision.** One decision, one context, one decider. If two
   choices can vary independently (what to build on, where to run it), write
   two briefs or two clearly separate sections.
2. **Collect the bounds.** From the project's requirements, approved ADRs, and
   [[concerns]], list what narrows the choice. Cite each by id or path.
3. **List the options,** including the status quo and any option a reviewer
   will ask "why not?" about.
4. **Gather evidence.** Cite technology briefs and component profiles by
   pinned revision. Evidence from outside the project is advisory; it informs
   the evaluation and does not set a requirement.
5. **Evaluate every option on the same criteria,** drawn from the bounds. A
   cell with no evidence says Unknown.
6. **Recommend.** One option for this context, its conditions, why it beats
   the strongest alternative, and what would change it.
7. **Record risks and unknowns** with a route. An owner, date, or figure
   appears only if a project artifact states it.
8. **Pin the evidence** before publishing: every reference carries the revision
   it was read at.

## Writing for the reviewer

The reader is a reviewer, often outside the team, who will check the argument
not the author. Plain words, claims in the sentence, citations after. State
the recommendation first in Recommendation, not in a closing paragraph, and
say what would change it. Do not inflate a conditional recommendation into a
certainty.

## Inputs

- Requirements, approved ADRs, concerns, and principles that bound the choice
- Technology briefs and component profiles for each option
- The current state, for the status quo option
Template
Show the template structure
---
ddx:
  id: DB-[number]
  type: decision-brief
  authoring:
    home: repo
  links:
    # - {id: <technology brief or component profile id>, kind: evaluates, rev: <pinned revision>}
    # - {id: <concern id>, kind: addresses}
    # - {id: <source id>, kind: supported_by, rev: <pinned revision>}
---

# DB-[number]: [Decision as a question]

## Context

The situation the decision is made in, and what bounds it. Name the
requirements, approved decisions, and concerns that apply, each by id or
path, and the constraints that are fixed. Say what is out of scope,
including any decision that can vary independently of this one.

| Bound | Source | Effect on the choice |
|-------|--------|----------------------|
| [Requirement, decision, concern, or constraint] | [id or path] | [How it narrows the options] |

## Decision

The one decision to be made, as a sentence a reviewer can answer yes or no
to or choose among options for, and who decides.

## Options

Every option, including the status quo. One paragraph each: what it is and
the briefs or profiles it rests on.

- **[Option A]**: [what it is]. Evidence: [reference, pinned revision]
- **[Option B]**: [what it is]. Evidence: [reference, pinned revision]

## Evaluation

All options against the same criteria, drawn from Context. Each cell cites
evidence or says Unknown.

| Criterion | [Option A] | [Option B] |
|-----------|------------|------------|
| [Criterion from Context] | [Finding, source] | [Finding, source] |

[Two to four sentences on what separates the options for this context.]

## Recommendation

**Recommendation**: [Option] for [this context], on these conditions: [the
conditions]. [One to three sentences on why it fits this context better than
the strongest alternative.]

What would change it: [the evidence or change in context that would reverse
the recommendation].

## Risks and Unknowns

| Risk or unknown | Bears on | Route |
|-----------------|----------|-------|
| [Risk or open question] | [Criterion or option] | [Spike, owner decision, or accepted] |

## Evidence

Each reference this brief relies on, with the revision it was read at.

| Reference | Kind | Revision | Used for |
|-----------|------|----------|----------|
| [Technology brief, profile, source] | [kind] | [revision or digest] | [criterion or option] |
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/design/decision-brief.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:c0fba65a…1cbe43db

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/design/decision-brief/",
        "digest": {
          "alg": "sha256",
          "value": "c0fba65a581463a2b8e141083c479582f21e7d7046924f29499ed7621cbe43db"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "xmpqeiV4rg2bWjZJMMBG_FRYkbopYf_UUgxQgwaGYCORA-DjRRedQUe5OlUv8htCSpij9nKzYemC9RQ86cyACQ",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}