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

must_haves:
  truths:
    - "User can find a complete flag compatibility matrix in README.md"
    - "User encountering unsupported staging flags gets a clear explanation"
    - "User can see accurate status for log, diff, show, status, add, commit, branch, and rev-parse commands"
  artifacts:
    - path: "README.md"
      provides: "Comprehensive documentation"
      contains: "Staging Area Limitations"
    - path: "README.md"
      provides: "Flag tables"
      contains: "--graph"
    - path: "README.md"
      provides: "Rev-parse documentation"
      contains: "--show-toplevel"
  key_links:
    - from: "DOC-01"
      to: "README.md"
      via: "flag tables for each command"
    - from: "DOC-02"
      to: "README.md"
      via: "Staging Area Limitations section"
---

<objective>
Update README.md with comprehensive flag compatibility documentation for the first set of commands.

Purpose: Users need accurate documentation reflecting the v1.3 Flag Compatibility milestone implementation. The current README is outdated - it says --graph and --format are "Not implemented" when they are now fully supported.

Output: README.md with updated structure, Staging Area Limitations section, and accurate flag tables for log, diff, show, status, add, commit, branch, and rev-parse 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: Add Staging Area Limitations and Common Translations sections</name>
  <files>README.md</files>
  <action>
Add two new sections after the "Command Reference" heading but before the per-command sections:

1. **Staging Area Limitations** section explaining Sapling has no staging area:
   - Table of affected flags: diff --staged/--cached, restore --staged/-S, stash --keep-index, commit -a, rm --cached
   - Each shows behavior (warning, removed, etc.)
   - Brief explanation of Sapling workflow (no staging step, commit directly)

2. **Common Flag Translations** quick reference table:
   - Show key translations: --author= -> -u, --graph -> -G, -n (limit) -> -l, --global -> --user, etc.
   - Include critical translations with notes: grep -v -> -V (uppercase!), blame -b -> --ignore-space-change

Keep the sections concise but complete. Users scanning the README should understand staging limitations quickly.
  </action>
  <verify>Grep README.md for "Staging Area Limitations" and "Common Flag Translations" - both sections should exist</verify>
  <done>README has dedicated sections explaining staging limitations and common translations</done>
</task>

<task type="auto">
  <name>Task 2: Update log, diff, show flag tables</name>
  <files>README.md</files>
  <action>
Replace the minimal "git log" section with comprehensive flag table covering LOG-01 to LOG-20:

**git log** table should include:
- --graph: Yes, translates to `-G`
- --stat: Yes, passes through
- --patch/-p: Yes, passes through
- --author=<pattern>: Yes, translates to `-u <pattern>`
- --grep=<pattern>: Yes, translates to `-k <pattern>`
- --no-merges: Yes, passes through
- --all: Yes, passes through
- --follow: Yes, translates to `-f`
- --since/--after: Yes, translates to `-d ">date"`
- --until/--before: Yes, translates to `-d "<date"`
- --name-only: Yes, uses template
- --name-status: Yes, uses template
- --decorate: Yes, uses template with bookmarks
- --pretty/--format: Yes, maps to `-T` template
- --first-parent: Yes, revset approximation
- --reverse: Yes, revset approximation
- -S/-G (pickaxe): Warning, no sl equivalent
- -n/--max-count: Yes, translates to `-l`
- --oneline: Yes, uses template

**git diff** - NEW section with DIFF-01 to DIFF-12:
- --stat: Yes, passes through
- -w/--ignore-all-space: Yes, passes through
- -b/--ignore-space-change: Yes, passes through
- -U<n>/--unified=<n>: Yes, passes through
- --name-only: Yes, uses `sl status -mard`
- --name-status: Yes, uses `sl status -mard`
- --staged/--cached: Warning (no staging area)
- --raw: Yes, passes through
- -M/--find-renames: Yes, passes through
- -C/--find-copies: Yes, passes through
- --word-diff: Yes, passes through
- --color-moved: Warning (not supported)

