Platform Documentation and Assessment Plan

Objective

Produce a baseline of canonical documentation for the Cogrion platform as it currently exists, including supported capabilities, user and operator journeys, constraints, and known limitations. Use that documented current state as the basis for an evidence-based assessment, identify gaps introduced during rapid development, and finish with prioritized findings and recommendations. Remediation implementation is outside this assessment.

The documentation and assessment are led and performed by the designated lead together with product, design, engineering, platform, security, and service owners. This document defines the scope, deliverables, method, and completion criteria.

The documentation and assessment must answer:

1. What capabilities does the platform provide?
2. Which capabilities are supported, conditionally supported, experimental, deprecated, or unsupported today?
3. Under which clouds, environments, roles, integrations, capacities, and operating conditions is each capability supported?
4. What current limitations, exclusions, workarounds, and failure cases must users and operators understand?
5. How do users and operators achieve important outcomes?
6. Which components, data, and infrastructure support those journeys?
7. How does the system behave when dependencies or operations fail?
8. Which controls and operational practices are demonstrated by evidence?
9. What gaps create material product, security, reliability, or delivery risk?
10. What should be fixed first, by whom, and how will completion be verified?

Scoping model

The documentation and assessment are not organized primarily by repository or backend. Those boundaries describe implementation, but they frequently hide end-to-end behavior and gaps.

Use this hierarchy:

Platform
└── Capability domain
    └── User or operator journey
        └── Components involved
            ├── User interface
            ├── API or backend
            ├── Data stores
            ├── Infrastructure
            └── External systems

Primary scope: capability domains

A capability domain represents a stable outcome provided by the platform. The initial grouping below is grounded in the routes, pages, navigation, settings modules, internal console, role restrictions, and feature gates currently present in the Oqullus frontend.

Group	Concrete product surfaces to document
1. Agentic experience and Cogrion Hub	Conversational workspace, conversation and agent history, incognito sessions, endpoint selection, suggested actions, quick actions, plan and flow canvases, generated widgets, progress visibility, confirmations, and failure recovery
2. Workspace content and collaboration	Workspace and folder navigation, files and objects, content creation, sharing, membership-dependent access, notebook entry points, scheduling where exposed, and workspace-level collaboration behavior
3. Data catalog and metadata governance	Catalog, schema, and table browsing; metadata detail; descriptions; ownership; schema creation; tags or classifications; discovery; and access-request entry points
4. Workflow authoring and orchestration	Workflow list, creation, cloning, definition, detail, execution state, scheduling, task status, resource monitoring, retries, and failure inspection
5. Data pipelines, connectors, and ingestion	Pipeline list, connector selection and configuration, pipeline creation, pipeline graph, source and destination configuration, ingestion execution, pipeline detail, status, monitoring, retry, and recovery
6. SQL querying and saved work	SQL Lab, classic and accelerated execution modes, schema browser, query tabs, query execution, results, visualization, history, saved queries, preview, rename, and sharing
7. Dashboards and analytical publishing	Dashboard list, creation, builder, chart and layout configuration, preview, publication, shared-dashboard access, and dashboard permissions
8. Machine-learning lifecycle	Experiments, run history and detail, metrics, registered models, model detail, AutoML task suggestion and execution, synthetic-data workflows, and data-engine configuration
9. AI Gateway and model access governance	Endpoint list, creation and detail, metrics, provider routing, traces, audit log, groups, group members, endpoint ownership, token budgets, provider usage, guardrails, rate limits, and routing policies
10. Ontology and semantic layer	Object types and objects, create and edit flows, object graph, semantic query, workbooks, proposals, reviews, branch conflicts, governed changes, and semantic relationships
11. Identity, membership, and access control	Account-realm login, invitation acceptance, human and workload identity, role-based navigation, account members, workspace members and roles, data-access management, dashboard access, AI Gateway ownership and groups, and auditability of access changes
12. Account cloud foundation	Account overview, cloud credentials, AWS and Alicloud setup, networks, storage, account membership, resource status, reprovisioning where available, and provisioning logs
13. Workspace platform management	Workspace list, creation, detail, bootstrap and agent status, stacks, resources, compute profiles, members, roles, agent commands, lifecycle state, and destructive or danger-zone operations
14. Internal platform operations, metering, and support	Internal account provisioning, internal workspace administration, cloud-connect onboarding, stack composition, agent commands, metering, workload analysis, pricing and configuration views, results and output, tickets, and help-and-support behavior

