Skip to main content
  • Send to AI

Product Principles

Purpose​

Four cross-cutting principles guide how every Project is shaped. They are not prioritization criteria: they are shape criteria. If a Project does not respect them, it returns to Shaping before leaving the Product side of the board.

The principles apply equally across the four Verticals (Publica.la Education, Reading Experience, E-Commerce: Checkout, Paper).

01 · Simplification​

The default flow works without the user learning anything new. Configuration lives at the tenant, not at the reader.

If the obvious solution is to "add a toggle," you are simplifying for the team, not for the user. This principle applies to platform (admin, control panel) and to final product (reader, checkout, storefront).

Does not count as simplification​

  • Adding an "advanced mode" or an "expert user" switch.
  • Solving the problem with a tooltip, an onboarding banner, or a tutorial.
  • Giving configurability to the end reader.

Counts as simplification​

  • Redesigning the default flow so the tooltip is not needed.
  • Reserving configuration for the tenant (publisher), not for the reader.
  • Removing an existing option that fewer than 5% of users use.

Questions to challenge​

  • You are adding a setting for X. What would happen if you just picked the best default and shipped without the setting?
  • This requires the user to understand [concept]. Is there a way the system can figure this out automatically?
  • You described 3 options for the admin. Which one would 90% of tenants pick? Can you just do that one?
  • If you removed this configuration entirely, who would complain? How many tenants? Is it worth the complexity?
  • This flow has N steps. Can any step be removed or combined with another?

02 · Remove Blockers​

Every Project either removes a known friction in a common path, or enables two or more future initiatives that are already in the active roadmap.

Enabler beats blocker: we prioritize work that opens doors over work that adds isolated features. If a Project does neither, it probably should not be built. The future initiatives it claims to enable must be traceable to active Initiatives or to the Verticals framework; hypothetical future value does not pass Spec Review.

Does not count as removing blockers​

  • A new feature discovered through a tooltip or tour.
  • Adding a configuration layer on top of a blocker instead of removing it.
  • Isolated work that does not unlock anything else.
  • Claiming enablement of initiatives that are not in the active set or the Verticals framework.

Counts as removing blockers​

  • Migrating to a new payments provider because it enables N future payments improvements already planned in E-Commerce: Checkout.
  • Unifying auth between reader and storefront because it unblocks several flows tracked in active Initiatives.
  • Removing a step from checkout: less friction, no new features.

Questions to challenge​

  • You say this enables [initiative X]. Is that Initiative active in Linear right now? What is its key?
  • If we did NOT build this, what specifically could we not do in Q3/Q4?
  • You listed two initiatives this enables. Would you bet that both will actually be built this year?
  • What is the current workaround? How painful is it, really? Do we have data on how many users hit this?
  • Could we remove the blocker with a smaller intervention (a config change, a data fix, a simpler feature) instead of this full Project?

03 · Shaped for Quality​

Quality is designed into the spec, not added at the end.

Quality lives in two places in the spec:

  1. EARS Acceptance Criteria — tracking events and state behaviors (empty, error, loading, offline) are written as EARS, just like functional behavior. They are testable, observable, and tied to specific user-facing copy.
  2. Quality Bar (open questions for Refining) — Metric, Performance, and Accessibility are surfaced as open questions and suggestions during Shaping, then resolved in Refining before Spec Review.

If it is not in the spec by Spec Review, it is not built.

Does not count as shaped for quality​

  • "We will define the metric post-launch."
  • "Performance is a v2 thing."
  • A spec without EARS for the empty, error, loading, or offline states (or with state names but no copy).
  • Tracking listed as a generic note ("we'll add events later") instead of EARS Acceptance Criteria.
  • Deferring accessibility to a follow-up Project.

Counts as shaped for quality​

  • Tracking events written as Event-driven EARS, with event name and payload fields, inside the Acceptance Criteria.
  • State behaviors written as State-driven or Unwanted-behavior EARS, with specific user-facing copy.
  • Quality Bar surfaced in Shaping as open questions; fully resolved before Spec Review with numbers (LCP under 2.5s, not "fast") and explicit scope (WCAG AA on the reader toolbar, not "accessible").

EARS for Tracking and States (inside Acceptance Criteria)​

TypePatternExample
TrackingEvent-drivenWhen the reader marks a tag as public, the reader app shall emit tag_made_public with {tag_id, user_id, tenant_id}.
StateState-drivenWhile the library has no products, the storefront shall display "Aún no tenés contenido en tu biblioteca." with a primary explore action.
StateUnwantedIf the reader loses connectivity, the reader app shall display "Modo offline. Tus marcas se sincronizarán al volver a conectarte."