**git show** - Update from "all flags passed through" to specific table with SHOW-01 to SHOW-08:
- --stat: Yes, passes through
- -U<n>: Yes, passes through
- -w: Yes, passes through
- --name-only: Yes, uses template
- --name-status: Yes, uses template
- --pretty/--format: Yes, maps to `-T` template
- -s/--no-patch: Yes, passes through
- --oneline: Yes, uses template

Use consistent table format: | Flag | Supported | Translation/Notes |
  </action>
  <verify>Grep README for "--graph" - should now show "Yes" not "Not implemented"</verify>
  <done>Log has 20 flags documented, diff has 12 flags documented, show has 8 flags documented with accurate translation info</done>
</task>

<task type="auto">
  <name>Task 3: Update status, add, commit, branch, rev-parse flag tables</name>
  <files>README.md</files>
  <action>
**git status** - Expand existing table with STAT-01 to STAT-05:
- (existing rows preserved)
- --ignored: Yes, translates to `-i`
- -b/--branch: Yes, adds branch info header
- -v/--verbose: Note (sl -v has different meaning)
- -u/--untracked-files[=<mode>]: Yes, controls untracked display

**git add** - Expand existing table with ADD-01 to ADD-05:
- (existing rows preserved)
- --dry-run/-n: Yes, shows what would be added
- -f/--force: Warning (cannot add ignored files in Sapling)
- -v/--verbose: Yes, passes through

**git commit** - NEW expanded section with COMM-01 to COMM-08:
- -m <message>: Yes, passes through
- --amend: Yes, translates to `sl amend`
- --no-edit: Yes, omits `-e` flag (sl amend default)
- -F/--file: Yes, translates to `-l` (logfile)
- --author=: Yes, translates to `-u`
- --date=: Yes, translates to `-d`
- -v/--verbose: Warning (different semantics)
- -s/--signoff: Yes, adds Signed-off-by trailer
- -n/--no-verify: Warning (hook bypass not available)
- -a/--all: **Removed** (safety - sl -A adds untracked)

**git branch** - Expand existing table with BRAN-01 to BRAN-09:
- (existing rows preserved)
- -m <old> <new>: Yes, translates to `-m`
- -a/--all: Yes, shows all including remote
- -r/--remotes: Yes, shows remote only
- -v/--verbose: Yes, uses template for commit info
- -l/--list: Yes, filters output
- --show-current: Yes, shows current branch name
- -t/--track: Yes, passes through
- -f/--force: Yes, passes through
- -c/--copy: Yes, two-step (get hash + create)

**git rev-parse** - Major update from "Only --short HEAD" to REVP-01 to REVP-07:
- --short HEAD: Yes, `sl whereami`
- --show-toplevel: Yes, `sl root`
- --git-dir: Yes, returns `.sl` directory path
- --is-inside-work-tree: Yes, returns true/false
- --abbrev-ref HEAD: Yes, returns current bookmark
- --verify: Yes, validates object reference
- --symbolic: Yes, outputs in symbolic form

Ensure all tables use consistent format.
  </action>
  <verify>Grep README for "--show-toplevel" - should now exist in rev-parse section</verify>
  <done>Status has 5+ flags, add has 5+ flags, commit has 10 flags, branch has 12+ flags, rev-parse has 7 flags - all accurately documented</done>
</task>

</tasks>

<verification>
After all tasks complete:
1. `grep -c "Staging Area Limitations" README.md` returns 1
2. `grep "Not implemented" README.md` returns no results for --graph or --format
3. `grep "--show-toplevel" README.md` shows rev-parse documentation
4. README structure is clean with consistent table formatting
</verification>

<success_criteria>
1. Staging Area Limitations section exists with clear explanation
2. Common Flag Translations quick reference exists
3. git log section documents all 20 LOG flags accurately
4. git diff section is NEW with all 12 DIFF flags
5. git show section updated from generic to specific 8 flags
6. git status, add, commit, branch sections expanded with new flags
7. git rev-parse section updated from 1 flag to 7 flags
8. No "Not implemented" entries for flags that ARE implemented
</success_criteria>

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