# GovOPlaN Interface Ethics And Design Doctrine

This document captures the product-level design doctrine for GovOPlaN. It is
more durable than an individual screen design and should guide admin,
configuration, workflow, policy, portal, and operational UI decisions.

GovOPlaN is meant to support administrative responsibility. The interface must
therefore make context, decision, consequence, and traceability visible enough
that users can act deliberately instead of being pushed through opaque
automation.

## Core Doctrine

1. Context, decision, and consequence belong together.
2. Decisions should not silently happen.
3. Transparency comes before convenience when rights, duties, records, money,
   access, or legal effects are involved.
4. Explicit state is preferable to implicit state.
5. Navigation is not consent.
6. Responsibility cannot be delegated to the system.
7. Traceability is part of the action, not a later reporting feature.
8. Context loss is a product defect.

These rules do not mean every screen should become verbose. They mean the
interface must expose the right explanation at the moment of decision and keep
technical detail available without making it the default surface.

## Decision Surface Contract

Any action that changes records, rights, policies, retention, communication,
payments, external systems, or workflow state should answer these questions
before execution:

- What object, person, organization, or process is affected?
- Which authority or role allows the actor to do this?
- What will change immediately?
- What downstream effects may happen?
- Can the action be undone, superseded, or only corrected later?
- What evidence or audit entry will be created?
- Which policy, configuration, or missing capability blocks the action?
- Who can resolve a blocker?

The answer may be shown through inline labels, a review step, a side panel, a
problem list, or a confirmation dialog. The important point is that consequence
and responsibility are not hidden behind a generic submit button.

## Contestability

Administrative decisions are often contestable or reviewable. GovOPlaN should
therefore preserve the path from input to decision:

- source data and attachments
- workflow state and task assignment
- policy decisions and source path
- actor and delegation context
- generated document/template version
- external handoff result
- notification or postbox delivery evidence
- retention and record classification state

Where a user sees a decision, they should be able to reach the provenance that
explains how the system got there. This is especially important for denials,
locks, calculated defaults, generated documents, payment state, retention
state, and access decisions.

## Anti-Patterns

Avoid these patterns in GovOPlaN interfaces:

- Magical buttons that execute multiple side effects without preview.
- Process tunnels that hide where the user is in an administrative procedure.
- Silent automation that changes external systems without an audit-visible
  command record.
- Friendly hiding that removes complexity at the cost of obscuring authority,
  consequence, or accountability.
- Disabled controls without actionable explanation.
- Configuration screens that ask users to edit raw JSON as the normal path.

## Automation Rule

Automation must use the same governed action surface as a human actor. The
system may execute actions as a system actor, but it must still run through
policy checks, capability contracts, audit, idempotency, and failure handling.

When an automated decision is not clear, GovOPlaN should create a manual
exception, task, or review item instead of guessing silently.

## Relationship To UI Components

Shared components should make this doctrine easy to follow:

- preflight and problem-list components for blockers
- policy source path and effective decision displays
- action review panels for consequence preview
- audit/provenance links on decision outputs
- guided dialogs for risky configuration
- disabled-action explanations with actor and next step
- confirmation dialogs that distinguish reversible, corrective, and destructive
  actions

The UI/UX decision ledger defines concrete implementation rules. This doctrine
defines why those rules exist.
