Skip to main content

ADR-0023 — Feature roadmap

  • Status: Accepted
  • Date: 2026-05-11
  • Decision-makers: Tom Anderson

Context​

The v1 build had been an implicit, evolving list. As Helm matures and the velocity-with-AI changes the feasibility of building many features quickly, the absence of an explicit roadmap risks two failure modes:

  • Scope creep — features get built because they came up in a conversation, not because they're the most-needed-next thing. Each addition steals attention from the prioritized list, but the steal happens silently.
  • Silent omissions — features that everyone "assumed" would land never get scheduled because they were never written down. The miss surfaces only when a customer asks.

A canonical, ordered list of v1+ features is the reference point for "what's on the plan and what isn't." It lives in the Bible because the Bible is the source of truth for everything else about Helm; the roadmap belongs in the same place.

Alternatives considered:

  • Implicit roadmap in a session-handoff doc — what we had. Easy to write, easy to drift, easy to forget.
  • GitHub issues / project board — fine for active work, terrible for "the plan." Issues rot; projects fragment.
  • External roadmap tool (Linear, Productboard) — adds a vendor, splits the docs surface, defeats the "Bible is canonical" property.
  • Canonical Bible page — chosen. The roadmap is documentation, not a tracker, and Helm's documentation lives in the Bible.

Decision​

Adopt the 15-feature v1+ roadmap captured in docs/overview/roadmap.md. The page is the canonical home; project files and session handoffs reference it and do not duplicate it.

Process:

  • Reordering within the roadmap happens by editing the page. Stages are ordered for build sequence, not calendar dates.
  • Additions to the roadmap require an explicit decision moment — an edit to the page with a rationale paragraph in the relevant feature's subsection.
  • Deletions move the feature to the page's "Deferred" subsection with a one-paragraph reasoning. Features are never silently dropped.
  • New features being considered for build require consultation against the roadmap first. A useful three-question check is included on the roadmap page under "Discipline."

Consequences​

Positive:

  • Scope creep produces a moment of conscious decision (an edit to the page with a rationale) rather than silent expansion of in-flight work
  • Future sessions inherit the planned trajectory without re-deriving it from session-handoff fragments
  • Customers and collaborators can see the plan as a stable artifact
  • The page is one click from intro / current-state / slice-overview, so it's hard to miss
  • The 15-feature framing exposes natural pause points (end of each stage) for re-evaluation

Negative:

  • The roadmap creates expectation pressure. Slipping items must be acknowledged, not silently dropped.
  • A canonical list is a target — it becomes tempting to optimize for "ticking items off the roadmap" rather than for shop value.

Mitigations:

  • The "Drafted from planning · v0.1" admonition on the roadmap page is honest about the list being a plan, not a commitment
  • The Deferred subsection is a legitimate destination for items that change — defer freely when the reasoning is good
  • Stage boundaries are explicit re-evaluation points; ending a stage is the natural moment to reorder what's next

Notes​

The roadmap is ordered, not scheduled. There are no dates on the page deliberately. Dates are session-handoff information; the roadmap is the durable shape of the plan.

See also​