ahmido
c36cb43741
This PR introduces the Global Surface Information Architecture Contract, detailing rules for decision-first display, metadata separation, and zero-state suppression across UI surfaces. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #441
66 lines
6.3 KiB
Markdown
66 lines
6.3 KiB
Markdown
# Tasks: Spec 370 - Global Surface Information Architecture Contract v1
|
|
|
|
**Input**: Design documents from `specs/370-global-surface-information-architecture-contract/`
|
|
**Prerequisites**: `spec.md`, `plan.md`, Spec 368 audit artifacts, `checklists/requirements.md`
|
|
|
|
**Tests**: Docs-only package. No Pest/browser lane is required unless a later implementation step changes runtime UI.
|
|
|
|
## Phase 1: Preparation Guardrails
|
|
|
|
- [x] T001 Re-read `specs/370-global-surface-information-architecture-contract/spec.md`, `plan.md`, `tasks.md`, and `.specify/memory/constitution.md`.
|
|
- [x] T002 [P] Confirm the package remains docs-only by checking no runtime paths outside `specs/370-global-surface-information-architecture-contract/` are modified.
|
|
- [x] T003 [P] Inspect Spec 368 source inputs in `specs/368-platform-ui-signal-to-noise-browser-audit/audit.md`, `findings.md`, `recommendations.md`, `page-scorecard.csv`, `spec-candidates.md`, and `artifacts/raw/browser-notes.md`.
|
|
- [x] T004 [P] Inspect the Spec 368 screenshot inventory under `specs/368-platform-ui-signal-to-noise-browser-audit/artifacts/screenshots/` and keep examples evidence-labeled.
|
|
- [x] T005 Confirm Spec 369 is completed/validated context only and do not edit `specs/369-baseline-profile-decision-view/`.
|
|
|
|
## Phase 2: Source Evidence Artifacts
|
|
|
|
- [x] T006 [P] Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/source-audit-summary.md` so each referenced Spec 368 input uses exact verification class labels such as `repo-verified`, `browser-verified`, `derived from existing implementation`, `not available`, or `deferred`.
|
|
- [x] T007 [P] Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/validation-report.md` with branch, HEAD, dirty/untracked files, source artifact availability, and preparation analysis result.
|
|
- [x] T008 Ensure missing or blocked source evidence is recorded as `not available` or `deferred`, never invented.
|
|
|
|
## Phase 3: Global Surface Contract
|
|
|
|
- [x] T009 [US1] Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/surface-contract.md` with the first-viewport hierarchy: status, reason, impact, primary next action, affected objects, evidence availability, diagnostics second, technical metadata on demand.
|
|
- [x] T010 [US1] Ensure the contract separates Header, Main Content, Sidebar/Aside, Technical Details, and Evidence Area responsibilities.
|
|
- [x] T011 [US1] Ensure the contract defines zero-metric suppression and duplicate-truth controls without requiring a runtime component or static guard.
|
|
- [x] T012 [US1] Ensure the contract defines verification classes and requires future facts to use them.
|
|
|
|
## Phase 4: Surface, Audience, And Scope Matrix
|
|
|
|
- [x] T013 [US1] Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/surface-type-matrix.md` with all required Spec 370 IA review classes from the spec, explicitly stating they are not runtime `ActionSurfaceType` values or replacements for canonical UI standards.
|
|
- [x] T014 [US2] Confirm each audience type in the matrix states decision need, forbidden default burden, allowed technical depth, evidence expectation, diagnostics expectation, and action model.
|
|
- [x] T015 [US1] Confirm each scope type states default scope treatment and raw ID placement rules.
|
|
- [x] T016 [US3] Confirm diagnostic and system surfaces are allowed more technical depth while still requiring impact and next action.
|
|
|
|
## Phase 5: Bloat, Copy, And Checklist Artifacts
|
|
|
|
- [x] T017 [US1] Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/ui-bloat-patterns.md` with Spec 368-derived patterns and prevention rules.
|
|
- [x] T018 [US2] Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/copy-and-terminology-rules.md` with provider-neutral, customer-safe, and operator-action-oriented language rules.
|
|
- [x] T019 [US1] Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/page-assessment-checklist.md` so future specs can assess pages before implementation.
|
|
- [x] T020 [US1] Ensure the page assessment checklist ends with one review outcome and one workflow outcome.
|
|
|
|
## Phase 6: Follow-up Boundary
|
|
|
|
- [x] T021 Review and finalize `specs/370-global-surface-information-architecture-contract/artifacts/follow-up-spec-map.md`.
|
|
- [x] T022 Confirm page-level runtime refactors, browser fixture repair, screenshot refreshes, target mock/examples per archetype, static guards, and docs/product publication remain follow-up candidates and are not hidden inside Spec 370.
|
|
- [x] T023 Confirm future automation guard work requires a separate spec after at least one additional consuming UI productization spec validates the contract.
|
|
|
|
## Phase 7: Review, Analysis, And Validation
|
|
|
|
- [x] T024 Run `./.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks`.
|
|
- [x] T025 Run a read-only preparation analysis across `spec.md`, `plan.md`, and `tasks.md` using the repo's `speckit-analyze` guidance.
|
|
- [x] T026 Fix only Spec Kit preparation artifacts if the preparation analysis finds bounded inconsistencies.
|
|
- [x] T027 Run `git diff --check`.
|
|
- [x] T028 Record final readiness, no-runtime-impact, branch name, and any remaining non-blocking question in `artifacts/validation-report.md` only after T024-T027 complete.
|
|
- [x] T029 Confirm no application/runtime implementation was performed.
|
|
|
|
## Test Governance Checklist
|
|
|
|
- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior. Docs-only/manual review is sufficient because no runtime behavior changes.
|
|
- [x] New or changed tests stay in the smallest honest family, and any heavy-governance or browser addition is explicit. No tests are added.
|
|
- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default; any widening is isolated or documented. No helpers or fixtures are added.
|
|
- [x] Planned validation commands cover the change without pulling in unrelated lane cost. `check-prerequisites`, read-only analysis, and `git diff --check` cover the prep package.
|
|
- [x] The declared surface test profile or `standard-native-filament` relief is explicit. N/A - no reachable UI surface changes.
|
|
- [x] Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR. None.
|