Implementation constitution · the engineering safeguard

The philosophy must survive the engineer.

Most calm apps don't die because the philosophy was wrong. They die because a hundred reasonable engineering decisions each shaved a small thing from the feel. This document is the safeguard — a classifier for implementation decisions, by surface, with named damage patterns.

Small interaction failures compound emotionally. The user's nervous system catches each one even when their conscious mind does not. The constitutional premise
01

The three-way classifier.

Every implementation decision falls into one of three categories. The verdict determines the response.

Preserving
Keeps the runtime feeling like weather. Ship it.
Neutral
Doesn't affect feel either way. Ship if useful; reject if it adds surface area.
Eroding
Each instance is small. Each makes the runtime feel one click more like software. Reject by default.

The signals to check, every time

A single eroding decision is rarely a crisis. The danger is the rate. Three in a quarter is a slow death.

02

The thirteen surfaces under permanent watch.

Each surface lists the decisions most likely to come up — preserving, neutral, or eroding.

S·01
Transition timing
Does the screen move at the rate of breath, or at the rate of compilation?
Preserve
Atmosphere cross-fade stays at cadence × 1000ms.
The breath-paced timing is the single most felt characteristic of the runtime. Speeding it up "for snappiness" erodes the whole premise.
conscious: nobody: yes
Erode
"Skip animation if user is mid-tap" optimization.
Performance engineer's instinct. The user's nervous system reads the abrupt cut as a glitch. Subtle damage: trust in the screen's calm degrades — they tense slightly for the next tap.
conscious: nobody: yes
Neutral
Easing curve cubic-bezier(0.25, 0.1, 0.25, 1) vs (0.2, 0, 0.2, 1).
Indistinguishable in practice at these durations. Pick one and document it.
S·02
Modal stacking
Is anything blocking the room from being seen?
Preserve
Re-entry overlay is the only modal in the app.
A second modal — any second modal — means the philosophy has cracked. Errors are inline; permission requests are contextual sheets at most.
Erode
A confirmation modal before deleting a capture.
"Are you sure?" is the productivity-app reflex. The user never deletes captures in v1; if they ever do, soft-delete with undo, not a modal.
conscious: yesbody: yes
Erode
A first-launch "tour" with carousel modals.
The onboarding is its own surface. Modal-stacked tours are SaaS-coded. Naya teaches by being inhabited.
S·03
Gesture burden
Does the user have to remember how, or only what?
Preserve
Capture orb records on single tap. No press-and-hold.
The stress-test doc identified this as the #1 risk. A 400ms hold is a precision burden a fragmented user fails.
Erode
Swipe-left to archive a capture.
iOS-native gesture, feels right to the engineer. But there is no archive — captures persist, threading is automatic. Adding a gesture invents a workflow.
Neutral
Two-finger gesture to toggle dark mode within Naya.
No one finds it; no harm done. Reject only because it's surface area to maintain.
S·04
Permission flows
Does the request match the user's intent at that moment?
Preserve
Microphone permission asked on first orb tap, not at onboarding.
Just-in-time permission is contextual; the user is about to use the thing it enables. Onboarding-time bulk permissions trains the user to deny.
Erode
"Please enable microphone in Settings" full-screen modal after denial.
Punitive. The user's denial was a real signal. The right response is the soft inline caption ("The mic is off, but you can write.") and silence.
conscious: yesbody: yes
S·05
Notification cadence
Did interruption earn its rights here?
Preserve
≤ 4 archetypes total. Hard cap.
Lock-Notifications.html names them all. A fifth archetype is a philosophy crack — not a feature.
Erode
"User hasn't opened Naya in 3 days" re-engagement push.
The shape of every habit-tracker drift. Absence is private. The user's silence is not a problem for Naya to solve.
Erode
Badge count on the app icon for "new resurfaces."
Badges are urgency manufactured by the dock. There is no urgency in Still here.
S·06
Loading states
Does the user feel waited-on, or waited-for?
Preserve
No spinners. Surfaces appear when ready; placeholders match the atmosphere.
A spinner is the universal symbol of your time is less important than ours. The atmosphere persisting unchanged is a better signal.
Erode
Skeleton-screen rectangles in the shape of cards while data loads.
Productivity-app convention. The user reads the rectangles as "missing content I will have to read in a moment." The right state is the atmosphere alone, until the line arrives.
conscious: nobody: yes
S·07
Empty states
Is "nothing" presented as a problem or as a kind of held?
Preserve
An empty Still here reads: "Nothing waiting. The room is still."
Names the silence as a quality, not a deficit. No call to action, no "+ Add capture" button.
Erode
An illustration of an empty notebook with "Capture your first thought!" CTA.
Onboarding-loop manipulation. The user opens Naya from their own readiness; the empty state is not a sales surface.
S·08
Re-entry behavior
Does the screen acknowledge return, or perform it?
Preserve
The 3-second welcome hold lingers even if the user taps.
Refusing to be skipped past is the entire point. An engineer will be tempted to dismiss on tap "for responsiveness." This is the load-bearing moment.
Erode
"Tap anywhere to continue" on the welcome hold.
Hint text undoes the hold. The screen is supposed to sit; adding skip-instructions teaches the user to skip.
S·09
Voice capture latency
Did the orb hear me before I doubted it?
Preserve
Orb color shift to recording-amber within 100ms of tap.
The visual confirmation must precede the user's doubt. If they wait 250ms wondering whether Naya heard them, they re-tap, and recording resets.
Erode
Async-init the AVAudioSession on tap.
Lazy session activation feels efficient. The first tap of the day will lag 300–800ms while the session warms up. Pre-warm the session on app foreground. The cost is battery; the benefit is trust.
S·10
Transcript streaming
Is the live transcript helping the user think, or watching them think?
Erode
Words appear with a typewriter animation as they're recognized.
Visually arresting. Cognitively distracting. The stress test identified this as a thought-shortener. Settled words appear plainly; partial words dim. No animation on text.
Preserve
Audio is always authoritative; transcript is best-effort.
If transcription lags, audio still saves. The user is never blocked on transcription performance. Held happens on silence, regardless of transcript state.
S·11
State restoration
Does the user return to the room they left, or to a fresh launch?
Preserve
Atmosphere persists across cold launches.
A cold launch that resets to a default atmosphere reads as the app forgetting. @AppStorage for atmosphere is the floor.
Preserve
Scroll position in Still here restores on return.
The user was reading something. Losing place is a small violence.
Erode
"Restore last session" prompt on launch.
Web-browser-coded. Restoration should happen silently; asking the user creates a decision they did not ask for.
S·12
Background suspension
Does Naya act as if the user is gone, or as if they'll be back?
Preserve
Background tasks complete silently. BGProcessingTask handles threading runs.
The user should never see Naya "thinking." Work happens in their absence; results are present on return.
Erode
"Naya is updating…" splash on relaunch after a long suspension.
Splash screens of any kind erode immediacy. If the data isn't ready, show the atmosphere; the lines fill in.
S·13
Edge-case recovery
When something fails, does the user learn or just receive?
Preserve
Failures speak in the user's vocabulary, never the technical layer's.
"The mic stopped. What you had is here." not "AVError -11800." The user does not need to understand the failure to forgive it.
Erode
A "Send error report?" prompt after any crash.
The user just survived their own crash; asking them to do telemetry labor is a betrayal. Crash reports are silent in production. Period.
Preserve
Orphan-capture recovery happens silently on launch.
No "we found unsaved work, want it?" prompt. The user's captures are theirs by default; reconciliation happens behind the screen.
03

