# Phase 0 Research: Unified Task Reports by Type

**Feature**: [`020-task-reports-design`](specs/020-task-reports-design)  
**Input Spec**: [`spec.md`](specs/020-task-reports-design/spec.md)  
**Related UX**: [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md)

## 1) Normalizing heterogeneous task outputs into one report model

### Decision
Adopt a two-layer report model:
1. **Canonical Report Envelope** shared across all task types.
2. **Type-Specific Detail Block** preserved per task type (LLM verification/documentation, backup, migration, documentation).

### Rationale
This preserves a uniform list/filter/sort experience while avoiding data loss from specialized task outcomes. It also aligns with the spec’s requirement for consistent minimum fields and type-specific design.

### Alternatives considered
- **Single fully generic schema only**: rejected because rich type-specific context becomes flattened and less actionable.
- **Separate endpoints and UI per type**: rejected because it breaks unified-report UX goal and increases navigation friction.

---

## 2) Pagination/filter strategy at report-history scale

### Decision
Use server-driven pagination and filtering as source of truth, with optional client-side refinement for currently visible page.

### Rationale
Large historical datasets require bounded payload sizes and stable response times. Server-side filtering supports scalable queries and predictable UX for “find failed report quickly” scenarios.

### Alternatives considered
- **Client-only filtering over full dataset**: rejected due to high transfer/memory cost and slow initial load at scale.
- **Infinite scroll without explicit pagination metadata**: rejected due to weaker operational predictability and harder QA validation.

---

## 3) Unknown type and partial payload fallback semantics

### Decision
Define deterministic fallback rules:
- Unknown type → render neutral “Other/Unknown” profile.
- Missing fields → show explicit placeholder text (“Not provided”).
- Status normalization maps all backend states into a fixed view state set: Success, Failed, In Progress, Partial.

### Rationale
This directly supports UX error-recovery expectations and prevents broken/blank interfaces when upstream task payloads vary.

### Alternatives considered
- **Hide malformed/unknown reports**: rejected because it reduces visibility and can hide operational incidents.
- **Hard-fail rendering on missing fields**: rejected due to poor resilience and degraded operator trust.

---

## 4) RBAC/privacy in consolidated reporting

### Decision
Inherit existing task visibility and permission checks; do not broaden data exposure in this feature.

### Rationale
Consolidation can accidentally reveal cross-domain details. Reusing current auth boundaries avoids privilege escalation and keeps rollout low risk.

### Alternatives considered
- **Open read access to all reports**: rejected due to security/privacy risk.
- **Introduce new role system in this feature**: rejected as out of scope and high change risk for current release.

---

## 5) UX state to contract mapping strategy

### Decision
Map UX states from [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md) into explicit module/API contracts using semantic tags:
- `@UX_STATE: Loading`
- `@UX_STATE: NoData`
- `@UX_STATE: FilteredEmpty`
- `@UX_STATE: Error`
- `@UX_STATE: Ready`

### Rationale
The project constitution and semantics standard require UX to be treated as contract logic, not decoration. Explicit state contracts reduce ambiguity for implementation and testing.

### Alternatives considered
- **Document states only in UX narrative**: rejected because it weakens enforceability and test traceability.
- **Encode states implicitly in code without contracts**: rejected due to lower semantic compliance and harder review.

---

## Consolidated Research Outcomes for Planning

- Canonical envelope + per-type details is the selected report modeling pattern.
- Server-side pagination/filtering is required for scalable history.
- Unknown/partial payloads must remain visible with fallback rendering.
- Existing RBAC boundaries remain authoritative for report visibility.
- UX states must be contract-bound in module definitions for implementation and QA traceability.