This grouping is a discovery baseline, not proof that every listed surface is supported. For each item, the documentation must establish whether it is visible, reachable, role-restricted, environment-gated, internal-only, partially implemented, or inactive.

Use these frontend-evidence classifications during inventory:

Classification	Meaning
Visible route	Appears in navigation for at least one eligible role and environment
Secondary route	Active detail, create, edit, preview, or shared route reached from another screen but intentionally hidden from primary navigation
Role-restricted	Route or action is offered only to documented roles
Environment-gated	Availability changes by account, realm, sandbox, demo, or deployed backend
Internal-only	Intended for Cogrion staff rather than tenant users
Source-present but inactive	Page or component exists in source but its primary route is disabled, commented, or otherwise not reachable as a supported flow

Do not equate these classifications with product support. For example, a secondary route may be fully supported, while a source-present page may not be supported at all. The frontend currently contains source-present or commented surfaces such as ML Playground, ML Features, model Serving, and parts of the connector marketplace; their status remains unverified until owner and runtime evidence confirms it.

Use one directory per product capability. Every directory contains an index.md overview and may contain additional journey or detail pages.

Use the following canonical target homes for the initial grouping:

Group	Canonical documentation home
Agentic experience and Cogrion Hub	docs/features/cogrion-hub/
Workspace content and collaboration	docs/features/workspace/
Data catalog and metadata governance	docs/features/catalog/
Workflow authoring and orchestration	docs/features/workflow/
Data pipelines, connectors, and ingestion	docs/features/pipeline/
SQL querying and saved work	docs/features/sql-querying/
Dashboards and analytical publishing	docs/features/dashboards/
Machine-learning lifecycle	docs/features/machine-learning/
AI Gateway and model access governance	docs/features/ai-gateway/
Ontology and semantic layer	docs/features/ontology/
Identity, membership, and access control	docs/features/access-control/
Account cloud foundation	docs/features/account-cloud-foundation/
Workspace platform management	docs/features/workspace-platform-management/
Internal platform operations, metering, and support	docs/core-platform/internal-operations/

User procedures for these capabilities live under the matching area in docs/user-guide/. Security models remain in docs/security/ or docs/authorization/, and component behavior remains in docs/core-platform/ or docs/tenant-platform/. Those pages link back to the owning capability instead of becoming competing product descriptions.

Keep these boundaries explicit:

• Identity and authentication establishes who a human or workload is and how that identity is verified.
• Authorization and access control defines, evaluates, enforces, reviews, and revokes what an identity may do across platform, workspace, application, and data resources.
• Ontology and semantic modeling defines governed concepts, entities, relationships, mappings, business meaning, and the semantic context shared by discovery, analytics, policy, and AI capabilities.
• Data pipeline authoring, orchestration, and execution covers creating, validating, publishing, deploying, scheduling, running, observing, retrying, backfilling, pausing, and retiring data pipelines. The documentation must establish how all supporting components contribute to this capability without using repository boundaries as the definition of the user outcome.
• AI agents and AI gateway covers agent and model capabilities, tools, providers, execution, routing, and governance.
• Agentic UI and conversational workflows covers the user experience for expressing intent, reviewing plans, granting approval, observing progress, resolving failures, inspecting evidence, and understanding actions performed by agents.

The system inventory may merge, split, or rename these domains when evidence shows a different stable boundary.

Assessment unit: user and operator journeys

Each domain is assessed through meaningful end-to-end journeys. Examples include:

• Sign in through an account realm and accept an invitation
• Create an account cloud connection with credentials, network, and storage
• Provision, bootstrap, inspect, and retire a workspace
• Add a workspace member, assign a role, review access, and revoke it
• Navigate workspace folders, create or open content, share it, and recover from access or execution failures
• Discover and request access to data
• Browse a catalog, inspect metadata, assign ownership, and update governed descriptions or classifications
• Define ontology concepts, relationships, mappings, and governed semantic definitions
• Propose, review, resolve conflicts in, and publish an ontology change
• Run and recover a query
• Save, rename, share, visualize, and revisit a query
• Build, preview, publish, share, and govern access to a dashboard
• Create, clone, schedule, monitor, retry, and diagnose a workflow
• Create, validate, deploy, schedule, and monitor a data pipeline
• Retry, backfill, pause, resume, and recover a failed pipeline run
• Start and use a notebook environment
• Submit and observe a distributed compute job
• Track experiments and runs, register a model, and inspect model details
• Configure and run an AutoML or synthetic-data workflow
• Create and operate an AI Gateway endpoint, inspect traces and metrics, and apply routing, budget, rate-limit, or guardrail policy
• Complete a multi-step task through Cogrion Hub with plan review, confirmation, progress, evidence, and failure recovery
• Provision and inspect an account or workspace through the internal console

