cupertino

Use FIRST, before cupertino-focus or any other cupertino technique, whenever customer experience and technology choices are both still undecided for a new feature or project scope. This is a pre-architecture gate: it establishes what experience actually matters before any technology direction is chosen, working backwards from experience to technology rather than forwards from the feature request. Trigger on requests like 'design a way for users to...', 'we need a feature that...', or any new scope where nobody has yet named a database, framework, API, or UI element.

USER-INVOKED ONLY — never automatic, never run as part of cupertino-review's pipeline or any other automatic stage. Use only when the user explicitly asks, on a deliberate post-ship cadence, whether to replace a currently-successful, load-bearing thing with a better successor built in-house — the iPhone-cannibalizing-the-iPod move. Trigger only on explicit requests like 'should we cannibalize X', 'is it time to replace our own best thing', or a direct ask to run this specific technique by name.

Use at UI/frontend build-time, before writing any code, whenever a user-facing interface or screen is being designed. Trigger on 'design this screen', 'build this UI', 'make this feel premium', 'this feels generic', or any request to design or implement a user-facing surface. Applies to any stack (HTML, React, Vue, native, etc.). Always run before code, never after — retrofitting the council onto finished code defeats the purpose. Not for a not-yet-scoped new feature where customer experience and technology are both still undecided — run cupertino-backwards first to establish the experience statement. Not for reviewing an interface that already exists: for accessibility, semantic-markup or hardcoded-design-value problems in shipped source use befund-ui-audit, and for a full-lifecycle design pass over an existing project use cupertino-review.

Use at build-time, ONLY when a low-status commodity feature already in scope for the current build — error messages, logs, config, settings, onboarding, migrations, loading states, empty states, backups, status output — could be transfigured into something beloved, the way Apple turned boring backup into Time Machine. Trigger on 'this feature is boring', 'nobody uses this', 'make this delightful', 'elevate this'. Never seek out a commodity feature independently or apply this to a brand-new capability not already being worked on — route a brand-new capability to cupertino-backwards instead; if nothing already in scope qualifies, say so and skip.

Use immediately after cupertino-backwards has established the customer experience, to reduce a sprawling portfolio of shipped and planned products, feature lines, modes, or variants down to the smallest focused set before architecture work commits effort. Trigger on requests like 'we have too many modes/plans/tiers/variants', 'help us decide what to cut', or any planning conversation where the honest list of things-in-flight is longer than anyone wants to admit.

Use before starting new work in a domain that already has a drafted handbook, to pull in only the constraints and exceptions relevant to the upcoming task rather than dumping the whole document. Trigger on 'what does our handbook say about this', 'apply our code standards to this task', or naturally at the start of any task in a domain where cupertino-handbook-draft has already run.

Use when the user wants to compare new or changed work against an existing domain handbook at .cupertino/DOMAIN-handbook.md (one file per domain) to find divergence. Trigger on 'does this comply with our handbook', 'audit these files against the code handbook', 'check this against the code handbook'. Requires a handbook previously produced by cupertino-handbook-draft. Not for repo-wide conventions written in CLAUDE.md or .claude/house-rules.md — use befund:befund-lint-audit for those. Read-only — never modifies target files. Zero findings is a valid, expected outcome, not something to work around.

Use when the user wants to create and persist a durable handbook for one domain — design, code, testing, or documentation — capturing the project's actual conventions (or honest scaffolded defaults where none exist) as a checkable rule per dimension. Trigger on 'write a code handbook', 'draft our design standards', 'create a testing handbook', or similar requests naming a domain and asking for a persisted, checkable artifact rather than a one-off answer. Not for researching what a stack *should* adopt from external authority, and not for producing the machine-checkable .lehre/ruleset.json a lehre run enforces — use lehre-codify for those. This skill describes one domain as it already is, in a human-readable per-dimension handbook.

Use only when the user has explicitly enabled fix mode for a domain, to apply the mechanical findings from a prior cupertino-handbook-check pass. Trigger only on explicit requests like 'fix the mechanical handbook findings' AFTER the user has turned on fix mode — never infer consent from a check report alone. Never touches mechanical:false findings, never commits or pushes. Not for code-modernization or idiom findings from code_idiom_summary.json — those belong to befund-idiom-fix. If no handbook_check_DOMAIN_summary.json exists for the domain, this is not the audit the user means.

Use at architecture-decision time, together with cupertino-longevity, to decide whether one specific seam — a boundary between layers, APIs, or ownership — is worth owning tightly versus delegating to a vendor or framework. Trigger on 'should we build or buy this', 'own vs delegate', 'vendor this piece or not', 'tight integration vs pluggable', or any decision about a single named boundary. Never apply as a blanket policy across a whole system — one seam per invocation.

Use at architecture-decision time, together with cupertino-integrate, to evaluate whether an architecture, API surface, or codebase structure can evolve incrementally or will force a future rewrite. Trigger on 'will this scale', 'future-proof this', 'API versioning strategy', 'will I regret this architecture', 'is this extensible', 'migration path', 'plugin system', or any design discussion where long-term evolvability is genuinely at stake — not on routine feature work with no durability question.

Use at build-time, parallel to cupertino-council, whenever a specific empirical uncertainty needs settling by actually building and running a throwaway version rather than debating it in the abstract. Trigger on 'not sure if this approach will actually work', 'let's spike this', 'will this library even do what we need', or any disagreement that a small runnable experiment would resolve faster than continued discussion. Never use for general feasibility studies — only for one specific, answerable question.

Use at ship-time, as the last automatic step for a finished feature, module, tool, or API, to deliver exactly one non-obvious, high-leverage addition in a keynote 'and one more thing' structure. Trigger on 'what's missing here', 'is there anything else this needs before shipping', or automatically as the final stage when cupertino-review runs the full pipeline. Never produces a list — exactly one suggestion, and it must be built, not pitched.

Use when a project spans multiple lifecycle moments and the user wants the whole cupertino discipline applied end-to-end in one pass — 'give this the full cupertino treatment', 'review this like Apple would', 'run the whole design lifecycle on this'. Composes the plugin's other techniques as fixed, sequenced stages rather than requiring the user to invoke each one by hand. Not for a single lifecycle moment with one obvious technique — use that technique directly instead.

Use at build/finishing-time, after core feature work has produced something worth a new user's first five minutes, to redesign the actual first-run, onboarding, or install flow. Trigger on 'improve onboarding', 'first-run experience', 'unboxing', 'install flow', 'first five minutes'. Scope is strictly the first five minutes of first contact — not the whole onboarding arc, and not to be confused with cupertino-elevate, which transfigures an existing feature's ongoing feel rather than the first-contact sequence.