context-surface-contract

name

context_surface_contract

description

Use when the user asks for Product Surface Contract, Surface Contract, Screen Contract, product surface responsibility, surface responsibility audit, information architecture governance, main/drilldown ownership, UI product boundary, product surface compiler, 产品界面职责治理, 产品接触面, 用户接触面, 页面职责契约, 界面责任契约, 主层/下钻归属, or asks to turn broad UI/product principles into project Context in a Minimal Context Harness project. Do not trigger for ordinary CSS tweaks, one-off UI bug fixes, copy edits, or implementation-only tasks unless the user explicitly asks to define or repair durable product-surface responsibility or information architecture contracts.

Context Surface Contract

Package-Managed Boundary

This Skill is generated by ty-context sync and owned by the Harness package. Do not edit the generated context_surface_contract Skill directly.

Project-specific Product Surface responsibilities belong in project_context/** and optional project-local Skills such as <harnessRoot>/skills/product_plan/SKILL.md, <harnessRoot>/skills/uiux_design/SKILL.md, <harnessRoot>/skills/development_engineer/SKILL.md or <harnessRoot>/skills/surface_contract/SKILL.md. The package-managed Skill teaches the compiler workflow only; it must not contain business-specific page duties, provider facts, project names, raw payload schemas or product examples.

Purpose

Help agents turn broad product/UI principles into concrete, project-owned Product Surface Contracts while keeping Minimal Context small.

A Product Surface is any user-facing interface where users make judgments, take actions and receive feedback. Covered platforms include Web apps, dashboards, admin or operations UI, mobile screens, desktop windows, game UI/HUD/menu scenes, CLI/TUI output, browser extension or plugin UI, and embedded, kiosk or device UI.

Context Roles

Do not add a new context_role.

Use existing roles:

• contract for cross-surface, cross-area or project-level Product Surface Contracts.
• area or subdomain for owning product-domain Screen Contracts.
• verification for repeatable UI, CLI, app or product-surface validation paths.
• decision-rationale for stable product-surface tradeoff reasons.
• implementation-index for code navigation only.

Forbidden roles include surface-contract, product-surface, web-contract, app-contract and game-surface.

Use DESIGN.md only for visual identity, visual tokens and visual rationale. Do not put surface responsibility, main/drilldown ownership or diagnostic placement into DESIGN.md.

Mode Selection

Use the narrowest mode that matches the request:

• Audit Mode: inspect whether existing surfaces have clear responsibility.
• Compile Mode: turn audit findings or user decisions into Context candidates.
• Apply Mode: write durable Context only when the user explicitly allows durable writes.
• Conformance Mode: check implementation against an existing Product Surface Contract.

Do not run implementation, long validation, browser smoke, app smoke or CLI smoke unless the user explicitly asks for execution.

Audit Mode

Use when the user asks to inspect, review or audit surface responsibility.

Output only:

• Surface list.
• Surface platform.
• Code, screenshot, CLI or app evidence inspected.
• Existing Context expectation.
• Drift, missing contract or backend complexity exposure.
• Candidate Context Delta.
• Suggested durable placement.
• Optional temporary audit path under tmp/** when useful.

Do not edit durable Context by default. Code, screenshots and CLI output are evidence of current implementation, not authority for product responsibility.

Compile Mode

Use when turning audit findings or user decisions into Context candidates.

Output:

• Project-level Product Surface Contract candidate when responsibilities cross surfaces or areas.
• Area-level Screen Contract candidate when ownership belongs inside one domain.
• context.toml candidate registration with role = "contract" when durable registration is needed.
• global.md#Context Index candidate entry when a new Context file is added.
• Verification candidate for repeatable surface checks.
• Internal source classification when an external product, architecture, technical or acceptance source changes durable surface responsibility; do not create a Markdown coverage table.
• Repo-local Skill task-block candidate when the user wants project-specific enforcement.

Do not assume business responsibilities from current code shape alone. Ask for confirmation if the candidate would silently choose between competing product or information-architecture meanings.

Apply Mode

Use only when the user explicitly allows durable writes.

Allowed writes:

• project_context/**.
• project_context/context.toml.
• project_context/global.md#Context Index.
• Optional verification role Context.
• Optional separate project-local Skill files when the user explicitly wants project-local enforcement.

Forbidden writes:

• Package-managed generated Skills in a consumer project.
• <harnessRoot>/ty-context-managed/** in a consumer project.
• Business code unless the user also requested implementation.
• Generated files.
• DESIGN.md, except visual tokens or visual rationale that do not belong in a Product Surface Contract.

If Surface Contract Hit is none and the task creates durable surface responsibility, set Context Delta: required and update project Context before implementation alignment.

Conformance Mode

Use after implementation or during review.

Output:

• Surface Contract Conformance.
• External-source constraint classification and implementation alignment status.
• Remaining Drift.
• Missing Context.
• Implementation Drift.
• Verification run / not_run / failed.

Do not store one-off evidence, screenshots, logs, raw outputs or implementation summaries in Context.

Compiler Questions

For each touched surface, answer only what is relevant:

• What surface is being touched?
• What platform shape does it have?
• What primary user question does it answer?
• What belongs on the main surface?
• What must move to drilldown, diagnostics, operations, evidence or technical detail?
• Which long-running or mutating actions require task id, progress, retry, import, recovery or history?
• Which empty, loading, stale, unavailable, fixture or fallback states matter?
• What validation path can prove conformance?
• If this came from an external plan/source, which source constraints are covered by existing Context, require new Context, are task-local only, are explicitly out of scope, need user decision or remain under-scoped?

Repo-Local Task Block Candidate

When the user wants project-local enforcement, propose a separate project-local Skill block like this and tailor only the project-specific answers:

## Surface Contract Task Block

For any task touching user-facing surfaces, information placement, forms, filters, search, long-running UI actions, diagnostics, evidence, CLI/TUI output or main/drilldown ownership, answer before implementation:

- Surface Contract Hit: `<context file / none>`
- Surface: `<route / screen / window / panel / command / HUD / menu>`
- Surface Platform: `<web | mobile | desktop | game | cli-tui | extension | embedded | mixed>`
- Owning Product Domain: `<area / subdomain>`
- Primary User Question: `<one concrete user judgment>`
- Main Surface Allows: `<durable visible information and actions>`
- Main Surface Forbids: `<backend fields, raw payloads, diagnostics, debug ids, fake states, etc.>`
- Drilldown Ownership: `<details / evidence / operations / diagnostics / technical details>`
- Long Task State Requirement: `<run id, progress, retry, recovery, import, history, or none>`
- Context Delta: `<none | required>`
- Verification: `<view-model test / component test / browser smoke / CLI smoke / manual check>`

Do not add this task block to package-managed default Skills as a universal gate. Projects opt in through separate project-local Skills.

Implementation Alignment

When implementation is also requested, align code with the Product Surface Contract:

• View-models or presenters should expose user-facing states instead of raw backend payloads when that contract exists.
• Components or commands should render main-surface facts and move technical details to the owning drilldown.
• Long-running actions should persist or recover the required operation state.
• Tests should assert user-facing state semantics, not only backend field plumbing.
• Browser, app, CLI or game smoke checks should validate actual surface behavior when feasible.

Final handoff should include concise Surface Contract Conformance: contract source, implementation alignment, remaining drift and verification status.

Conformance must internally confirm that every important external-source constraint is covered by Context, updated into Context, task-local, explicitly out of scope or awaiting a genuine user decision, and that controlling surface facts reached the correct implementation. Unresolved constraints or non-aligned surface implementation mean the work cannot be described as fully aligned; component, modal, viewmodel or unit evidence alone cannot prove main-surface ownership. Do not create a fixed plan.md, Task Contract file or Markdown mapping tables for this check.

Output Boundaries

• Do not create PRDs, UI/UX handoff docs, ADRs, stage artifacts, lifecycle state or phase gates.
• Do not update Context for ordinary CSS tweaks, copy edits or one-off UI bug fixes unless durable surface responsibility changes.
• Do not treat current backend fields, enums, JSON, screenshots or terminal output as product intent.
• Do not invent rationale; rejected alternatives or tradeoffs belong in Context only when they are stable enough to affect future surface decisions.
• Do not add a surface-specific validator, edit-order gate, plan-contract validator or package-level mandatory Surface Contract gate.
• Do not include business-domain examples in this package-managed Skill.