Why
A developer adding a new investigation type will not understand why investigations run in a separate worktree rather than the current directory, and may implement one that doesn't work correctly.
Current state
The worktree-based PR investigation flow — bare repo cloned to ~/.hub/repos/, PR fetched to a subdirectory, Claude launched there with cwd set to the worktree — is only partially explained in source comments. No architecture doc or TUI README describes this as a system. ui/tui/src/investigations/mod.rs contains the implementation but no prose explanation of the design.
Ideal state
- A section in
docs/architecture/ or the TUI README explains the worktree model as a system:
- Bare repos are cloned by
hub fetch to ~/.hub/repos/
- PR worktrees are created on demand at investigation time as subdirectories
cwd is set to the worktree before launching Claude- Why this model was chosen (isolation, no interference with the user's working tree)
Out of scope
Changing the worktree implementation.
Starting points
ui/tui/src/investigations/mod.rs — worktree creation and cwd setupworkflows/src/implement.rs — bare repo and worktree interactiondocs/architecture/ — target location for the new section
QA plan
- Open the relevant architecture doc or TUI README — expect a prose section describing the worktree model with the four points above.
- A developer reading only that section should be able to implement a new investigation type that correctly sets
cwd to a worktree path.
Done when
docs/architecture/ or the TUI README contains a section that explains the worktree model well enough that a developer can implement a new investigation type without reading investigation source code.
Why
A developer adding a new investigation type will not understand why investigations run in a separate worktree rather than the current directory, and may implement one that doesn't work correctly.
Current state
The worktree-based PR investigation flow — bare repo cloned to
~/.hub/repos/, PR fetched to a subdirectory, Claude launched there withcwdset to the worktree — is only partially explained in source comments. No architecture doc or TUI README describes this as a system.ui/tui/src/investigations/mod.rscontains the implementation but no prose explanation of the design.Ideal state
docs/architecture/or the TUI README explains the worktree model as a system:hub fetchto~/.hub/repos/cwdis set to the worktree before launching ClaudeOut of scope
Changing the worktree implementation.
Starting points
ui/tui/src/investigations/mod.rs— worktree creation andcwdsetupworkflows/src/implement.rs— bare repo and worktree interactiondocs/architecture/— target location for the new sectionQA plan
cwdto a worktree path.Done when
docs/architecture/or the TUI README contains a section that explains the worktree model well enough that a developer can implement a new investigation type without reading investigation source code.