l-refactor

Project-specific refactoring review covering Storybook, unit tests, e2e tests, sub-package separation, and documentation. Spawns 5 parallel reviewers with deep project context, applies fixes, and repe...

Project Refactoring Review

A project-specific review that goes beyond code quality (which /local-review handles) to check whether the project's support infrastructure — Storybook, tests, packages, and docs — are keeping up with the codebase.

Project Context

This is a Tauri v2 + Astro 6 monorepo app (zudo-text) with:

36 packages under /packages/ (app-defaults, app-scaffold, backend-bridge, cloud-crypto, cloud-sync, cm-ghost-text, cm-inline-command, cm-search-highlight, code-block, color-themes, command-palette, cross-pane-search, css-playground, design-token-lint, directive-registry, file-utils, find-in-page, frameset, frontmatter-schema, frontmatter-ui, gfm-table, inline-command-skills, kanban-board, kanban-parser, mindmap-board, mindmap-parser, remark-source-line, settings-sections, shortcut-engine, sync-logger, timeline-board, todo-board, todo-parser, ui-components, view-provider)
1 sub-package under /sub-packages/ (mdx-formatter)
~18 Storybook stories in /packages/ui-components/src/
~52 unit test files across packages (vitest + @testing-library/react)
Rust unit tests in /tauri-app/core/ (zudotext-core crate, testable without Tauri/GTK deps)
1 Playwright e2e spec in /e2e/ (web-based, runs against pnpm dev:mock on port 1421)
~59 doc pages in /doc/src/content/docs/ (Astro 6/zudo-doc site with 10 categories: architecture, backend-api, claude, claude-commands, claude-md, claude-skills, development, manual, overview, packages)
Pure Rust backend (/tauri-app/src/) — commands, file watchers, PTY management, HTTP server
React 19 frontend (/tauri-app/renderer/) with Tailwind CSS 4, CodeMirror 6, xterm.js
Backend bridge (/packages/backend-bridge/) — abstraction layer with 3 adapters: TauriAdapter (IPC), MockAdapter (in-memory), RestAdapter (HTTP/SSE)

Review Flow

Repeat the following cycle 3 times. Each round discovers new issues and fixes issues from the previous round.

Round N (N = 1, 2, 3)

Step 1: Run 5 Parallel Reviewers

Launch all 5 reviewers in a single message using subagent_type: "code-reviewer" with model: "opus".

Reviewer 1: Storybook Coverage & Quality

Review the Storybook stories in this zudo-text project.

PROJECT CONTEXT:
- Stories live in /packages/ui-components/src/ (*.stories.tsx)
- ~18 story files exist
- Components use React 19, Tailwind CSS 4
- The project follows: component-first design, tight token strategy, 3-tier color strategy (see /css-wisdom concepts)

REVIEW FOCUS:
1. Missing stories: Are there components without stories? Any new components added without corresponding stories?
2. Story quality: Do stories cover key states (default, loading, error, empty, disabled)?
3. Component-first design: Are components designed to be reusable and self-contained? Too specific UI should NOT be a Storybook component, but generic building blocks should be.
4. Token strategy: Do stories demonstrate the design token usage (spacing, typography, color tiers)?
5. 3-tier color strategy: Are components using semantic color tokens properly (not hardcoded colors)?
6. Interactive controls: Do stories use Storybook args/controls for interactive props?
7. Stale stories: Are any stories outdated or testing components that changed significantly?

IMPORTANT: Storybook tweaks are commonly forgotten during feature development. Be thorough.

REPORTING: Save FULL findings to the log file (as per your log generation rules).
Return to caller ONLY:
- Bullet list of high-priority findings (1 sentence each, max 5 items)
- The log file path

Reviewer 2: Unit Test Coverage & Quality

Review unit tests across the zudo-text project.

