APEX Amendment: Level of Effort (LOE) Field for Proposals

Date: 2026-03-06 Author: Bob Matsuoka Status: DRAFT Audience: Engineering Leadership, APEX contributors

Problem

APEX proposals have no structured place to record a Level of Effort estimate. This creates two gaps:

1. Proposals that gate initiative creation — e.g. the go-dre staging test — require an ops/coordination LOE before a formal initiative can be opened, but there is no field to capture it, no owner to assign it to, and no way to see at a glance which proposals are blocked on a missing LOE.

2. Proposals in the dashboard — the Docusaurus status page and any future tooling cannot surface "how big is this?" without parsing free-form prose.

Currently, type: proposal is not even in schemas/frontmatter.schema.json — proposals are freeform markdown with no required fields. This amendment formalises the proposal type and adds LOE as a structured field.

Proposal

1. Add proposal to the frontmatter schema

Add a proposal branch to frontmatter.schema.json alongside initiative, experiment, prd, team-charter, and decision.

Required fields:

type: proposal
title: "..."
status: draft | review | approved | implemented | rejected
author: "..."
created: YYYY-MM-DD
updated: YYYY-MM-DD

Optional fields:

loe: XS | S | M | L | XL | TBD
loe_owner: "Name"           # who provides the estimate
loe_notes: "..."            # free-form context (1 line)

LOE t-shirt sizing:

2. Update the proposal template

Add a standard ## Level of Effort section to templates/proposal.md (create if not present) with the LOE table pattern established in the go-dre proposal.

3. Validation rule: proposals gating initiatives

When a proposal is referenced by an initiative's related_proposal field (future), the validator should warn if the proposal's loe is TBD and status is still draft. This surfaced the problem before the initiative is opened.

4. Frontmatter migration for existing proposals

Five existing proposals lacked the minimal type: proposal frontmatter required for schema validation. This PR includes the migration — each of the five files now has type, status, author, created, and updated fields added. The loe field is left as TBD on migrated proposals since retroactive sizing is speculative.

Migrated in this PR: - APEX-WORKFLOW-REVISIONS-PROPOSAL.md - CURSOR-INTEGRATION.md - MONOREPO-HIERARCHY.md - PDP-SPEC-PROCESS-PROPOSAL.md - TOOLING-IMPLEMENTATION-PROPOSAL.md

Two existing proposals (POLARIS-ARCHITECTURE.md, SHADOW-VAMPIRE-PIPELINE.md) already have full frontmatter — no changes needed. All archived proposals are also compliant.

What This Does Not Cover

• Adding loe to initiatives or experiments (those already have explicit milestone-based sizing)
• Automated LOE calculation or integration with Jira story points
• Requiring LOE on all proposals — only those that gate initiative creation

Implementation

Total: S (1–2 days end-to-end)

Alternatives Considered

Put LOE in the initiative instead of the proposal. The initiative is where commitments live, so LOE could live there as loe_estimate. Rejected because the LOE is needed before the initiative is opened — it is the gate, not the output. Putting it in the initiative would allow initiatives to be created without the estimate, defeating the purpose.

Use numeric days instead of t-shirt sizes. More precise but harder to maintain — estimates get stale, and point precision implies false accuracy. T-shirt sizes age better and are consistent with how teams communicate effort in practice.