A journey remains one assessment unit even when it crosses multiple frontends, backends, repositories, databases, cloud resources, or external systems.

Supporting scope: components

Components are documented to explain which systems support a capability or journey. A component record includes:

• Purpose and responsibility
• Technical and operational owner
• Capabilities and journeys supported
• Inputs, outputs, and high-level dependencies
• Data owned or processed
• Deployment location
• Lifecycle status
• Failure impact
• Links to implementation documentation

Implementation details remain in the owning component repository. Platform documentation describes what happens and links to how it is implemented.

The component catalog must cover every known platform component discovered through repository, deployment, runtime, and owner inventories. Each component receives the same documentation treatment. A component that cannot be mapped to an owner, deployment, supported capability, or lifecycle status is recorded as an explicit documentation or assessment gap.

Platform-wide scope

The following concerns are documented once at platform level and assessed across all critical capabilities:

• Authentication and authorization
• Tenant isolation
• Data protection and privacy
• Infrastructure and networking
• Delivery and release management
• Reliability and observability
• Backup and disaster recovery
• Performance and capacity
• Cost management
• Ownership and lifecycle governance

Support status and limitations

Every capability and journey must state its current support status. Do not infer support merely because code, configuration, or a UI entry exists.

Use this vocabulary consistently:

Status	Meaning
Supported	Offered for normal use, has an owner, and has demonstrated evidence for its documented operating conditions
Conditionally supported	Supported only under explicitly documented clouds, environments, roles, integrations, capacities, or operational constraints
Preview	Available for evaluation, but behavior, compatibility, or operations may change and production commitments are limited
Experimental	Used for exploration without a production support commitment
Deprecated	Still available for a defined transition period but has a replacement or retirement decision
Unsupported	Known to exist or be technically possible, but not operated or committed as a platform capability
Unverified	Current behavior or support commitment has not yet been established with sufficient evidence

Each support claim must record:

• Capability and relevant journeys
• Status and effective date
• Supported actors and roles
• Supported cloud providers, regions, environments, and tenancy models
• Supported integrations, data sources, formats, and authentication modes
• Tested or contractual scale and performance boundaries
• Operational support and recovery expectations
• Explicit exclusions
• Known limitations and required workarounds
• Owning team
• Evidence or decision supporting the status

Limitations must be specific and observable. For example, document "workspace deletion does not remove external object-store data" rather than "deletion has some limitations."

Criticality

Assessment depth is determined by criticality:

Tier	Definition	Required depth
Tier 0	Identity, secrets, tenant isolation, networking, production data, or controls whose failure compromises the platform	Full evidence review and failure or recovery exercise
Tier 1	Customer-critical capability with material contractual, financial, or operational impact	Full journey and runtime review
Tier 2	Supporting capability with a documented workaround	Control review and targeted runtime verification
Tier 3	Experimental, replaceable, or low-impact capability	Inventory and exception-based review

Tier 0 and Tier 1 systems are assessed before lower-criticality systems.

Concrete deliverables

The objective produces two related sets of deliverables:

1. Canonical system and product documentation describing the current supported platform
2. Assessment artifacts evaluating the quality, risk, and maturity of that documented platform

System and product documentation deliverables

These pages live in the canonical docs/ hierarchy and remain maintained after the assessment ends. Information stays with the subject it describes; support conditions and limitations are not moved into separate global registers.

Use this structure:

docs/
├── index.md
├── architecture.md
├── use-cases.md
├── features/
│   └── <capability>/
│       ├── index.md
│       └── architecture.md
├── user-guide/
├── core-platform/
│   └── components/
├── tenant-platform/
│   ├── capabilities/
│   ├── open-source-components/
│   └── infra/
├── security/
├── platform-developer/
├── platform-testing/
├── decision-records/
└── assessments/
    ├── platform-assessment-plan.md
    └── 2026-platform-baseline/