The compounding patterns to name.

Each pattern below is the shape of a slow erosion. Naming them in code review is the constitutional defense.

Convenience compounding
Each engineering shortcut feels small. Three small ones in a release, four in the next, and within a year the app has been quietly re-shaped by what was easier to build. Defense: name "this is a convenience compromise" out loud when it happens.
Affordance creep
Every state gets a "useful" button. Today gets a + to add. Capture gets a "save" for users who feel anxious without one. Within six months the screen is buttons. Defense: the screen ships with zero buttons that didn't exist on day one; new buttons require a written justification rooted in the runtime test.
Surface inflation
Settings grows: a toggle here, a slider there, "for users who want it." The Tweaks-panel-shaped temptation in shipped product. Defense: a fixed cap of settings (≤ 4 in v1). New settings must replace, not add.
Notification creep
"This one really earns rights." Every quarter, a new archetype enters the doc. Within a year, the user has muted the app. Defense: the archetype cap is constitutional. Five archetypes is a different product.
Animation creep
Each new screen gets a new transition "to feel polished." The cumulative effect is a UI that constantly demands the eye. Defense: any new animation must specify its breath-cycle relationship to existing motion. Bare additions are rejected.
Quantification leak
A small "you have 3 fragments today" surfaces, then "12 this week," then a weekly summary email. The runtime acquires a scoreboard. Defense: no count is rendered to the user. Engineers may count for analytics; product must never render a count.
Verb migration
Noun-shaped surfaces become verb-shaped ones. "The anchor" becomes "Start the anchor." "Still here" becomes "Review still here." Defense: a verb on Today is the warning. Audit every CTA quarterly.
04

The nervous-system test.

The conscious-mind test asks: does the user notice? The nervous-system test asks: does the user's body notice, even when their mind doesn't? Most eroding decisions pass the first and fail the second.

The body knows when…
A transition skips frames mid-animation. The screen flashes during a transition. A tap takes 250ms to register visually. An animation has too many easing changes. Type contrast jumps between screens. A modal arrives without warning. Haptic feedback fires when it wasn't expected.
The body forgives
A capture takes 2s instead of 1s to save. A line of copy is slightly wordier than ideal. The atmosphere is a shade darker than designed. The app icon is one pixel rounder than the spec. Small craft variations are forgiven; small interaction violations are not.
Code-review heuristic
If a change makes the app feel faster or snappier, look closely. Snappier is often the early symptom of erosion. The runtime is supposed to feel slow in a regulated way. Performance optimization that erases the runtime's pace is regression dressed as progress.
Naya remembers where your attention was — even under imperfect implementation conditions.
The constitutional commitment · Naya