Remaining onboarding and documentation issues

[nhorton]

A consolidated list of open issues from manual testing of the DeepWork plugin install and authoring experience. Issues #3, #10, #11, and #12 from the original list were addressed in the new_user onboarding improvements PR.

---

P1 — High-friction onboarding

#1 — "Personal" category not visible in Cowork plugin install UI

Status: Fix in flight — #379

The install instructions say "Customize with plugins → Personal → +", but the "Personal" category wasn't visible in Claude Desktop (April 2026). User eventually got it installed via a different path.

Fix: Update install docs to match current Cowork UI.

#8 — Cowork Desktop install path skips the onboarding walkthrough

Status: Open

The CLI install path ends with "run /deepwork:new_user to finish onboarding." The Cowork Desktop path doesn't surface this step — users land with the plugin installed but no guided tour.

Fix: Auto-invoke /deepwork:new_user after install, or show a visible CTA to run it.

#9 — Slash-command names differ between CLI and Claude Desktop

Status: Open

CLI uses namespaced form (/deepwork:review); Desktop uses short form (/review). Docs are written in the namespaced form, so Desktop users get "unknown command" errors when following the docs.

Fix: Unify on the namespaced form in both surfaces for collision safety.

Note: After accumulating Desktop-specific issues (#1, #3, #7, #8, #9), user abandoned the Desktop path and used CLI instead.

#13 — Claude Code was very slow during DeepWork sessions; fixed by switching to Sonnet

Status: Resolved

Simple tasks were taking several minutes to complete. Switching from Claude Opus to Claude Sonnet fixed it immediately — Opus is significantly slower and it compounds over multi-step sessions.

Recommendation: Default to Sonnet for DeepWork sessions unless reasoning depth specifically requires Opus.

---

P2 — Authoring and documentation improvements

#2 — No published JSON schema for .deepreview files

Status: Open

job.yml has a machine-readable schema (job.schema.json) for editor autocomplete and validation. .deepreview files have prose docs only — no autocomplete, no typo detection, errors surface at runtime. Three schema violations in initial .deepreview files were caught only when running the review.

Fix: Publish deepreview.schema.json analogous to job.schema.json.

#4 — Three Review strategies are hard to distinguish from the README

Status: Open

The repo README doesn't make the three strategies easy to tell apart at a glance. Understanding required reading README_REVIEWS.md and SKILL.md inside the installed plugin.

Fix: Lead the strategies section with a comparison table (name | what reviewer sees | use when), then expand into prose.

#5 — Public docs headline example ("competitive marketing analysis") is a rare task

Status: Open

The example on deepwork.md is a task engineering teams rarely repeat, which undermines the "repeatable automated workflow" value prop.

Fix: Replace with something engineering teams do daily or per-sprint: standup digest, per-PR review, release notes draft, issue triage.

#6 — Reviews are underemphasized relative to Workflows in public docs

Status: Open

Reviews aren't featured on the homepage and aren't in the example jobs. For a team that wants to enforce PR rules, Reviews are the primary value — the docs don't reflect this.

Fix: Elevate Reviews to peer status with Workflows on the homepage; demote Schema to a subsection.

---

Windows / PowerShell issues

Reported from testing DeepWork with PowerShell on Windows.

W1 — CLAUDE_CODE_SESSION_ID not set

register_session_job requires a session_id parameter. The CLAUDE_CODE_SESSION_ID environment variable was not present in the shell environment.

Workaround: Generated a manual session ID using date +%s.

W2 — DeepWork project_root path malformed

start_workflow returned project_root as C:WINDOWS\system32\weekly_status (missing \ after C:). This caused every finished_step call to fail with [WinError 3]. The DeepWork MCP server's Python path handling drops the backslash after the drive letter on Windows.

Workaround: Used quality_review_override_reason to bypass file verification on every step.

W3 — Path format inconsistency across tools

Bash/Git use Unix paths (/c/WINDOWS/system32/...), Windows native uses C:\WINDOWS\system32\..., DeepWork server stores C:WINDOWS\system32\... (broken). cygpath -w converts correctly but the DeepWork server still can't resolve.

W4 — DeepWork job not discoverable

A job existed on disk at .deepwork/jobs/decision_apps_smoke_test/job.yml but get_workflows didn't list it. Had to manually register it via register_session_job. Likely a Windows-specific path resolution issue.

W5 — Multiple Chrome extensions connected error

Intermittent Multiple Chrome extensions connected error from Claude in Chrome MCP tools. Resolved by retrying. Also got No Chrome extension connected once, requiring manual reconnect.