# ADR 060: Product Decision Records

- HTML version: https://robbiepalmer.me/projects/personal-knowledge-graph/adrs/060-product-decision-records
- Project: Personal Knowledge Graph (https://robbiepalmer.me/projects/personal-knowledge-graph.md)
- Status: Accepted
- Date: 2026-09-27
- Initiatives: Semi-autonomous Software Development (https://robbiepalmer.me/initiatives/semi-autonomous-software-development.md)

## Context

Architecture Decision Records explain technical structure and implementation
trade-offs. Several existing ADRs also carry product choices because the
repository has no durable record for a user-facing promise, scope boundary,
policy, success measure, or behaviour. That blurs two different questions:

* What should the product do, for whom, and how will I judge the result?
* How should the system deliver that outcome under its technical constraints?

A product choice may lead to several architecture choices. Architecture work
can also be worth recording without changing the product. Treating both as one
record makes product history hard to find and encourages implementation
evidence to stand in for an outcome.

## Decision

The knowledge graph will add Product Decision Records as a separate, global
content type. PDRs own durable product choices. ADRs continue to own durable
architecture choices.

A PDR is warranted when changing the choice would alter a user-facing promise,
target audience, supported workflow, scope boundary, policy, outcome measure,
or product behaviour. Research notes, feature specifications, delivery plans,
and routine copy changes do not become PDRs. An ADR is warranted when changing
the choice would alter system structure, a non-functional constraint, a
technology selection, or an implementation trade-off.

### Location, identity, and routes

PDR source files will live in `ui/content/product-decisions/`. Each filename
uses a repository-wide, monotonic number and a stable slug, such as
`001-agent-readable-project-pages.mdx`. A number is never reused, including
after rejection or deprecation.

The filename slug is the canonical PDR identity. Public collection and detail
routes will be `/product-decisions` and `/product-decisions/<slug>`. The global
identity fits decisions that affect more than one project and avoids choosing
one project as their artificial owner.

The title repeats the number for readers, for example `PDR 001: Publish
agent-readable project pages`. Renaming the prose title does not change the
filename, identity, or route.

### Frontmatter contract

`ProductDecisionFrontmatterSchema` is the typed source contract. A complete
record has this shape:

```yaml
title: "PDR 001: Publish agent-readable project pages"
date: "2026-09-20"
status: "Accepted"
decision_date: "2026-09-21"
supersedes: "000-earlier-publication-policy"
evidence:
  - title: "Reader and agent access study"
    url: "https://example.com/study"
ideas: ["context-engineering"]
affected_projects: ["personal-knowledge-graph"]
informed_by_adrs: ["personal-knowledge-graph:033-content-graph-indexes"]
```

`date` records when the PDR was opened. `decision_date` records when a proposal
was accepted or rejected. An accepted choice created in one step may use the
same value for both. `deprecated_date` records when an accepted choice ended
without a replacement.

`evidence` supports the choice at decision time. Evidence may be research,
observed behaviour, user feedback, or an experiment. The record should link to
what actually informed the choice instead of inventing a quantitative target
to complete the frontmatter.

Evaluation belongs in the PDR body when the decision has a real way to assess
it. An optional `Evaluation` section can describe a signal, observation, or
revisit condition in the terms used to make the choice. A measurable target is
useful when the decision genuinely depends on one. The contract does not
require a metric, target, measurement method, or time window.

Delivery evidence belongs to the work that implements the decision, such as a
linked ADR, ticket, pull request, or deployment. A merged pull request may
prove delivery, but it does not prove that the product choice was sound.

`ideas` preserves conceptual provenance. `affected_projects` names every
project governed by the choice. `informed_by_adrs` names earlier architecture
decisions whose constraints or discoveries shaped this product choice.

### Lifecycle and supersession

Authors may set `Proposed`, `Accepted`, `Rejected`, or `Deprecated`.
`Superseded` is derived and never written into frontmatter.

* A Proposed PDR has no `decision_date`. It may name the record it intends to
  supersede, but the earlier choice remains current.
* Accepted and Rejected PDRs require `decision_date`.
* A Rejected PDR remains in the graph as decision history. It cannot supersede
  an earlier choice.
* A Deprecated PDR requires both `decision_date` and `deprecated_date`. It has
  ended without a replacement.
* An Accepted PDR with `supersedes` makes the named record Superseded from the
  successor's `decision_date`.

Lifecycle dates cannot run backwards. An accepted file remains unchanged when
a later record replaces it. The graph derives its effective Superseded state
from the accepted successor, following the same immutable-history rule used by
ADRs.

### Relationship to ADRs

The relationship can run in either direction because product and architecture
decisions can expose work for each other. The later record owns the link to the
earlier record, and the field name states why:

* When a PDR comes first, a later ADR names it through
  `implements_product_decisions`. The ADR explains the technical response to
  that product choice.
* When an ADR exposes a constraint that requires product judgment, a later PDR
  names it through `informed_by_adrs`. The PDR explains how the product will
  handle that constraint.

The content graph derives reverse links. Authors do not add the same relation
to both records, and a record does not predict a decision that has not been
made yet.

One product choice may govern several architecture decisions. For example, a
PDR promising one canonical project narrative for people and agents could lead
to the choices for [static generation](/projects/personal-knowledge-graph/adrs/015-ssg),
[MDX content](/projects/personal-knowledge-graph/adrs/020-mdx), and the
[in-memory content graph](/projects/personal-knowledge-graph/adrs/033-content-graph-indexes).
The PDR owns the audience and promise, including any genuine evaluation
criterion. Each ADR owns its technical trade-off.

The reverse sequence matters too. An ADR may discover that a viable design has
a latency floor, eventual consistency, a licensing restriction, or a cost
boundary. If choosing how users experience that limit changes the product, a
new PDR records the product choice and names the ADR in `informed_by_adrs`. If
the choice replaces an earlier PDR, it also uses `supersedes`. Any later ADR
that changes the architecture in response then points to the new PDR through
`implements_product_decisions`.

An ADR does not need a PDR when its value is architectural and it does not
change a product promise. The
[Typos adoption](/projects/personal-knowledge-graph/adrs/055-typos) records a
repository quality control. It can stand alone unless a separate product
decision promises a measurable editorial standard to users.

### Initial records

The first adoption pass should preserve these live choices:

1. The Personal Knowledge Graph is the primary public account of projects,
   decisions, and delivery evidence, rather than a conventional portfolio of
   unconnected summaries.
2. Every major public page has a canonical plain-Markdown twin for agents and
   text-first readers.
3. Public project narratives include the problem, current boundary, decisions,
   and evidence needed to assess the work. Private notes and application data
   remain outside the public graph.

This ADR only identifies the candidates. The adoption work must give each one
its own rationale, available evidence, affected projects, and lifecycle dates.

## Consequences

Product intent gains a stable identity and can connect to ideas, projects, and
the architecture that follows it. Reviews can ask separately whether a feature
shipped and whether the underlying product choice still holds.

The repository gains another content type, route family, validation path, and
set of graph relations. Authors must decide whether a choice belongs in a PDR,
an ADR, both, or neither. The boundary above makes that extra judgment useful,
but it does not remove it.

Existing ADRs remain valid and do not gain references to later PDRs. A new PDR
may cite an existing ADR that informed it, and a new ADR may cite an existing
PDR that it implements. Later pipeline work will load and validate the new
files; later publication work will add views and the initial records.

## Alternatives

### Keep product choices in ADRs

This adds no content type. It also keeps product outcomes mixed with technical
means and makes a product choice that spans several ADRs difficult to express.
Rejected because the current ambiguity is the problem this decision addresses.

### Store PDRs under one project

Project-local numbering matches the ADR layout. It breaks down for choices
that govern several projects and makes cross-project ownership arbitrary.
Rejected in favour of a global sequence with explicit `affected_projects`.

### Store product choices only in the Work Graph

Work Graph tickets are useful for scheduling and delivery state. They are not
immutable public decision records, and closing a ticket does not explain why a
product policy remains in force. Rejected. Tickets may link to PDRs as context
or evidence.

---

Markdown index of this site: https://robbiepalmer.me/llms.txt