Quality Bar (open questions for Refining, resolved before Spec Review)​

#ItemWhat to surface in Shaping (open questions / suggestions)
1MetricBaseline source, target candidates, measurement window options
2PerformanceExpected LCP/TTI band on web, response time band on admin, perf-critical paths to instrument
3AccessibilitySurfaces requiring WCAG AA, keyboard navigation scope, aria patterns to evaluate

See Spec and EARS for how the Quality Bar and EARS integrate.

Questions to challenge​

  • For each user-triggered action you described, do you have an EARS for the tracking event with payload? If not, write it.
  • The empty state — is there an EARS with the user-facing copy, or only the word "empty"?
  • Your Quality Bar lists "Metric: TBD." That is fine in Shaping. What are the open questions you need answered to close it in Refining?
  • Your performance suggestion is "fast." Before Spec Review, what number in milliseconds would make you reject a PR?
  • Accessibility scope — which specific surfaces (reader toolbar, checkout form, search input) must hit WCAG AA? List them.
  • The tracking AC fires on event X with payload Y. Is QA able to write a test case for it? If not, rewrite.

04 · Self-Serve by Default​

Anything that requires Customer Success, DevOps, or Support to work is product debt.

Every Project reduces (never increases) operational load. If a release adds manual tickets, it is not finished.

This principle applies to tenants (publishers) configuring themselves from their panel, and to readers resolving their case without opening a ticket.

New work vs. existing debt. New features must ship self-serve from day one; this is a hard rule and blocks Spec Review. Existing manual processes that predate this framework are tracked as self-serve debt and prioritized through the normal RICE flow; they do not block unrelated Projects.

Does not count as self-serve​

  • "CS activates the feature by flag when the customer requests it."
  • "DevOps runs a script to onboard the tenant."
  • "Send us a ticket and we will enable it."
  • Shipping a new feature that is self-serve for readers but requires CS to enable for the tenant.

Counts as self-serve​

  • The tenant enables the feature from their panel or from Nova.
  • Onboarding runs on its own from data the customer loads.
  • Every release lists which manual operations it eliminates.
  • A Project that converts an existing CS-gated workflow into a panel setting.

Questions to challenge​

  • You say the tenant enables this from their panel. Show me: which panel screen? Does that screen exist today?
  • After this ships, does CS still need to do anything? What exactly?
  • If a tenant wants to disable this after enabling it, can they do it themselves?
  • What happens if 50 tenants want to enable this on the same day? Is there a queue, a script, or is it self-serve?
  • Is there a manual migration or data backfill required? Who runs it? Is it a one-time cost or recurring?

Scope and Focus​

Before evaluating a Project against the four principles, ask whether the scope itself is right. These two questions apply across all principles and are the first filter during Shaping.

Does the objective need all of this?​

Read the Objective (the single testable sentence, R-10). Then read every EARS requirement. Does the Objective become true with just a subset of the requirements? If yes, everything else is scope creep disguised as completeness.

  • Which requirements are strictly necessary to make the objective sentence true, and which are nice-to-haves?
  • If requirements E1 and E2 shipped and E3 through E6 did not, would the objective still be met?
  • Rank your requirements: which 3 are essential for the objective, and which could be moved to a wishlist without losing the core value?
  • Remove everything from this spec that is not strictly required to make the objective true. What is left? Is that enough to ship?

Can this be smaller?​

Projects at 2-3 weeks almost always hide a smaller functional unit that could ship in 1 week and deliver value on its own. (R-07, R-08)

Split into vertical slices, not horizontal layers. Each part of a Project should cut through all layers (UI, logic, data) and produce something demo-able. "Set up the data model" is a horizontal layer that cannot be demoed. "Professor marks a tag as public and gets a shareable link" is a vertical slice that can.

  • If you had to ship something valuable in 1 week instead of 3, what would you cut?
  • Which of these requirements could ship as a separate Project and still deliver value on its own?
  • Can you draw a line through this spec where everything above the line is the MVP and everything below is a separate Project?
  • What is the smallest change that would make a user's life better today?
  • If you split this into two Projects, would each one still pass R-22 (removes a blocker or enables 2+ initiatives)?
  • For each group of requirements: can a user see and interact with the result? If not, you have a horizontal layer, not a vertical slice.

How the Principles Are Enforced​

Principles are checked during Shaping and Spec Review. A Project that does not respect them is returned to Shaping. This is not a soft guideline: it is a shape criterion that blocks the progression of every Project.

X

Graph View