This structure already exists. The documentation effort updates and fills it rather than introducing parallel capabilities, components, journeys, reference, or cross-cutting trees.

Naming convention

Use one directory per capability, with required index.md and architecture.md pages. Use descriptive kebab-case names without numeric prefixes for directories and additional pages, for example:

features/ontology/index.md
features/ontology/architecture.md
features/access-control/index.md
features/access-control/architecture.md
features/workflow/index.md
features/workflow/architecture.md

Control navigation order with Docusaurus sidebar_position frontmatter or _category_.json, not filename prefixes.

Numeric prefixes are not part of the target documentation design. The canonical paths in this plan use descriptive names even when the repository currently contains a numbered legacy filename. Any legacy rename must preserve incoming links and update internal references.

1. Platform overview and vocabulary

Files: docs/index.md and the canonical concept pages linked from it

Documents:

• Platform purpose and intended users
• Cogrion-managed and tenant-managed boundaries
• Core concepts and consistent terminology
• Major capability domains
• Platform-wide actors and roles
• Navigation to capabilities, journeys, components, and support information

2. Product capability and support documentation

Location: docs/features/

docs/features/ is the canonical home for what the product enables users to do. Every capability uses docs/features/<capability>/index.md and docs/features/<capability>/architecture.md; additional feature pages stay inside that capability directory.

Each capability index.md records:

• User or operator outcome
• Current support status
• Supported environments and operating conditions
• Supported roles, integrations, and data types
• Supported journeys and their current behavior
• Components involved
• States and lifecycle
• Failure and recovery behavior
• Owners
• Evidence date
• Known limitations, exclusions, and workarounds

Support information and limitations live directly on the relevant feature page. There is no global limitations register that readers must reconcile against the feature documentation.

Each capability architecture.md explains how the participating components collectively deliver that capability. It owns the end-to-end component view, control and data flows, state ownership, trust boundaries, deployment boundaries, failure propagation, recovery behavior, and observability for that capability.

3. User and operator journey documentation

Location: docs/user-guide/ for user procedures; concise behavior summaries may remain on the relevant page under docs/features/

Each journey page records:

• Intended outcome
• Actors and prerequisites
• Supported conditions
• Normal flow
• States and lifecycle transitions
• Components involved
• Data created, read, changed, or deleted
• Authorization decisions
• Failure, retry, cancellation, and recovery behavior
• Completion evidence visible to the user or operator
• Limitations and workarounds
• Links to component implementation documentation

Feature pages explain what is supported. User-guide pages explain how a user completes a task. The two link to each other and do not duplicate full content. Cross-feature journeys receive one canonical user-guide page rather than being split by participating backend or repository.

4. System and component documentation

Locations:

• docs/core-platform/ for Cogrion-managed system behavior and components
• docs/tenant-platform/ for tenant-side infrastructure, services, open-source components, and platform capabilities

Each component page records its purpose, owner, supported capabilities and journeys, high-level dependencies, data ownership, deployment location, lifecycle status, failure impact, and links to its owning repository.

Component pages describe platform responsibilities and boundaries, not internal implementation.

5. Architecture, security, and engineering documentation

Locations:

• docs/architecture.md for whole-platform context and boundaries
• docs/features/<capability>/architecture.md for end-to-end feature architecture
• docs/core-platform/ and docs/tenant-platform/ for reusable component and subsystem responsibilities
• docs/security/ and docs/authorization/ for security, identity, authorization, and tenant-boundary behavior
• docs/platform-developer/ for platform authoring and deployment guidance
• docs/platform-testing/ for platform testing expectations
• docs/decision-records/ for accepted architectural and engineering decisions

Use this ownership model:

Architecture scope	Canonical location	Owns
Platform	docs/architecture.md	Cogrion-versus-tenant context, control and data planes, trust boundaries, major infrastructure boundaries, and links to feature architectures
Feature	docs/features/<capability>/architecture.md	End-to-end architecture for one product outcome across every participating UI, backend, data store, infrastructure service, and external dependency
Component	docs/core-platform/ or docs/tenant-platform/	One reusable component's responsibility, ownership, state, dependencies, deployment location, failure impact, and supported capabilities
Implementation	Owning service repository	Internal modules, protocols, API details, schemas, classes, and implementation-specific decisions

Workflow example

The Workflow feature uses:

