---
phase: 29-documentation
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - README.md
autonomous: true

must_haves:
  truths:
    - "User can find complete flag documentation for stash, checkout, switch, restore, grep, blame, clone, rm, mv, clean, config"
    - "User encountering interactive mode flags gets a clear explanation"
    - "All 217 v1.3 flags are documented in README"
  artifacts:
    - path: "README.md"
      provides: "Complete command reference"
      contains: "stash@{n}"
    - path: "README.md"
      provides: "Grep documentation"
      contains: "GREP-"
    - path: "README.md"
      provides: "Clone flags"
      contains: "--no-checkout"
  key_links:
    - from: "DOC-03"
      to: "README.md"
      via: "interactive mode notes"
    - from: "DOC-05"
      to: "README.md"
      via: "complete flag tables"
---

<objective>
Complete README.md documentation with remaining command flag tables and final polish.

Purpose: Complete the v1.3 documentation effort with stash, checkout, switch, restore, grep, blame, clone, rm, mv, clean, and config flag tables. Ensure all 217 requirements are reflected.

Output: README.md with complete flag documentation for all 25 supported commands.
</objective>

<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/29-documentation/29-RESEARCH.md
@README.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Update stash, checkout, switch, restore flag tables</name>
  <files>README.md</files>
  <action>
**git stash** - Expand existing table with STSH-01 to STSH-10:
- (existing rows preserved)
- -u/--include-untracked: Yes, translates to `-u`
- -m/--message: Yes, translates to `-m`
- show --stat: Yes, displays diffstat
- stash@{n}: Yes, maps to shelve names via lookup
- -p/--patch: Yes, translates to `-i` (interactive)
- -k/--keep-index: Warning (no staging area)
- -a/--all: Yes, includes ignored (uses `-u` + note)
- -q/--quiet: Yes, suppresses output
- push <pathspec>: Yes, selective file stashing
- branch <name>: Yes, creates bookmark + unshelve

Add note about interactive mode: "-p/--patch translates to sl shelve -i for interactive selection"

**git checkout** - Expand existing table with CHKT-05, CHKT-06:
- (existing rows preserved)
- --detach: Yes, translates to `--inactive`
- -t/--track: Note (limited emulation)
- -f/--force: Yes, translates to `sl goto -C` (SAFE-02)
- -m/--merge: Yes, translates to `sl goto -m` (SAFE-03)

**git switch** - Expand with CHKT-01, CHKT-02, CHKT-07 to CHKT-09:
- (existing rows preserved)
- -c/--create: Yes, creates and switches to new branch
- -C/--force-create: Yes, force creates if exists
- -d/--detach: Yes, translates to `--inactive`
- -f/--force/--discard-changes: Yes, translates to `-C`
- -m/--merge: Yes, passes through

**git restore** - Expand with CHKT-03, CHKT-04, CHKT-10, CHKT-11:
- (existing rows preserved)
- -s/--source=<tree>: Yes, translates to `-r <rev>`
- --staged/-S: Warning (no staging area)
- -q/--quiet: Yes, suppresses output
- -W/--worktree: Default (no-op, worktree is default)

Ensure checkout, switch, restore sections cross-reference where appropriate for users migrating from git checkout to git switch/restore.
  </action>
  <verify>Grep README for "stash@{n}" - should document shelve name lookup</verify>
  <done>Stash has 10+ flags, checkout has safety flags, switch has 6+ flags, restore has 5+ flags documented</done>
</task>

<task type="auto">
  <name>Task 2: Add grep, blame, clone flag tables</name>
  <files>README.md</files>
  <action>
**git grep** - NEW expanded section with GREP-01 to GREP-14:
- -n/--line-number: Yes, passes through
- -i/--ignore-case: Yes, passes through
- -l/--files-with-matches: Yes, passes through
- -c/--count: Warning (not supported)
- -w/--word-regexp: Yes, passes through
- -v/--invert-match: Yes, translates to `-V` (CRITICAL: uppercase!)
- -A <num>: Yes, passes through
- -B <num>: Yes, passes through
- -C <num>: Yes, passes through
- -h: Warning (sl -h shows help, not filename suppression)
- -H: No-op (already default)
- -o/--only-matching: Warning (not supported)
- -q/--quiet: Yes, passes through
- -F/--fixed-strings: Yes, passes through

Add prominent note: "**Critical:** git grep `-v` (invert match) translates to sl grep `-V` (uppercase). The lowercase `-v` in Sapling means verbose."

