ss-tools/specs/020-task-reports-design/plan.md

# Implementation Plan: Unified Task Reports by Type

**Branch**: `020-task-reports-design` | **Date**: 2026-02-22 | **Spec**: [`/home/busya/dev/ss-tools/specs/020-task-reports-design/spec.md`](specs/020-task-reports-design/spec.md)  
**Input**: Feature specification from [`/specs/020-task-reports-design/spec.md`](specs/020-task-reports-design/spec.md)

## Summary

Implement a unified reports experience that aggregates task outcomes across LLM documentation/verification, backups, migrations, and documentation into one report center with type-specific visual design. The approach extends existing task/result data flows and adds normalized report-view contracts so users can identify type, status, and next actions quickly while preserving current async task architecture and operational observability.

## Technical Context

**Language/Version**: Python 3.9+ (backend), Node.js 18+ (frontend)  
**Primary Dependencies**: FastAPI, SvelteKit, Tailwind CSS, SQLAlchemy/Pydantic task models, existing task/websocket stack  
**Storage**: SQLite task/result persistence (existing task DB), filesystem only for existing artifacts (no new primary store required)  
**Testing**: pytest (backend), Vitest (frontend), API contract tests for report endpoints  
**Target Platform**: Linux server backend + browser-based SPA frontend  
**Project Type**: Web application (frontend + backend)  
**Performance Goals**: Report list first render <2s for typical workload; filter response perceived immediate (<500ms UI update for already loaded data)  
**Constraints**: Must reuse existing TaskManager async model; no blocking task APIs; preserve RBAC boundaries; avoid breaking current dashboards/datasets/task pages  
**Scale/Scope**: Unified view for at least 4 report types; thousands of historical report entries, with pagination/filtering in UX

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

| Gate | Status | Notes |
|---|---|---|
| Semantic Protocol Compliance ([`constitution.md`](.ai/standards/constitution.md)) | PASS | New/updated modules will define [DEF] contracts in [`contracts/modules.md`](specs/020-task-reports-design/contracts/modules.md). |
| Modular Plugin Architecture | PASS | Feature consumes plugin/task outputs; no hardcoded config paths; existing config/dependency mechanisms retained. |
| Unified Frontend Experience | PASS | Tailwind-first UI, reuse existing API wrappers, and route all user-facing strings through i18n files in implementation phase. |
| Security & RBAC | PASS | Report visibility remains under existing auth/session and permission checks; no permission bypass in plan. |
| Independent Testability | PASS | Spec already defines independent user stories and acceptance scenarios. |
| Asynchronous Execution | PASS | Long-running operations remain task-based; reporting is read/aggregation over async outcomes. |

## Project Structure

### Documentation (this feature)

```text
specs/020-task-reports-design/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── modules.md
│   └── reports-api.openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
backend/
├── src/
│   ├── api/
│   │   └── routes/
│   ├── services/
│   ├── models/
│   └── core/
└── tests/

frontend/
├── src/
│   ├── lib/
│   │   ├── components/
│   │   ├── stores/
│   │   └── api/
│   └── routes/
└── tests/
```

**Structure Decision**: Use the existing web application split ([`backend/`](backend), [`frontend/`](frontend)) with feature additions in report-oriented API route/service and a dedicated frontend reports route/components. This minimizes architectural risk and conforms to existing module boundaries in [`PROJECT_MAP`](.ai/PROJECT_MAP.md).

## Phase 0: Research Focus

Research tasks derived from technical context and spec:

1. Best strategy to normalize heterogeneous task outputs (LLM, backup, migration, documentation) into one report DTO without losing type-specific meaning.
2. Pagination/filter tradeoffs for large report history while preserving UX scan speed from [`ux_reference.md`](specs/020-task-reports-design/ux_reference.md).
3. Error/fallback taxonomy for unknown task type and partial payloads consistent with existing task status model.
4. RBAC and privacy implications of consolidated cross-type reporting.
5. Contract strategy for mapping UX states (Loading/Empty/FilteredEmpty/Error) to backend/frontend boundaries.

## Phase 1: Design & Contracts Plan

1. Validate architecture against UX:
   - Ensure unified list + type-specific cards + fast filtering supports happy path.
   - Ensure explicit handling for Loading/No Data/Filtered Empty/Failed report detail states.
2. Produce [`data-model.md`](specs/020-task-reports-design/data-model.md) from spec entities and lifecycle rules.
3. Produce [`contracts/modules.md`](specs/020-task-reports-design/contracts/modules.md) with DEF headers, TIER, PRE/POST, UX state tags where applicable.
4. Simulate one full scenario through contracts (failed migration report discovery and triage path).
5. Produce API contract at [`reports-api.openapi.yaml`](specs/020-task-reports-design/contracts/reports-api.openapi.yaml) for backend/frontend sync.
6. Produce [`quickstart.md`](specs/020-task-reports-design/quickstart.md) for implementation and verification flow.
7. Run agent context updater script and record result.

## Complexity Tracking

No constitution violations identified; section intentionally empty.

## Test Data Reference

| Component | TIER | Fixture Name | Location |
|---|---|---|---|
| Unified Reports API Contract | CRITICAL | mixed_task_reports | [`spec.md`](specs/020-task-reports-design/spec.md) |
| Reports UI State Handling | CRITICAL | unknown_type_partial_payload | [`spec.md`](specs/020-task-reports-design/spec.md) |
| Report Filtering & Discovery | STANDARD | failed_reports_filterable | [`spec.md`](specs/020-task-reports-design/spec.md) |

**Note**: Tester implementation should materialize these fixtures in backend/frontend test suites during `/speckit.tasks` execution.