docs/features/workflow/
├── index.md
└── architecture.md

index.md owns supported workflow behavior, actors, environments, lifecycle, limitations, workarounds, and links to user guides.

architecture.md owns the end-to-end Workflow feature view:

Cogrion UI
→ BFF API
→ Workflow Backend
→ DAG repository
→ Airflow
→ execution infrastructure
→ status, logs, and monitoring

It documents component responsibilities, control and data flows, workflow state ownership, authentication, authorization, tenant boundaries, deployment boundaries, failure propagation, retry and recovery behavior, and observability. It links to the reusable component pages for Cogrion UI, BFF API, Workflow Backend, and Airflow, which in turn link to their owning repositories.

This pattern applies equally to Pipeline, Ontology, AI Gateway, Access Control, SQL, Dashboards, Agentic UI, and the other product capabilities.

Across these architecture scopes, document:

• Platform and service landscape
• Critical journey and data flows
• Cloud and Kubernetes topology
• Identity, authorization, and tenant boundaries
• Infrastructure and networking behavior
• Data governance and privacy expectations
• Delivery and release behavior
• Reliability, observability, backup, and disaster recovery
• Cost, performance, ownership, and lifecycle governance

Update an existing canonical page when one already covers the concept. New pages follow the nearest existing audience and subject boundary. Feature-specific support conditions and limitations remain under docs/features/.

Assessment deliverables

All deliverables live under the stable assessment identifier docs/assessments/2026-platform-baseline/. The directory name does not change when the assessment is completed, so links and evidence references remain durable. A later assessment receives a new dated identifier rather than replacing this baseline.

docs/assessments/2026-platform-baseline/
├── index.md
├── system-inventory.md
├── evidence-register.md
├── risk-register.md
├── capability-reviews/
├── workstream-reviews/
├── findings/
└── final/
    ├── executive-summary.md
    └── recommendations.md

1. Assessment charter

File: docs/assessments/2026-platform-baseline/index.md

Contains:

• Objective, scope, exclusions, and constraints
• Sponsor and assessment lead
• Product, design, architecture, platform, security, and service-owner responsibilities
• Start date and target completion date
• Evidence-handling rules
• Immediate-escalation process
• Review and decision cadence

2. System inventory

File: docs/assessments/2026-platform-baseline/system-inventory.md

One entry per repository, application, service, database, infrastructure stack, and external dependency. Each entry records:

• Purpose and owners
• Source and deployment location
• Users and supported capabilities
• Upstream and downstream dependencies
• Environments
• Data sensitivity
• Lifecycle status
• Criticality tier
• Documentation and operational-readiness status

3. Capability and journey reviews

Directory: docs/assessments/2026-platform-baseline/capability-reviews/

Each capability assessment contains:

• Purpose and expected outcome
• Actors and owners
• Critical journeys
• Components involved
• Data flow and state transitions
• Authentication, authorization, and tenant boundaries
• Normal behavior
• Failure and recovery behavior
• Observability and operational support
• Evidence collected
• Gaps and risks found

For each journey, test or inspect the happy path, invalid input, authorization failure, timeout, dependency failure, retry, cancellation, partial success, audit history, and recovery where applicable.

4. Workstream reviews and maturity scorecards

Directory: docs/assessments/2026-platform-baseline/workstream-reviews/

Create one evidence-backed scorecard for each workstream:

• Product and feature completeness
• UX and accessibility
• Application and integration architecture
• Infrastructure and cloud controls
• Security and privacy
• Data architecture and governance
• Reliability and operations
• Engineering quality and delivery
• Cost, performance, ownership, and lifecycle governance

Use this maturity scale:

Score	Meaning
0	No capability or control is evident
1	Ad hoc and person-dependent
2	Documented or partly automated, but inconsistently applied
3	Implemented, owned, and routinely verified
4	Measured, tested, and continuously improved

Do not calculate a single platform average. Report maturity by workstream and critical capability so severe gaps are not hidden by unrelated strengths.

The application-architecture review contains four bounded current-state views: the platform and service landscape, critical journey flows, cloud and Kubernetes topology, and identity, authorization, data, and trust boundaries. Each view states its scope, assumptions, owners, major dependencies, and failure boundaries.

5. Evidence register

File: docs/assessments/2026-platform-baseline/evidence-register.md

Each evidence entry records:

