vikingowl/polyscribe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d531ac0b96afa778b1b2b8fe656663dec9bb183f
polyscribe/TODO.md

7.2 KiB
Raw Blame History

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 <template_name> 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 <path> or --template-paste '<template_string>'.
    • Add flag (CLI): --out-ext <extension> 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.