feat: improve using-git-worktrees with pre-flight checks and TDD tests

[EthanJStark]

Skill(using-git-worktrees) Improvements

Summary

Adds pre-flight checks, TDD test scenarios, and enhanced CSO description to using-git-worktrees skill based on production incident learnings.

Problem

Production failures revealed three gaps in the using-git-worktrees skill:

1. Nested worktree creation: Agent inside .worktrees/feature/ created worktree at .worktrees/feature/.worktrees/new/ instead of .worktrees/new/
2. Relative path errors: Using ../.worktrees/ from within worktree caused wrong-location creation
3. Bare repository confusion: Agent attempted git pull in bare repo root, unclear about primary workspace location

Solution

1. Pre-Flight Checks (commit 1)

• Detect if already in worktree (.git file vs directory)
• Navigate to main repo before creating worktree
• Detect bare repositories and provide guidance
• Enforce absolute path usage

2. TDD Test Scenarios (commit 2)

• test-nested-worktrees.md - Pressure test for nested creation
• test-path-resolution.md - Verify absolute path enforcement
• test-bare-repos.md - Bare repository handling
• CREATION-LOG.md - Documents TDD process (RED-GREEN-REFACTOR)

3. Enhanced CSO Description (commit 3)

• Added symptom keywords: "nested worktrees", "wrong paths", "bare repository confusion"
• Improves skill discovery when debugging issues
• Focuses on WHEN to use (triggers) not WHAT it does (workflow)

Testing

All improvements validated with pressure testing:

• ✅ Pre-flight checks detect worktree context correctly
• ✅ Absolute paths prevent wrong-location creation
• ✅ Bare repository detection prevents errors
• ✅ Test scenarios document expected behavior

Impact

• Reliability: Prevents three classes of production failures
• Discoverability: Better CSO triggers for troubleshooting
• Maintainability: TDD test scenarios enable regression testing
• Documentation: CREATION-LOG shows TDD-for-docs methodology

Files Changed

• skills/using-git-worktrees/SKILL.md - Pre-flight checks + absolute paths + CSO
• skills/using-git-worktrees/test-nested-worktrees.md - New test scenario
• skills/using-git-worktrees/test-path-resolution.md - New test scenario
• skills/using-git-worktrees/test-bare-repos.md - New test scenario
• skills/using-git-worktrees/CREATION-LOG.md - TDD process documentation

Summary by CodeRabbit

• Documentation
  • Expanded git worktrees guidance with detailed pre-flight validation, absolute-path practices, run-setup and verify-clean-baseline steps, and enhanced quick references and red flags.
• Tests
  • Added structured pressure-test scenarios for nested worktrees, path-resolution, and bare-repo handling with acceptance criteria, verification steps, and cleanup guidance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds comprehensive documentation for the git-worktrees skill: a CREATION-LOG describing a TDD approach, an expanded SKILL.md with pre-flight checks and absolute-path handling, and three new test/pressure documents for nested worktrees, path resolution, and bare-repo scenarios.

Changes

Cohort / File(s)	Summary
Core Skill Documentation skills/using-git-worktrees/SKILL.md	Expanded guidance: pre‑flight checks (detect in-worktree, detect bare repo), mandate absolute paths, clarified creation steps (cd into absolute path), added Run Project Setup and Verify Clean Baseline sections, updated Quick Reference and Red Flags, integration notes.
Test & Pressure Documents skills/using-git-worktrees/test-nested-worktrees.md, skills/using-git-worktrees/test-path-resolution.md, skills/using-git-worktrees/test-bare-repos.md	Added three new test docs covering nested-worktree prevention, absolute-path enforcement from subdirectories, and handling bare repositories; each includes setup, scenario, pre-flight checks, verification, success criteria, and cleanup.
Process / Postmortem skills/using-git-worktrees/CREATION-LOG.md	New creation log describing RED‑GREEN‑REFACTOR TDD cycle, failure modes (nested creation, relative paths, bare repos), planned tests, acceptance criteria, and lessons learned.

Sequence Diagram(s)

(omitted — changes are documentation and tests; no new multi-component control flow to visualize)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• fix: use git check-ignore for worktree gitignore verification #160: Touches skills/using-git-worktrees/SKILL.md and addresses worktree ignore verification (replaces grep-based checks with git check-ignore / absolute-path handling).

Suggested reviewers

• yoavsion

Poem

🐰 I hopped through branches, paths made bright,
Pre-flight checks stitched wrongs to right,
No nested nests, no bare‑repo fright,
With absolute steps I bound the site,
Hooray — the worktrees sleep tonight! 🌿

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main changes: introducing pre-flight checks and TDD test scenarios to the git-worktrees skill to address production issues.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@skills/using-git-worktrees/SKILL.md`:
- Around line 20-29: Replace the brittle root-only check that uses `[ -f .git ]`
with a root-independent check using `git rev-parse --git-dir` (capture its
output into a variable like `git_dir`) and test whether that path is a file to
detect a worktree; if it is a file, derive the main repository path from
`git_dir` (strip the trailing `/.git`) into `main_repo` and `cd "$main_repo"` as
before. Update the block that currently defines `main_repo` and checks `.git` to
use `git_dir=$(git rev-parse --path-format=absolute --git-dir 2>/dev/null)` then
`if [ -f "$git_dir" ]; then ...` so the detection works from any subdirectory.

In `@skills/using-git-worktrees/test-path-resolution.md`:
- Around line 56-66: The pre-flight check using a file test on .git is fragile;
replace it with a root-independent comparison of git directories by calling git
rev-parse --path-format=absolute --git-dir and git rev-parse
--path-format=absolute --git-common-dir, assign them to git_dir and
git_common_dir, and if they differ emit a warning (e.g., "Already in a worktree.
Navigate to main repo first.") so the doc/example reliably detects being inside
a worktree from any subdirectory.

[obra]

Can you please share a human-written description of what problem you were having and how these changes you made solved the problem?

Also, the test documents don't look a lot like our standard testing methodology. Can you talk me through what was going on there?