• Evidence ID
• Date collected
• Capability, journey, and component
• Workstream
• Source type
• Immutable commit, artifact version, or observation interval
• Collector
• Sensitivity
• Summary
• Related finding IDs

Valid evidence includes source and configuration, deployed behavior, test results, dashboards, alerts, incidents, support records, architecture decisions, interviews, and recovery exercises.

Secrets, tokens, customer data, or sensitive Terraform state must not be copied into the documentation.

6. Findings and risk register

Index: docs/assessments/2026-platform-baseline/risk-register.md

Detailed findings: docs/assessments/2026-platform-baseline/findings/<workstream>/<finding-id>-<short-name>.md

The risk register is a concise index, not the location of every finding's full analysis. It contains one row per accepted finding:

ID	Finding	Workstream	Affected capabilities	Severity	Confidence	Validation	Suggested owner	Detail
SEC-001	Example access-control gap	Security	Access control, workspace lifecycle	High	High	Owner validated	Security team	Finding link

Use stable workstream prefixes such as PROD, UX, ARCH, DATA, INFRA, SEC, REL, DEL, and GOV. IDs are never reused, even after a finding is resolved.

Each accepted finding has its own page. For example:

docs/assessments/2026-platform-baseline/
├── risk-register.md
└── findings/
    ├── product/
    ├── ux/
    ├── architecture/
    ├── data/
    ├── infrastructure/
    ├── security/
    ├── reliability/
    ├── delivery/
    └── governance/

Detailed finding format

Each detailed finding must be understandable without opening its remediation issue or reconstructing the problem from several evidence pages. Evidence may remain in a shared register, but the finding summarizes what that evidence proves and links directly to it. Use this order:

1. Finding ID and outcome-focused title
2. Where the problem appears — affected capabilities, journeys, product navigation, execution mode, environment, APIs, and components
3. Concrete observed case — representative input or action, actual result, and the user or operator consequence
4. Expected condition — the behavior, state, or architectural property that should replace the observation
5. Cause and evidence — verified source, configuration, deployment, runtime, or owner evidence; uncertain claims are labelled Unverified
6. Why it matters — credible product, UX, security, reliability, cost, data, operational, or lifecycle consequences without speculative inflation
7. Existing controls and workarounds — including their limits
8. Alternatives considered — the recommended outcome, feasible alternatives, trade-offs, and why rejected options do not solve the finding
9. Cross-component scope — affected frontend, BFF, data, platform, or operations responsibilities without turning the finding into an implementation plan
10. Reproduction and verification — repeatable steps, control cases, and the evidence needed to close remaining uncertainty
11. Resolution conditions — observable criteria that would allow the finding to be closed; implementation acceptance criteria remain in the remediation issue
12. Risk and confidence — impact, likelihood, exposure, total score, and evidence confidence
13. Ownership and status — owner validation or dispute, suggested accountable team, dependencies, blockers, and follow-up decision

The finding and remediation issue serve different readers but share the same facts. The finding explains the evidence, impact, decision space, and desired outcome. The issue turns that outcome into repository-specific work and testable delivery acceptance criteria. Neither may rely on the other to supply the affected location, concrete case, expected result, or alternatives.

Remediation issue format

When a finding is converted into a GitHub remediation issue, the issue must be self-contained. Do not require an implementer to infer the affected screen, current behavior, or intended solution from the finding ID or an assessment document. Use this order:

1. Outcome-focused title — name the user-visible or operational correction, not only the internal finding label.
2. Parent and evidence — link the parent assessment issue, canonical finding, reproduction evidence, and relevant design decision.
3. Where the problem appears — give the product navigation path, API or operator surface, affected mode, and environment when applicable.
4. Concrete broken case — show a representative input, current output, and resulting user or operator misunderstanding.
5. Cause — cite the verified frontend, backend, configuration, or deployment behavior responsible. Mark an unverified cause explicitly.
6. Expected experience or behavior — describe what the user or operator should see and what the system must preserve.
7. Alternatives considered — identify the recommended option, credible alternatives, and why rejected alternatives do not satisfy the outcome.
8. Work by repository or component — separate responsibilities when the fix crosses frontend, BFF, platform, data, or operations boundaries.
9. Reproduction and verification — provide numbered steps that another person can execute, including both the broken case and relevant control cases.
10. Acceptance criteria — state observable, testable completion conditions.
11. Non-goals, dependencies, and blockers — make scope limits and delivery ordering explicit.

