Copy these into GitHub Issues when the repository is public. They are not already created on GitHub. Do not file duplicates.
Suggested labels are listed on each draft.
Labels: good first issue documentation beginner
Problem: New contributors may miss backend/.env, pytest from repo root, or Windows-only constraints.
Why it matters: Public onboarding fails if setup is ambiguous.
Proposed direction: Tighten README / docs/development.md with the exact commands that exist in package.json and pytest.ini. Add a short troubleshooting subsection (port 8000 in use, missing Gemini key, missing ffmpeg).
Acceptance criteria: A new contributor can follow docs without inventing commands; no secrets in examples.
Difficulty: beginner · Area: docs · Files: README.md, docs/development.md
Labels: good first issue backend python
Problem: Validation failures can be terse (Forbidden parameter, generic 404/400).
Why it matters: Developers and users cannot tell what was rejected.
Proposed direction: Map ActionValidationError to clearer API/TTS-safe messages without leaking internals. Keep safety behavior unchanged.
Acceptance criteria: Tests cover at least one forbidden-parameter and one unknown-action message; no validator bypass.
Difficulty: beginner · Area: backend · Files: action_validator.py, command_service.py, tests/backend/test_action_validator.py
Labels: good first issue testing python
Problem: Discovery ranking and match modes need more fixtures (contains vs exact, disabled buttons, nested names).
Why it matters: UI discovery is easy to regress.
Proposed direction: Extend tests/backend/test_element_discovery.py with synthetic UiElementNode trees. No live Windows required.
Acceptance criteria: New tests pass in CI; no production behavior change unless a real bug is found (then fix in a linked issue).
Difficulty: beginner · Area: testing · Files: element_discovery.py, tests/backend/test_element_discovery.py
Labels: enhancement backend python
Problem: Summaries can be noisy or miss the field Gemini needs (path, title, process).
Why it matters: Planning and replanning consume the summary, not the full tree.
Proposed direction: Tune summarizer.py for compact, stable lines. Do not store full trees in session context.
Acceptance criteria: Unit tests for Explorer, Notepad, and Chrome-like snapshots; length stays bounded by existing constants.
Difficulty: intermediate · Area: observation · Files: backend/app/core/observation/summarizer.py, tests
Labels: enhancement Windows UI Automation phase-3
Problem: Filesystem collector sometimes reports unknown path even when Explorer is open.
Why it matters: Follow-ups like “us folder me …” need active_explorer_path.
Proposed direction: Strengthen address-bar / window-title heuristics in filesystem_collector.py without inventing paths. Preserve None when unknown.
Acceptance criteria: Tests for D:\ and nested folder titles; never guess a drive.
Difficulty: intermediate · Area: observation · Files: filesystem_collector.py, computer_updater.py, tests
Labels: enhancement Windows UI Automation
Problem: Multiple matches (empty names, list vs tree items) can pick a weak element.
Why it matters: Semantic click/select fails or hits the wrong control.
Proposed direction: Document ranking in element_discovery.py; prefer enabled+visible+name match; add tests for ties.
Acceptance criteria: Documented ranking; tests; no coordinate fallback.
Difficulty: intermediate · Area: computer control · Files: element_discovery.py
Labels: testing Windows
Problem: Unit tests mock UIA; real Notepad regressions slip through.
Proposed direction: Mark a pytest module windows_integration skipped unless RACCHHA_WINDOWS_INTEGRATION=1. Launch Notepad, type, observe. Do not run on Linux CI.
Acceptance criteria: Default CI unchanged; opt-in test documented; does not modify user files.
Difficulty: intermediate · Area: testing · Files: tests/backend/, docs/development.md
Labels: testing Windows
Problem: Same as Notepad for Explorer navigation.
Proposed direction: Opt-in tests for navigate_path to a disposable test folder or D:\ if present; skip if the path is missing.
Acceptance criteria: No CI breakage; no deletion of user files.
Difficulty: intermediate · Area: testing · Files: tests/backend/
Labels: enhancement phase-3 Windows architecture
Problem: Users say “brightness badhao” / “thoda aur”. There is no typed brightness action yet.
Why it matters: Phase 3 system controls should be first-class actions, not shell scripts, and not hardcoded NL maps.
Proposed direction: Research a Windows API/WMI/UIA Settings path. Propose ActionType + validator + safety limits. Implement only after architecture review.
Acceptance criteria: Design note; no PowerShell one-liners; tests for validation; Gemini prompt examples only after the action exists.
Difficulty: advanced · Area: computer control · Files: models.py, safety_policy.py, action_validator.py, prompt_builder.py
Labels: enhancement phase-3 Windows
Problem: Volume/mute is not a typed ComputerAction.
Why it matters: Common voice request; must stay allowlisted and reversible.
Proposed direction: Core Audio / UI Automation Settings. Same pattern as brightness: schema → validator → executor → observation if possible.
Acceptance criteria: No arbitrary shell; unit tests for validation; documented limitations (per-app vs master volume).
Difficulty: advanced · Area: computer control
Labels: research phase-3 Windows
Problem: “Video pause karo” is a user goal; implementation may be media keys, UIA, or Chrome.
Why it matters: Wrong channel (global media key vs Chrome CDP) causes surprising behavior.
Proposed direction: Research issue: compare media key vs focused-window UIA vs browser. Write findings before coding.
Acceptance criteria: Written recommendation; no implementation required in this issue.
Difficulty: research · Area: architecture
Labels: enhancement phase-3 Windows
Problem: ms-settings: launch exists; deeper settings pages are not modeled.
Why it matters: Users expect “open display settings”, not a dump of all Settings URIs.
Proposed direction: Small allowlist of settings URIs as parameters on a typed action. Reject unknown URIs.
Acceptance criteria: Allowlist tests; no open-ended URI execution.
Difficulty: intermediate · Area: computer control · Files: app_launcher.py, safety_policy.py
Labels: research phase-4
Problem: Some apps expose poor UIA trees. OCR/screenshots are not implemented (by design in Phase 2).
Why it matters: Vision should be a fallback, not a replacement for semantic UIA, and not an unrestricted clicker.
Proposed direction: Survey libraries, privacy (screenshots stay local), how OCR hits become selectors not raw coordinates.
Acceptance criteria: Research write-up; no production OCR in this issue.
Difficulty: research · Area: perception
Labels: AI Gemini testing
Problem: Replan quality is hard to measure; tests use StaticReplanProvider.
Proposed direction: Golden JSON fixtures: given a failed step + summary, expected action types. Optional recorded Gemini responses in tests (no live API in CI).
Acceptance criteria: Fixture tests for parse/validate; forbidden actions still rejected.
Difficulty: intermediate · Area: goal · Files: planning_provider.py, replan_prompt_builder.py, tests/backend/test_goal_replan.py
Labels: enhancement browser automation architecture
Problem: Browser workflows often use the legacy execute/plugin path; goal mode may not delegate cleanly to CDP.
Why it matters: Unified “Chrome kholo aur search karo” should not require two mental models forever.
Proposed direction: Design typed browser actions or a safe handoff to existing BrowserController without rewriting CDP internals.
Acceptance criteria: Architecture issue first; then a small vertical slice with tests.
Difficulty: advanced · Area: browser · Files: automation/, goal/, Chrome plugin
Labels: enhancement architecture
Problem: Allowlists are scattered (safety_policy, plugins, prompt text).
Why it matters: Contributors add apps in one place and forget validator/prompt.
Proposed direction: A single registry of allowlisted apps and supported action kinds. Prompt builder and validator read it. Not a hardcoded NL command dictionary.
Acceptance criteria: Launching a new allowlisted app requires one registry update plus tests.
Difficulty: intermediate · Area: architecture · Files: safety_policy.py, prompt_builder.py
Labels: testing performance architecture
Problem: GitHub Actions uses windows-latest and still depends on native packages. A fake observation/CCL would let more tests run anywhere.
Why it matters: Faster PRs; less flake from real UIA.
Proposed direction: Protocol/fake ObservationService and ActionExecutor already used in unit tests — extract a supported test double package. Keep Windows job for native import smoke if needed.
Acceptance criteria: Documented fake; no production code path that “runs” the fake on user machines.
Difficulty: advanced · Area: testing
Labels: performance Windows research
Problem: Tree capture has depth/node caps; still can be slow on busy desktops.
Why it matters: Goal loops capture observation many times.
Proposed direction: Script that logs capture time and node counts; recommend cap tweaks with evidence. Do not raise caps blindly.
Acceptance criteria: Benchmark script + notes in docs; no default cap change without data.
Difficulty: intermediate · Area: observation · Files: observation/constants.py, scripts/
Labels: documentation good first issue
Problem: docs/architecture.md is accurate but could use a sequence diagram for one Notepad goal.
Why it matters: New AI/backend contributors get lost in modules.
Proposed direction: Add mermaid sequence: utterance → intent → plan → observe → act → verify → TTS.
Acceptance criteria: Diagram matches code (CommandService, GoalExecutor).
Difficulty: beginner · Area: docs · Files: docs/architecture.md
Labels: frontend typescript react
Problem: Backend errors may surface poorly in the Electron UI.
Proposed direction: Map HTTP status to a short spoken/UI message; never show stack traces or env values.
Acceptance criteria: Frontend test for error mapping; no speech-pipeline rewrite.
Difficulty: beginner · Area: frontend · Files: frontend/src/api/, frontend/src/hooks/
Labels: documentation AI good first issue
Problem: Model names and free-tier rules change.
Why it matters: README must not promise a permanently free model.
Proposed direction: Link to Google’s current Gemini API docs; keep placeholders in .env.example.
Acceptance criteria: README Gemini section has no hardcoded “always free” claim.
Difficulty: beginner · Area: docs
Labels: security documentation
Problem: Expanding ALLOWED_APPLICATIONS is a security decision.
Why it matters: Each new executable is a new blast radius.
Proposed direction: Checklist in SECURITY.md or docs: why this app, how it launches, how it is observed, tests required.
Acceptance criteria: Checklist exists; referenced from CONTRIBUTING.
Difficulty: beginner · Area: security · Files: SECURITY.md, safety_policy.py (comment/link only unless implementing an app)