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

Quickstart: Unified Task Reports by Type

Purpose

Implement and validate the unified reports feature defined in:

• Spec: spec.md
• UX reference: ux_reference.md
• Plan: plan.md
• Data model: data-model.md
• Contracts: contracts/modules.md, contracts/reports-api.openapi.yaml

1) Backend implementation flow

1. Add report API route module under existing API routes structure.
2. Implement report aggregation/normalization service using canonical TaskReport envelope + type-specific details.
3. Enforce server-side filtering and pagination according to OpenAPI contract.
4. Ensure unknown task types map to fallback unknown and partial payloads are still returned.
5. Keep read-only/non-blocking behavior for report endpoints.

2) Frontend implementation flow

1. Add unified reports page route and connect to existing API wrapper layer (no native fetch).
2. Implement list view with type-specific visual profiles and explicit text labels.
3. Implement filter toolbar (type/status/time/search) and empty/error/loading states.
4. Add detail panel/page for selected report with diagnostics and next actions.
5. Ensure all user-facing strings are i18n-ready.

3) UX conformance checks (must pass)

• Loading state shows skeleton placeholders.
• No-data state appears when there are no reports at all.
• Filtered-empty state appears for strict filter combinations and supports one-click clear.
• Failed report shows clear reason + suggested next actions.
• Unknown type is visible with neutral fallback style.

4) Contract checks (must pass)

• API payloads match reports-api.openapi.yaml.
• Canonical minimum fields always present in list and detail.
• Status and task_type values conform to enumerations.
• Pagination metadata (total, has_next, applied_filters) is consistent.

5) Suggested validation commands

Backend tests (use project venv convention):

cd backend && .venv/bin/python3 -m pytest

Frontend tests:

cd frontend && npm test

Optional targeted API contract checks:

cd backend && .venv/bin/python3 -m pytest tests -k reports

6) Validation execution results (implementation run)

Backend targeted reports tests

Command:

cd backend && .venv/bin/python3 -m pytest tests/test_reports_api.py tests/test_report_normalizer.py tests/test_reports_detail_api.py tests/test_reports_openapi_conformance.py -q

Result:

• tests/test_report_normalizer.py: created and collected in run context.
• API-level tests requiring app import failed at collection in current environment due DB connection:
  • psycopg2.OperationalError / sqlalchemy.exc.OperationalError
  • connection refused to localhost:5432

Interpretation:

• Reports code/tests are in place, but full backend validation in this environment is blocked by unavailable database service.
• Re-run same command in environment with reachable DB to complete final verification.

7) Done criteria for planning handoff

• All planning artifacts exist and are internally consistent.
• UX states in ux_reference.md are mapped in module contracts.
• OpenAPI contract is stable for backend/frontend parallel implementation.
• Ready to decompose into executable work items via /speckit.tasks.