Small issues may omit sections that genuinely do not apply, but must retain the affected location, concrete case, expected result, reproduction steps, and acceptance criteria. The risk-register row remains concise and links to the detailed finding and implementation issue; it does not duplicate this body.

Capability and journey assessment pages remain under capability-reviews/. They link to the relevant finding IDs but do not duplicate the finding analysis. A finding may affect several capabilities, and a capability may link to several findings.

Observations that do not meet the threshold for a formal finding remain in the relevant capability or workstream page and are not added to the risk register.

Calculate priority as:

impact × likelihood × exposure

Each factor is scored from 1 to 5:

• Critical: 80–125
• High: 45–79
• Medium: 20–44
• Low: 1–19

Confidence is recorded separately as High, Medium, or Low. Missing evidence is an assurance gap, not automatic proof that a control is absent.

7. Executive assessment report

File: docs/assessments/2026-platform-baseline/final/executive-summary.md

Contains:

• Overall platform condition
• Demonstrated strengths
• Five to ten most important systemic risks
• Immediate containment actions
• Decisions required from leadership
• Accepted residual risks
• Investment recommendations

The executive report links to detailed findings and evidence rather than duplicating them.

8. Prioritized recommendations

File: docs/assessments/2026-platform-baseline/final/recommendations.md

This document converts findings into decision-ready recommendations without planning or executing remediation. Each recommendation includes:

• Intended outcome
• Affected capabilities and systems
• Linked finding IDs
• Priority and rationale
• Suggested accountable team
• Dependencies and decision required
• Evidence that would demonstrate the outcome

Prioritize identity, tenant isolation, data recovery, deployment safety, and failure visibility before convenience improvements. Delivery estimates, committed dates, implementation tasks, and remediation sequencing are outside the assessment.

Assessment workstreams

The workstreams below are assessment lenses, not separate execution phases. Apply every applicable lens while reviewing one capability end to end, complete that capability's documentation and findings, and only then move to the next selected capability.

Product and feature completeness

Compare promised outcomes, documentation, support expectations, analytics, and observed behavior. Distinguish missing functionality from functionality that exists but is unreliable, difficult to discover, unmeasured, or operationally unsupported.

UX and design

Review information architecture, terminology, interaction consistency, empty and error states, long-running operations, destructive actions, accessibility, responsive behavior, and representative-user completion of critical journeys.

Application architecture

Review responsibilities, boundaries, dependency direction, API and event contracts, versioning, retries, timeouts, idempotency, tenant-context propagation, shared data, duplicate implementations, obsolete paths, and transitional systems.

Infrastructure and cloud

Review AWS accounts, networking, EKS, IAM, workload identity, Terraform state and locking, provider and module versions, Helm provenance, environment isolation, secrets, drift detection, approvals, rollback, backup restoration, capacity, and blast radius.

Security and privacy

Review trust boundaries, authentication, authorization, tenant isolation, privileged access, secret handling, public endpoints, encryption, artifact provenance, dependency and container vulnerabilities, third-party access, retention, deletion, and auditability.

Data

Review systems of record, ownership, lineage, contracts, quality controls, sensitive-data flows, retention, deletion, migration, backup consistency, replay safety, and recovery objectives.

Reliability and operations

Review service objectives, dashboards, alerts, runbooks, on-call ownership, incident history, logging, metrics, traces, capacity, deployment recovery, backup restoration, disaster recovery, and dependency failure behavior.

Engineering quality and delivery

Review the path from development through review, tests, security checks, artifact creation, promotion, deployment, verification, rollback, and identification of the deployed version. Include unit, integration, contract, end-to-end, infrastructure, migration, policy, and recovery testing.

Cost, performance, and governance

Review cost allocation, idle or duplicate resources, capacity limits, latency, throughput, upgrade cadence, dependency support status, ownership gaps, and whether components should be retained, consolidated, migrated, replaced, or retired.

Assessment roadmap

The roadmap is intentionally high level. The assessment cannot be estimated responsibly until the inventory reveals the actual capability scope, system boundaries, evidence availability, and owner dependencies. Progress and completion are determined by evidence-backed deliverables and the criteria below, not by elapsed time or a predefined number of capability reviews.