PROJECT CONTEXT:
- Test framework: vitest with @testing-library/react and jsdom
- ~52 test files in /packages/*/src/ directories (*.test.ts, *.test.tsx)
- Key packages with tests: ui-components, kanban-board, kanban-parser, color-themes, cloud-sync, backend-bridge, app-scaffold, app-defaults, shortcut-engine, command-palette, find-in-page, code-block
- Tauri app renderer tests in /tauri-app/renderer/ (if any)
- Rust unit tests in /tauri-app/core/ (zudotext-core crate — can be tested standalone with `cargo test`)

REVIEW FOCUS:
1. Coverage gaps: Which packages or modules lack test coverage? Especially for complex logic.
2. Outdated tests: Tests that test removed/changed functionality. Remove these.
3. Weak-point tests: Even if a test seems trivial, it may exist because of a past failure. KEEP tests that guard against regressions unless the tested code no longer exists.
4. Missing useful tests: Identify high-value test additions (complex state logic, edge cases, utility functions with branching).
5. Test quality: Are tests actually asserting meaningful behavior? Or just running without real assertions?
6. Test organization: Are test files co-located with source? Consistent naming?
7. Rust tests: Check /tauri-app/core/src/ for coverage — this crate mirrors Tauri command logic without Tauri dependencies.

IMPORTANT: Do NOT dismiss tests as "useless" — there may be historical context for why they exist. Only flag truly outdated ones (testing deleted code or changed APIs).

REPORTING: Save FULL findings to the log file (as per your log generation rules).
Return to caller ONLY:
- Bullet list of high-priority findings (1 sentence each, max 5 items)
- The log file path

Reviewer 3: E2E Test Coverage & Quality

Review the Playwright e2e tests in this zudo-text project.

PROJECT CONTEXT:
- E2E specs in /e2e/ (currently 1 spec file)
- Config: /playwright.config.ts
- Tests run against the mock dev server (pnpm dev:mock on port 1421)
- This is a Tauri v2 app but e2e tests run against the web frontend directly (no native app interaction)
- The app has: editor page, archives page, pins page, search page, settings dialog, command palette, terminal, kanban board, sync features

REVIEW FOCUS:
1. Coverage gaps: E2E coverage is minimal (1 spec). Identify the most valuable user flows to test: writing flow, draft management, navigation, settings, command palette, search, pins.
2. Missing critical paths: What user-facing flows have zero automated coverage?
3. Current test quality: Is the existing spec robust? Does it cover meaningful interactions?
4. Flaky patterns: Are there timing issues, race conditions, or brittle selectors?
5. Priority recommendations: Which 3-5 e2e specs would provide the most coverage value?

IMPORTANT: The e2e test infrastructure is early-stage. Focus on identifying highest-impact test additions rather than nitpicking the existing spec.

REPORTING: Save FULL findings to the log file (as per your log generation rules).
Return to caller ONLY:
- Bullet list of high-priority findings (1 sentence each, max 5 items)
- The log file path

Reviewer 4: Sub-Package Separation

Review the package structure in this zudo-text monorepo.

PROJECT CONTEXT:
- 36 packages under /packages/: app-defaults, app-scaffold, backend-bridge, cloud-crypto, cloud-sync, cm-ghost-text, cm-inline-command, cm-search-highlight, code-block, color-themes, command-palette, cross-pane-search, css-playground, design-token-lint, directive-registry, file-utils, find-in-page, frameset, frontmatter-schema, frontmatter-ui, gfm-table, inline-command-skills, kanban-board, kanban-parser, mindmap-board, mindmap-parser, remark-source-line, settings-sections, shortcut-engine, sync-logger, timeline-board, todo-board, todo-parser, ui-components, view-provider
- 1 sub-package under /sub-packages/: mdx-formatter
- Tauri app source: /tauri-app/renderer/ (React frontend, ~124 .ts/.tsx files), /tauri-app/src/ (Rust backend), /tauri-app/core/ (standalone Rust crate)
- Backend bridge provides 3 adapters: TauriAdapter (IPC), MockAdapter (in-memory), RestAdapter (HTTP/SSE)
- This is inherently a "can't-split" type application — a huge SPA. Full decomposition into microservices is NOT the goal.
- Sub-packaging is for FUTURE DEVELOPER UNDERSTANDING, not for deployment boundaries.

REVIEW FOCUS:
1. Feature clusters in tauri-app/renderer: Are there groups of files that form a cohesive feature and could be extracted to a package for clarity? (e.g., editor logic, file management, settings management)
2. Package boundary violations: Are packages reaching into each other's internals instead of using public APIs?
3. Misplaced code: Is there logic in one package that conceptually belongs in another?
4. Overly coupled code: Are there tight dependencies between packages that make them hard to understand independently?
5. Package API surface: Are package exports clean and well-defined?
6. Rust crate structure: Is the boundary between /tauri-app/src/ (Tauri-dependent) and /tauri-app/core/ (standalone) well-maintained?

IMPORTANT: Be conservative. Only suggest extraction when it genuinely improves understanding. Don't suggest splitting things that are naturally coupled. The goal is readability, not modularity for its own sake.

REPORTING: Save FULL findings to the log file (as per your log generation rules).
Return to caller ONLY:
- Bullet list of high-priority findings (1 sentence each, max 5 items)
- The log file path

Reviewer 5: Documentation Coverage & Quality

Review the documentation in this zudo-text project.

PROJECT CONTEXT:
- Doc site: Astro 6 (zudo-doc framework) at /doc/
- ~59 doc pages in /doc/src/content/docs/ organized in 10 categories:
  - architecture/ — backend-bridge, css-color-strategy, app-generation, app-lifecycle, draft-tab-sync, state-management, sync, workspace-config
  - backend-api/ — assets, draft-and-tabs, helpers, messages, pins, settings-and-workspace, sync-and-auth, terminal, watchers
  - claude/ — Claude Code integration overview
  - claude-commands/ — /l-b4push
  - claude-md/ — CLAUDE.md files documentation
  - claude-skills/ — b4push, l-local-tauriapp-build, l-refactor
  - development/ — adding-commands, build-and-deploy, dev-workflow, project-structure, testing
  - manual/ — getting-started, editor-and-preview, command-palette, pins, drafts, archives-and-search, settings-and-themes, terminal, find-in-page, kanban, sync, assets
  - overview/ — quick-start
  - packages/ — app-defaults, app-scaffold, backend-bridge, color-themes, find-in-page, mindmap-board, mindmap-parser, other-packages, ui-components

REVIEW FOCUS:
1. Outdated docs: Compare doc content against actual code. Are there docs describing features that changed or were removed?
2. Missing docs: Are there new features, packages, or architectural decisions that lack documentation?
3. Inaccurate docs: Do code examples, file paths, or config references in docs match the current state?
4. Package docs: Does each of the 14 packages have adequate documentation? Are missing packages covered under other-packages.mdx or do they need their own page?
5. Architecture docs: Do they reflect the current Tauri v2 architecture? Backend bridge, sync, kanban, etc.?
6. User manual: Does the manual cover all user-facing features?
7. Doc organization: Are docs in the right categories? Any orphaned or misplaced pages?

IMPORTANT: Outdated documentation is worse than no documentation. Prioritize accuracy.

REPORTING: Save FULL findings to the log file (as per your log generation rules).
Return to caller ONLY:
- Bullet list of high-priority findings (1 sentence each, max 5 items)
- The log file path

Step 2: Synthesize Findings

After all 5 reviewers return:

Merge and deduplicate findings across reviewers
Categorize by priority (High / Medium / Low)
Note cross-reviewer consensus (flagged by multiple reviewers = higher priority)
Read log files for detail when needed

Step 3: Present Findings to User

Present a clear summary grouped by review area. Include log file paths.

Format:

## Round N Findings

### Storybook
- [High] ...
- [Med] ...

### Unit Tests
- ...

### E2E Tests
- ...

### Sub-Package Separation
- ...

### Documentation
- ...

Step 4: Apply Fixes

High priority: Implement automatically
Medium priority: Implement if clearly safe; ask user if uncertain
Low priority: Skip — these become GitHub issues (see Step 6)
After fixes, run pnpm b4push to verify nothing broke

Step 5: Commit

After applying fixes, commit with a descriptive message:

refactor: round N - [summary of changes]

Step 6: Create GitHub Issues for Deferred Findings

After each round, create GitHub issues for findings that were NOT fixed in this round. This includes:

Low priority items that were skipped
Medium priority items that were deferred (uncertain or risky)
Consider-level suggestions from any reviewer (architectural improvements, refactoring opportunities)

Issue format:

gh issue create \
  --title "[refactor-review] <concise finding title>" \
  --body "$(cat <<'EOF'
## Finding

<description of the finding>

## Source

Found by `/l-refactor` reviewer: <reviewer name>
Round: <N>
Priority: <High/Medium/Low>

## Suggested Action

<what should be done to address this>

## Context

<relevant file paths, code references, or log file path>
EOF
)" \
  --label "refactor-review"

Rules for issue creation:

Create the refactor-review label first if it doesn't exist: gh label create refactor-review --description "Findings from /l-refactor review" --color "c5def5" (run once, ignore error if exists)
One issue per finding — don't bundle unrelated findings
Skip creating issues for findings that were already fixed in the current round
Skip duplicates — check existing open issues with the refactor-review label before creating
Keep issue titles concise and actionable (e.g., "[refactor-review] Add missing Storybook story for DiffViewerDialog")

After Round 3

Present a final summary comparing what was found and fixed across all 3 rounds
List all GitHub issues created during the review
Note any remaining items that need user decision

Important Notes

All 5 reviewers MUST launch in parallel in a single message using Opus model
This skill complements /local-review — it covers project infrastructure, not code quality
Respect existing tests even if they seem trivial — they may guard against past regressions
Sub-package suggestions should be conservative — readability over modularity
Documentation accuracy matters more than documentation completeness
Run pnpm b4push after each round of fixes to catch regressions
GitHub issues are created for deferred findings so they don't get lost — this is the key difference from /review-loop which only reports in-terminal