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
Input: Feature specification from /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)	PASS	New/updated modules will define [DEF] contracts in 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)

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)

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/, 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.

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.
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 from spec entities and lifecycle rules.
3. Produce 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 for backend/frontend sync.
6. Produce 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
Reports UI State Handling	CRITICAL	unknown_type_partial_payload	spec.md
Report Filtering & Discovery	STANDARD	failed_reports_filterable	spec.md

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