git plugin: rtk git vs bare git is inconsistent across skills
#113
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Defame1297/holocron#113
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Surfaced during the #99 ADR-0020 retrofit, wave 2. Pre-existing — held out of that wave because it needs one normalising pass across the plugin, not nine independent per-skill judgment calls.
The inconsistency
CLAUDE.mdstates the golden rule: always prefix commands withrtk, including inside&&chains, because RTK either applies a token-reducing filter or passes through unchanged — so it is always safe.The plugin does not follow this uniformly:
git-commits/SKILL.mdmandatesrtk git <subcommand>and says "never baregit".git-historyuses baregitthroughout its body and references.git-submodulesusesrtk gitin the body's gates but baregitin reference code blocks.gitwhile bodies vary.Two auditors independently flagged it, one noting that bare
gitin reference blocks "matches the convention in every sibling git skill's references, so it is house-normal" — which is the problem: there are two house norms and no stated rule for which applies where.Why it is worth fixing
The cost is not correctness — both forms work. It is that an agent reading one skill learns a convention that the next skill contradicts, and neither states which is intended. That is the same class of defect as a stale cross-reference: cheap individually, corrosive in aggregate, and invisible to every gate.
What a fix needs to decide
rtkapply to illustrative commands inreferences/files, or only to commands the agent is instructed to execute? A reasonable split is: executable instructions getrtk, syntax illustrations do not — but it has to be written down.README.md, orAGENTS.mdif it generalises beyond the git plugin).Doing this per-skill as each is touched guarantees the inconsistency persists for months and gets re-litigated every time.
Scope
plugins/git/.apm/skills/— all nine:git-commits,git-branches,git-worktrees,git-remotes,git-workflow,git-submodules,git-history,pc-run,pc-author. Worth checking whether thegitea-*family has the same split before deciding where the rule lives.Related
#99 (the retrofit), #112 (the other pre-existing git-plugin item from the same wave).
Implementation note
Rule decided in session, empirically validated against
git-commitsbefore the corpus-wide pass (every existing baregitthere turned out illustrative, never an instructed step): executable instructed commands getrtk git; illustrative/referential mentions of a git command stay baregit. Documented in a newplugins/git/README.mdunder a "Conventions" section — confirmed it doesn't generalize beyond this plugin, sincegitea-*skills talk to the server over the MCP tools and contain zerogit/rtkmentions.Normalized all nine skills:
git-branches,git-history,git-remotes,git-worktrees,pc-run— real instructed-command gaps fixed (dispatch-table "Run" cells and fenced-code-block procedures counted as instructed, e.g.git-worktrees' whole dispatch table andgit-remotes' entire fetch/push/pull/remote-config catalogs were 0%rtkbefore this).pc-author— the pre-dispatch audit had this at 0/0 bare occurrences, but a full pass found 2 unflaggedgit ls-filescommands inside instructed steps (not backtick-quoted, so the earlier grep missed them). Fixed both.git-submodules,git-workflow— already essentially compliant; one deliberate exception left bare ingit-submodules: the inner command string passed togit submodule foreach '<command>'runs inside each submodule's own subshell, not as a top-level agent-invoked Bash command, sortk's wrapper has nothing to intercept there — the outerforeachinvocation itself isrtk git submodule foreach.No new pre-commit gate added for this (discussed and decided against) — the Claude Code
rtkhook already guarantees correctness for any command actually executed regardless of prose; this was purely a documentation-consistency gap, confirmed via Context7 against RTK's own docs that neither RTK nor any git hook in this repo checks skill-file prose at all."Never do X" anti-pattern warnings (e.g.
git-worktrees' detached-HEAD warning,pc-run's--no-verifywarning) were left bare as illustrative rather than rtk-prefixed, consistent with the rule — flagging in case that reads differently to a reviewer.