GTST-17 feat: add Claude Code skill for gitsift selective staging

[MonteYin]

Summary

Add a Claude Code skill that teaches agents how to use gitsift for selective staging.

Users can copy skills/gitsift-staging/ into their .claude/skills/ to enable it.

What the skill covers

• Core workflow: diff → decide → stage → verify → commit
• Hunk-level staging with --hunk-ids
• Line-level staging with --from-stdin and line_selections
• JSON response format parsing
• Example: splitting a feature and bugfix into separate commits

Gotchas (from real testing)

• Untracked files break ALL staging — must git add new files first (GTST-18)
• Changes within 3 lines merge into one hunk — use line-level staging
• Hunk IDs change after every stage — always re-diff
• Cannot mix hunk_ids and line_selections in one request

Tested scenarios

• Large file with multiple scattered hunks
• Untracked files workaround (detect → git add → stage)
• Hunk-level staging (single hunk)
• Re-diff verifies hunk ID changes
• Line-level staging (select only bugfix lines, leave refactor)

[MonteYin]

Review -- Opus 4.6

Review Result

Overall Verdict: HAS_ISSUES

---

1. Correctness

Verdict: HAS_ISSUES

Issues

Important

• SKILL.md:47-54 -- JSON example shows incorrect content field values. The example shows content with unified-diff prefix characters: " unchanged\n" (leading space for equal), "old line\n", "new line\n". Verified against a live run of gitsift diff --format json: the actual content field contains raw text WITHOUT prefix characters. For example, an equal line with text "line 1" produces {"tag":"equal","content":"line 1\n",...}, not {"tag":"equal","content":" line 1\n",...}. An agent parsing the diff output and comparing against this example will have a mismatch.

  Evidence from live test:

  {"tag":"equal","content":"line 1\n","old_lineno":1,"new_lineno":1}
  {"tag":"delete","content":"line 2\n","old_lineno":2}
  {"tag":"insert","content":"changed line 2\n","new_lineno":2}

• SKILL.md:42-56 -- JSON example omits 5 fields from the Hunk object. The actual Hunk struct (defined in src/models.rs:24-33) serializes with fields: id, file_path, old_start, old_lines, new_start, new_lines, header, lines. The example only shows id, header, and lines, omitting file_path, old_start, old_lines, new_start, new_lines. Since this is the canonical JSON reference an agent will use to understand the response format, missing fields will cause confusion or missed data extraction opportunities. At minimum, the example should include all fields or have a comment indicating it is truncated.

Minor

• SKILL.md:49 -- old_lineno/new_lineno shown as bare integers, but actual serialization omits them when null. The example shows {"tag": "delete", "content": "old line\n", "old_lineno": 2} with new_lineno absent. This is actually correct (due to skip_serializing_if = "Option::is_none" in src/models.rs:8-11), but it is worth noting for completeness that this behavior is accurate.

Fix Instructions

1. Fix the content values in the JSON example (lines 49-51):

   • Change " unchanged\n" to "unchanged\n" (or better, use a realistic value like "line 1\n")
   • Change "old line\n" to "old line\n" (this one happens to be correct without a prefix already, but the equal line has the spurious space)

2. Add the missing hunk fields to the example:

   "hunks": [{
     "id": "59a9050fd4195c94",
     "file_path": "src/lib.rs",
     "old_start": 1,
     "old_lines": 5,
     "new_start": 1,
     "new_lines": 7,
     "header": "@@ -1,5 +1,7 @@",
     "lines": [...]
   }]

---

2. Architecture

Verdict: HAS_ISSUES

Issues

Important

• SKILL.md -- Missing coverage of the protocol subcommand. The skill documents diff, stage, and status but never mentions gitsift protocol -- the persistent JSON-lines mode over stdin/stdout (defined in src/cli.rs:41 and implemented in src/protocol.rs). For a long-running agent session, protocol mode avoids repeated process spawning overhead and is the recommended integration pattern per CLAUDE.md. The PR description claims the skill covers "all gitsift features" but this omission contradicts that.

Minor

• SKILL.md:13 -- Installation check could mention gitsift --help as fallback. The --version flag works but --help provides more diagnostic value if something is misconfigured (e.g., it shows subcommands).

• No mention of the --repo global flag. The CLI supports --repo <path> (defined in src/cli.rs:13) for operating on a repository at a different path. This is useful when an agent's working directory differs from the repo root. Not critical since most agents run from the repo root, but worth a one-liner.

Fix Instructions

Add a section after "Stage by line" or in the "Response Format" area covering protocol mode:

## Protocol Mode (Long-Running Sessions)

For persistent agent sessions, use protocol mode to avoid process spawn overhead:
```bash
gitsift protocol

Send JSON-lines requests on stdin, receive JSON-lines responses on stdout:

{"method": "diff", "params": {"file": "src/main.rs"}}
{"method": "stage", "params": {"hunk_ids": ["abc123"]}}
{"method": "status"}

Each response uses the same envelope format. All logs go to stderr only.

---

### 3. Security
**Verdict**: PASS

No security concerns. This is a documentation-only PR that adds a skill file. No code changes, no secrets, no user input handling.

---

### 4. Performance
**Verdict**: PASS

Not applicable to a documentation file. No runtime code changes.

---

### 5. Simplicity
**Verdict**: PASS

#### Observations

The skill document is well-structured with progressive disclosure: core workflow first, then gotchas, then examples, then response format. The description trigger phrases are comprehensive and natural. The untracked files workaround pattern (detect, git add, then stage) is clear and actionable with concrete commands.

Line count (163 lines) is reasonable for the scope -- not padded, not too terse. The example workflow at the end effectively demonstrates the diff-stage-commit-rediff cycle.

One minor style note: the untracked files workaround uses a `python3 -c` one-liner to parse JSON. An agent would more naturally parse the JSON itself rather than shelling out to Python. Consider showing the detection as a conceptual step ("check the diff output for files with `status: added`") rather than a specific command, since the agent can read JSON natively.

---

### Summary

This is a well-written skill document that covers the core gitsift workflow accurately and with good progressive disclosure. However, two important correctness issues need fixing before merging: (1) the JSON example shows content values with spurious unified-diff prefix characters that don't match actual output, and (2) the hunk object example omits 5 of 8 fields. Both issues will mislead agents parsing real gitsift output. Additionally, the `protocol` subcommand -- gitsift's persistent JSON-lines mode -- is entirely absent from the skill, leaving a gap in feature coverage. The gotchas section is strong and clearly drawn from real testing, particularly the untracked files issue (cross-referenced as GTST-18). Fix the JSON example accuracy and add protocol mode coverage, and this is ready to merge.