From 8c9fac80dbbe8246045df4d728ec6fc148339e81 Mon Sep 17 00:00:00 2001 From: vikingowl Date: Fri, 8 Aug 2025 20:57:01 +0200 Subject: [PATCH] [docs] add initial TODO.md with actionable backlog and prioritization --- TODO.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 TODO.md diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..4fb4580 --- /dev/null +++ b/TODO.md @@ -0,0 +1,158 @@ +This is a prioritized, actionable backlog to guide short-term improvements. Each item includes a short description, +priority, estimated effort, suggested owner(s), and acceptance criteria. Use this as a living document — update status +and estimates as you make progress. + +## How to use + +- Priority: P0 (highest), P1, P2. +- Effort: S (small, <1 week), M (medium, 1–2 weeks), L (large, 2+ weeks). +- Owner: team or role that should pick it up. +- AC: acceptance criteria — what "done" looks like. + +--- + +## 1. Populate this README & quickstart (P0, S) + +- Description: Add a short README and a "Getting started" quickstart with environment setup, how to run locally, and how + to run tests. +- Owner: Developer / Docs +- Effort: S +- Acceptance criteria: + - README contains: purpose, prerequisites, install steps, run steps, test command. + - Quickstart reproduces a working dev environment on a fresh machine. + - One developer verified it following the instructions. + +## 2. First-run onboarding & demo data (P0, M) + +- Description: Add an interactive first-run walkthrough and an optional "Try demo" mode that populates safe sample data. +- Owner: Product / Frontend +- Effort: M +- Acceptance criteria: + - First-run modal guides through top 3 core actions. + - Demo mode populates a non-destructive dataset and can be reset. + - Onboarding completion is tracked via an analytics event. + +## 3. Instrument basic analytics & events (P0, M) + +- Description: Add event instrumentation for key flows to measure adoption and drop-offs (onboarding, critical actions, + errors). +- Owner: Engineering / Product +- Effort: M +- Acceptance criteria: + - Tracking for: onboarding_start, onboarding_complete, core_action_X, error_high_priority. + - Events include a minimal context payload (non-sensitive): user-agnostic session id, event name, timestamp. + - Privacy opt-out toggle exists in settings. + +## 4. Improve error messages & in-app help (P0, S) + +- Description: Replace generic errors with actionable messages and add a Help/FAQ entry and a "Report a bug" flow that + optionally attaches logs. +- Owner: Frontend / QA +- Effort: S +- Acceptance criteria: + - Top 10 most common errors have specific messages and suggested next steps. + - A simple Help view exists with links to docs and a one-click "Report issue" action that collects an anonymized log + bundle (with consent). + +## 5. Add basic structured logging & correlation IDs (P1, M) + +- Description: Implement structured logs and add correlation IDs to sessions/requests to make debugging easier from logs + and error reports. +- Owner: Backend / Infra +- Effort: M +- Acceptance criteria: + - Logs emitted in JSON or consistent structured format. + - Correlation ID generated per session/request and included in error logs and any bug reports. + - Document how to search logs by correlation ID. + +## 6. CI: run tests, linter, and basic checks on PRs (P1, M) + +- Description: Add a CI pipeline that runs unit tests, a formatter/linter, and basic build checks for each PR. +- Owner: DevOps / Engineering +- Effort: M +- Acceptance criteria: + - PRs are blocked from merging if tests fail or the linter/format checks fail. + - Developers can run the same checks locally via a single script or Makefile. + +## 7. Add automated end-to-end tests for critical flow(s) (P1, L) + +- Description: Create a small suite of E2E tests that cover onboarding, signing in (if relevant), and the main user + flow. +- Owner: QA / Engineering +- Effort: L +- Acceptance criteria: + - At least 3 E2E tests added and green in CI. + - Tests are stable and do not flake more than a predefined threshold. + - Documentation on how to run and update tests exists. + +## 8. Performance profiling and one optimization (P2, M) + +- Description: Run a lightweight performance profile (CPU/memory) on the key path and implement one low-effort, + high-impact optimization (e.g., lazy-load a heavy module or add caching). +- Owner: Engineering +- Effort: M +- Acceptance criteria: + - Profile data collected and summarized (top 5 hotspots). + - One optimization implemented with measurable improvement (e.g., 20% faster load or 30% memory reduction). + - Benchmarks recorded in the repo. + +## 9. Output templates: add predefined template flags (P1, M) + +- Description: Provide CLI/UI flags to select from a set of predefined output templates (for example: json, csv, pretty, + report, compact). Each template controls formatting, default file extension, and optional post-processing steps. +- Owner: Product / CLI / Frontend +- Effort: M +- Acceptance criteria: + - Add flag (CLI): `--template ` and (UI) template selector in export dialog. + - Supported predefined templates documented (name, description, default extension). + - Template selection influences output format and default file extension automatically. + - Invalid template name produces a helpful error with a list of valid templates. + - Unit tests cover at least 3 templates and the error path. + +## 10. Output templates: add custom template paste & output extension flag (P1, M) + +- Description: Allow users to paste/provide a custom template (e.g., Mustache, Go template, or simple placeholder + format) and specify output extension via flag or UI input. Support local validation and a preview before writing + output. +- Owner: Product / CLI / Frontend +- Effort: M +- Acceptance criteria: + - Add flag (CLI): `--custom-template-file ` or `--template-paste ''`. + - Add flag (CLI): `--out-ext ` and (UI) an "Output filename/extension" input. + - Validate custom template at input time and show errors if malformed (with line/column hints when possible). + - Provide a preview option that renders a sample using demo data before saving. + - When `--out-ext` is provided, output file uses that extension; otherwise, use template's default extension or + fallback to `.txt`. + - Security: sanitize template execution context to avoid code injection; document limitations. + - Tests cover custom-template validation, preview rendering, and output extension resolution. + +--- + +## Nice-to-have / Future items (P2) + +- Accessibility audit and WCAG fixes (keyboard nav, aria labels). +- Feature flagging support for experimental rollouts. +- Localization prep (externalize strings). +- Observability: dashboards for errors, latency, adoption (define SLOs). + +## Developer experience & contributor friendliness + +- Improve README and contributing guide + - Add quickstart, environment setup, testing and release instructions. +- Add a clear issue/tracking template + - Bug template, feature-request template, and PR template to standardize contributions. +- Developer tooling + - Add static analysis tools, formatters, and pre-commit hooks to keep code consistent. + +## Quality of life improvements (UX polish) + +- Dark mode and theme support +- Keyboard-driven shortcuts and quick actions +- Contextual undo/redo where destructive actions exist +- Consistent microcopy and confirmation flows for destructive operations + +## Low-effort, high-value items to implement now + +- Add a single “Contact support / report a bug” action that attaches logs and repro steps (with user consent). +- Add usage telemetry opt-in/opt-out and a privacy policy summary. +- Implement a lightweight feature-usage dashboard to see which features customers actually use.