Phase	Focus	Output
Discover and prioritize	Inventory capabilities, repositories, deployed systems, environments, data stores, dependencies, owners, support status, criticality, and available evidence; agree which capabilities enter the assessment scope	Platform inventory, preliminary support matrix, evidence register, prioritized capability backlog, and explicit scope rationale
Assess capabilities	Take one prioritized capability at a time through the full vertical checklist below; complete its documentation, architecture, journey evidence, limitations, maturity assessment, and findings before starting another	Evidence-backed capability review with an explicit status of Complete, Partially assessed, Not assessed, or Unverified
Validate	Review capability evidence and conclusions with relevant product, engineering, platform, security, data, and operational owners; record disagreements and missing evidence	Owner-reviewed findings, resolved questions, and explicit blockers or unresolved claims
Synthesize and close out	Consolidate systemic findings, risk-score material gaps, prepare recommendations, and report the status of the agreed assessment scope	Evidence register, risk register, executive summary, prioritized recommendations, and backlog of remaining or blocked assessments

Access delays, unavailable owners, missing runtime evidence, and other dependencies are recorded as blockers. A blocked capability remains open with its current assessment status; evidence standards are not reduced and unfinished work is not represented as complete.

Vertical capability checklist

Complete this checklist for one capability before starting another:

1. Product contract: purpose, users, roles, support status, environments, feature gates, exclusions, limitations, and workarounds
2. Journeys and UX: normal flow, alternate flows, empty and error states, authorization failures, cancellation, retry, recovery, accessibility, and visible completion evidence
3. Feature architecture: participating UI, backends, data stores, infrastructure, external dependencies, control flow, data flow, state ownership, and deployment boundaries
4. Security and data: authentication, authorization, tenant isolation, privileged operations, auditability, sensitive data, retention, deletion, and third-party access
5. Infrastructure and operations: configuration, secrets, capacity, scaling, backup, restore, failure domains, observability, alerts, runbooks, on-call ownership, and recovery evidence
6. Engineering delivery: tests, contracts, migrations, CI/CD, artifact promotion, deployment verification, rollback, dependency health, and change ownership
7. Cost and lifecycle: material cost drivers, performance boundaries, support ownership, upgrade status, and retain, consolidate, replace, or retire decisions
8. Assessment outputs: evidence references, maturity scores, detailed findings, risk scores, confidence, owner validation, and recommendations

Anything that cannot be established remains explicitly Unverified with the missing evidence, blocker, and suggested accountable team recorded. Assumptions must not be converted into findings to create artificial progress.

Completion criteria

The system and product documentation is complete for the capabilities in the agreed assessment scope when:

• Every known capability is inventoried with a preliminary owner, support status, criticality, and assessment status.
• Each in-scope capability has a named owner and canonical page.
• Every critical user and operator journey within each in-scope capability documents its supported conditions, normal behavior, lifecycle, failure behavior, and recovery expectations.
• Each in-scope capability has an evidence-backed support status and last-verified date.
• Supported clouds, environments, roles, integrations, scale boundaries, and explicit exclusions are stated where applicable.
• Known limitations and workarounds are visible from the affected capability and journey pages.
• Components link to their owning repositories without duplicating implementation details.
• Current-state architecture and platform-wide behavior are consistent with the capability and journey documentation.
• Product, engineering, platform, and operational owners have reviewed the in-scope capability pages they own, or their unavailability is recorded as a blocker.

The assessment is complete when:

• Every known capability and production system is inventoried and maps to an owner and source or deployment location, or the absence is recorded as Unverified.
• Every capability in the agreed assessment scope has been assessed end to end across every applicable workstream lens.
• Each in-scope capability has canonical documentation, feature architecture, journey evidence, component links, limitations, maturity scores, and detailed findings.
• Critical user journeys within the in-scope capabilities have been examined beyond the happy path.
• Critical restore and failover claims have supporting evidence, or the missing demonstration is recorded as a finding.
• Findings are evidence-backed, owner-reviewed, risk-scored, and confidence-rated.
• Every Critical and High finding from the in-scope capability reviews has a clear recommendation, suggested accountable team, and required decision.
• Capabilities outside the agreed scope are clearly marked Not assessed, with their priority and known evidence gaps retained in the follow-up backlog.
• Unresolved questions and missing evidence are explicitly classified as Unverified.
• The executive summary and prioritized recommendations are delivered when their supporting completion criteria are met.
• No remediation implementation is included or represented as completed.