# OBPI Decomposition Matrix

Status: Active
Last reviewed: 2026-03-04
Authority: Canon (Defines the granularity standards for work breakdown structures)

This document provides the formal matrix for decomposing Architectural Decision Records (ADRs) into One Brief Per Item (OBPI) units. It moves the project from heuristic-based planning to a mature, dimension-aware granularity model.

---

## The Granularity Matrix

Decomposition must be right-sized by assessing the ADR across five dimensions.

| Dimension | **Atomic (Lite)** | **Modular (Heavy)** | **Structural (Foundation)** |
| :--- | :--- | :--- | :--- |
| **Data & State** | No schema changes; logic-only. | New schema, config key, or JSON field. | New ledger event, storage engine, or DB migration. |
| **Logic/Engine** | Pure function update or bug fix. | New service, logic flow, or internal component. | New execution runtime, subsystem, or core engine. |
| **Interface** | Internal/Hidden change. | New CLI flag, API endpoint, or UI element. | New CLI command group, Protocol, or Surface. |
| **Observability** | Standard logging inherited. | Targeted status reporting and diagnostics. | Dedicated audit receipts, log paths, and metrics. |
| **Lineage** | N/A. | Scripted state transition or cleanup. | Full historical lineage migration or archival. |

---

## Baseline Structure: The Rule of Three

For any **Heavy** or **Foundation (0.0.x)** ADR, the initial decomposition follows a standard three-layer structural template:

1.  **OBPI-01: Registry/Interface** (Schema, configuration, data structures).
2.  **OBPI-02: Core Execution** (Internal engine, primary logic, algorithms).
3.  **OBPI-03: Lifecycle/Operations** (CLI surface, logging, runbook, status).

---

## Refining Overlay: The Matrix of Four

Once the baseline structure is established, apply the **Matrix of Four** as an overlay filter. Each baseline unit must be tested against these principles; if a unit fails a principle, it MUST be decomposed further.

### 1. The Single-Narrative Rule (Overlay)
**One OBPI = One clear "Value Narrative."**
-   *Rule*: Avoid the word "and" in objectives.
-   *Decomposition*: If OBPI-03 covers "Implement CLI commands AND automated auditing," split into two OBPIs.

### 2. The Testability Ceiling (Overlay)
**Small surface = Reliable verification.**
-   *Rule*: Maximum 5 distinct test scenario clusters per OBPI.
-   *Decomposition*: If OBPI-02 (Core) requires 8 different edge-case setups, split into "Core Happy Path" and "Core Error Recovery."

### 3. The State Anchor (Overlay)
**Isolate side-effects.**
-   *Rule*: Isolate any component that writes to the Ledger or modifies persistent state.
-   *Decomposition*: If OBPI-01 defines a schema AND seeds the initial ledger event, split the seeding into its own unit.

### 4. The Surface Boundary (Overlay)
**Separate the "How" from the "What."**
-   *Rule*: Internal logic must never share a brief with an external-facing surface (CLI/API).
-   *Decomposition*: If OBPI-02 attempts to implement the core engine AND the CLI parser, split them.

---

## Lane-Aware Scaling

The matrix scales based on the ADR's lane:

-   **Lite Lane**: Typically triggers 1-2 dimensions. A single, high-granularity OBPI is preferred.
-   **Heavy Lane**: Typically triggers 3+ dimensions. Decomposition into 3-5 OBPIs is the standard.
-   **Foundation (0.0.x)**: Triggers all dimensions. Requires maximum granularity (5+ OBPIs) to ensure base stability.

---

## Deterministic Decomposition Gate

To remove intuition-only planning, ADR decomposition MUST be computed using a scorecard.

### Step 1: Dimension Scores (0/1/2)

Score each dimension:

- Data/State
- Logic/Engine
- Interface
- Observability
- Lineage

Compute:

- `Dimension Total = sum(5 dimension scores)`

### Step 2: Baseline Count

Map `Dimension Total` to a baseline range:

- `0-3 => 1-2`
- `4-6 => 3`
- `7-8 => 4`
- `9-10 => 5+`

Select one baseline count inside that range as `Baseline Selected`.

### Step 3: Mandatory Split Adders

Add `+1` OBPI for each triggered split rule:

- Single-Narrative violation (mixed objectives)
- Surface Boundary violation (internal logic + external surface in one unit)
- State Anchor violation (state-writing mixed with non-state work)
- Testability Ceiling violation (>5 test scenario clusters)

Compute:

- `Split Total = sum(triggered split rules)`
- `Final Target OBPI Count = Baseline Selected + Split Total`

### Step 4: Checklist Synchronization

ADR checklist count MUST equal `Final Target OBPI Count`.

This is enforced as a mechanics contract in gzkit command surfaces (`gz plan` seed + `gz specify`
binding + validation checks).

### Calibration Policy

Cutoffs are notional defaults, not immutable constants. They MUST be reviewed and tuned from project
evidence (rework rate, failed gates, attestation churn, and delivery predictability).

---

## Enforcement

The `gz-plan` and `gz-adr-promote` skills utilize this matrix during the **Spec Developer Phase**. Agents must perform a "Granularity Assessment" and present the rationale for the resulting OBPI checklist based on these dimensions.
