pikasTech-unidesk/docs/reference/strategy-governance.md

Strategy Governance

This document owns the strategic filter for UniDesk requirements: external-benefit traceability, short-term versus long-term investment, and anti-loop guardrails for architecture proposals. The analysis record for the current strategy framing is GitHub issue #7. The long-term governance follow-up for the default user path versus diagnostics/status boundary is DC-DCSN-P0-2026-004.

Scope

Use this document when deciding whether a proposal should exist at all, how urgently it should be pursued, and whether it belongs to the short-term stabilization lane or the long-term base-layer lane.

This document does not replace docs/reference/release-governance.md, docs/reference/deploy.md, docs/reference/ci.md, or docs/reference/dev-environment.md. Those documents own the execution rules. This document owns the demand filter before execution begins.

Strategic Principle

UniDesk should be driven by verifiable external demand, not by infinite internal derivation or architecture taste.

External demand includes:

• user workflow value;
• operator recovery and incident reduction;
• deployment speed and reliability;
• delivery throughput;
• availability and observability;
• cost reduction that can be observed in practice;
• adoption or retention of a real platform capability.

Internal work is acceptable only when it can be traced to one of those outcomes or when it is a bounded investment that clearly compounds future external value.

If a proposal only improves internal elegance, symmetry, or conceptual purity, it is not sufficient by itself.

Requirement Test

Before accepting a requirement, answer these questions:

1. Who outside the implementation layer benefits?
2. What external metric improves?
3. How can the improvement be observed or verified?
4. Is the benefit short-term or long-term?
5. What user, operator, or delivery pain does it remove?
6. What is the removal condition if the proposal is only a temporary bridge?

If the answers are weak, the requirement should be dropped, narrowed, or rewritten.

Minimal Requirement Shaping

Before writing a long-term reference, implementation plan, issue, prompt, or task breakdown for a broad requirement, first compress the requirement to the smallest domain model that satisfies the current external need.

Use an explicit simplification pass:

1. List the rich or default architecture that first comes to mind.
2. Remove roles, groups, projects, capabilities, services, middleware, gates, and audit surfaces that are not needed for the first useful workflow.
3. Produce a before/after table showing what was removed or merged.
4. Ask whether the remaining model can be implemented with an existing service, database, and control path before introducing a new microservice or middleware.
5. Record postponed components as trigger-based follow-ups, not as phase-one dependencies.

For example, a multi-user hardware-lab requirement should first check whether admin/user, session ownership, and a single grant table are enough before adding group/project RBAC, capability matrices, OpenFGA, Keycloak, service mesh, or Kubernetes tenant abstractions. A middleware is justified only when a concrete trigger appears, such as external identity integration, inherited permissions, tenant self-service namespaces, or admission-policy enforcement that cannot be handled by the existing service boundary.

Reference And Plan Split

When the simplified requirement needs documentation, split the output:

• docs/reference/*.md owns stable design goals, authority boundaries, table or API contracts, request paths, service ownership, and acceptance criteria.
• docs/plan/*.md, GitHub issues, or project-specific planning docs own current state, source observations, implementation order, migration steps, incompatible changes, and open work.

The reference must not become a process log. It should explain the target shape as if a future implementer has not seen the chat. The plan should explain how the current source differs from that target and what must change.

For product or platform designs that touch multiple services, the plan should name each affected service and classify the change:

• data/schema change;
• API or request-chain change;
• frontend behavior change;
• worker/runtime behavior change;
• deployment or namespace/data-plane change;
• incompatible behavior that deliberately removes an old route, default, or fallback.

Do not preserve legacy compatibility just because it existed before. If the user has accepted a simplified target, old assertions, public routes, feature flags, fallbacks, or dual paths that conflict with the target should be removed in the same plan, with the user-facing breakage and migration handling stated clearly.

Short-Term Work

Short-term work is the work that improves the current usable system quickly.

It is valid when it:

• stabilizes release/v1;
• protects production availability;
• makes CI/CD more reliable;
• reduces manual recovery effort;
• fixes user-visible defects;
• removes a blocking infrastructure defect that slows delivery;
• reduces the cost of shipping the next verified change.

Short-term work should be chosen when the main problem is today’s delivery or today’s operational fragility.

Long-Term Work

Long-term work is justified only when it creates reusable base capability with a measurable future payoff.

It is valid when it:

• raises the ceiling of future delivery speed;
• reduces the cost of every later change;
• improves the quality of the stable base for future releases;
• removes a recurring class of operational pain;
• creates a platform primitive that several real workflows will use.

Long-term work must still have:

• a named beneficiary;
• a measurable hypothesis;
• a bounded budget;
• an explicit exit condition;
• a reason it cannot wait forever.

If it does not have those properties, it is just internal expansion.

Anti-Patterns

Do not accept requirements that are only:

• architecture experimentation without a user or operator payoff;
• feature-flag proliferation without a clear removal path;
• hidden dual paths that are hard to test or observe;
• abstractions added only because they feel cleaner;
• infrastructure work that cannot be tied to delivery, availability, recovery, or cost;
• refactors that move complexity around without reducing external pain.

Review Rule

When a new idea is proposed, classify it immediately:

• short-term if it helps the current stable base ship, recover, or stay alive;
• long-term if it compounds future capability and has a clear payoff path;
• reject if it cannot be tied to external benefit.

The default bias should be toward the simplest path that satisfies the external need. Complexity is only justified when it pays for itself in visible external value.

Default Path Boundary

When a product surface has both a primary user workflow and an internal diagnostics or acceptance surface, the primary workflow must remain the default discoverable entry. Diagnostics and status pages may exist for verification, recovery, or observability, but they do not become the product's headline or default route unless a decision record explicitly says so.

For the current HWLAB case, DC-DCSN-P0-2026-003 freezes the short-term product direction, and DC-DCSN-P0-2026-004 records the longer-term governance rule for keeping the default path distinct from diagnostics/status surfaces.

Relationship to Other Governance Docs

• docs/reference/release-governance.md owns release lines, stabilization windows, runtime pinning, and feature-flag governance.
• docs/reference/deploy.md owns desired-state reconciliation and rollout semantics.
• docs/reference/ci.md owns CI execution on D601.
• docs/reference/dev-environment.md owns the persistent dev lane.

This document sits above those execution rules. It decides whether a proposed change is worth doing and whether it belongs to the short-term lane or the long-term lane.