**git blame** - Update from "all flags passed through" to BLAM-01 to BLAM-07:
- -w: Yes, passes through (ignore whitespace)
- -b: Yes, translates to `--ignore-space-change` (CRITICAL: sl -b differs!)
- -L <start>,<end>: Warning (not supported)
- -e/--show-email: Warning (not supported)
- -p/--porcelain: Warning (not supported)
- -l: Warning (DO NOT pass through - sl -l means line number)
- -n/--show-number: Yes, passes through

Add prominent note: "**Critical:** git blame `-b` does NOT pass through directly. Sapling `-b` shows blank SHA1; use `--ignore-space-change` instead."

**git clone** - NEW section with CLON-01 to CLON-09:
- -b <branch>/--branch: Yes, translates to `-u <bookmark>`
- --depth: Warning (use --shallow)
- --single-branch: Warning (limited support)
- -o/--origin: Warning (not supported)
- -n/--no-checkout: Yes, translates to `-U`
- --recursive/--recurse-submodules: Warning (not supported)
- --no-tags: Warning (not supported)
- -q/--quiet: Yes, passes through
- -v/--verbose: Yes, passes through
  </action>
  <verify>Grep README for "invert-match" or "-V" - should document critical translation</verify>
  <done>Grep has 14 flags with critical warning, blame has 7 flags with critical warning, clone has 9 flags documented</done>
</task>

<task type="auto">
  <name>Task 3: Update rm, mv, clean, config tables and final polish</name>
  <files>README.md</files>
  <action>
**git rm** - Expand with RM-01 to RM-05:
- -f/--force: Yes, passes through
- --cached: Warning (no staging area)
- -n/--dry-run: Warning (not supported)
- -q/--quiet: Yes, suppresses output
- -r/--recursive: Filtered (sl recursive by default)

**git mv** - Expand with MV-01 to MV-04:
- -f/--force: Yes, passes through
- -k: Warning (not supported)
- -v/--verbose: Yes, passes through
- -n/--dry-run: Yes, passes through

**git clean** - Expand with CLEN-01 to CLEN-04:
- (existing rows preserved)
- -x: Yes, translates to `--ignored` (removes ignored too)
- -X: Warning (use --ignored only)
- -e <pattern>: Yes, translates to `-X` (exclude)

**git config** - Expand with CONF-01 to CONF-08:
- (existing rows preserved)
- --get: Yes, default behavior
- --unset: Yes, translates to `--delete --local`
- --list/-l: Yes, default behavior
- --global: Yes, translates to `--user`
- --local: Yes, passes through
- --system: Yes, passes through
- --show-origin: Yes, translates to `--debug`
- --all: Warning (not supported)

**Final polish:**
1. Update "Supported Commands" table at top to mark all commands as "Full" (remove any "Partial" for commands now fully documented)
2. Ensure rev-parse is marked "Full" instead of "Partial"
3. Check all tables use consistent format (| Flag | Supported | Translation/Notes |)
4. Ensure no duplicate sections exist after edits
  </action>
  <verify>`grep "Partial" README.md` should return empty (all commands now "Full")</verify>
  <done>Rm has 5 flags, mv has 4 flags, clean has 7+ flags, config has 8 flags. All commands marked "Full" in top table.</done>
</task>

</tasks>

<verification>
After all tasks complete:
1. `grep "stash@{n}" README.md` shows shelve lookup documentation
2. `grep -i "critical" README.md` shows warnings for grep -v and blame -b
3. `grep "Partial" README.md` returns nothing - all commands are "Full"
4. Count command sections - should be 18 (all supported commands)
5. README is comprehensive and navigable
</verification>

<success_criteria>
1. git stash documents all 10 STSH flags including stash@{n} and branch
2. git checkout/switch/restore document all CHKT flags with safety notes
3. git grep documents all 14 GREP flags with CRITICAL warning about -v -> -V
4. git blame updated from generic to 7 specific flags with CRITICAL warning about -b
5. git clone documents all 9 CLON flags
6. git rm, mv, clean, config all fully documented
7. Top "Supported Commands" table shows "Full" for all commands (no "Partial")
8. Interactive mode limitations noted (stash -p -> -i)
9. All 217 v1.3 flags reflected in documentation
</success_criteria>

<output>
After completion, create `.planning/phases/29-documentation/29-02-SUMMARY.md`
</output>
