T-Y7IN-document-grep-alias-bypass

Status: closed/done · Impact: low · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to ready before picking up.

Goal

/sdlc:task-work and several other SDLC skills shell out to grep with BSD-flag arguments (e.g. grep -l -E). On some user shells this hits an alias that rewrites grep to rg --no-heading --with-filename, which then fails on the BSD flags. Documenting the “use /usr/bin/grep (or command grep)” pattern in the skills that invoke grep keeps a single-line workaround at the source of truth instead of relitigating it during every run.

Today

From the post-mortem:

“Bash invocations of grep were intercepted by a shell alias (looks like rg with --no-heading --with-filename rewrites) that fails on BSD-flag arguments — used /usr/bin/grep to bypass. Cosmetic, but it broke a verification step until noticed.”

A grep of plugin/skills/**/SKILL.md shows several skills invoke grep bare in their procedural prose; none currently caveat the alias issue.

Proposed

In any SDLC skill that includes grep in a Bash example, switch the example to command grep (POSIX-portable: bypasses aliases and functions but uses the shell’s PATH) or /usr/bin/grep (absolute, ignores PATH-overrides) and add a one-line note explaining why.

Optionally: add the same note to a shared “Bash conventions” snippet that skills can reference, so it stays consistent.

Approach

1. grep -nE '\bgrep:space:' plugin/skills/**/SKILL.md (run with /usr/bin/grep to avoid the very issue) to enumerate hits.
2. For each hit, replace grep → command grep and add a footnote / parenthetical on first use per file: “command grep rather than bare grep because some shells alias grep to rg rewrites that fail on BSD flags.”
3. Spot-check /project-check still passes.

Files to touch

• plugin/skills/**/SKILL.md — wherever grep is invoked. Likely candidates: task-work, project-cleanup, entities-audit, entities-migrate, import-planning.

Acceptance criteria

• AC-1: No SDLC SKILL.md procedural example invokes bare grep; all use command grep or /usr/bin/grep.
• AC-2: Each modified SKILL.md includes a one-line rationale on first use of the bypass.
• AC-3: /project-check still passes.

Dependencies

• none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-DHGL-build-import-planning-skill on 2026-05-19.

Post-mortem

What went sideways or what could automation have caught:

• Three of the six grep hits in SKILL.md files (git grep and git log --grep) are git’s own flag/subcommand, not the shell grep command — so they aren’t subject to the alias issue. Distinguishing “bash grep invocation” from “git’s --grep flag” required reading each hit in context. A simple \bgrep:space:“ regex doesn’t separate them; a more selective enumeration (e.g. excluding lines containing git before the grep token, or requiring the token to start a pipeline) would have shortened the triage.
• One hit (task-work:213 post-mortem prose: “a pre-implementation grep for similar helpers”) is a noun-form remediation suggestion, not a command to run. Left as-is — converting would read awkwardly and the prose doesn’t direct a specific shell invocation.
• /project-check’s check_entities.py failed in the worktree with ModuleNotFoundError: No module named 'yaml'. Same failure on main — pre-existing environmental gap, not caused by this change. The newer check_skill_prose.py ran cleanly and reported no violations. Worktree init should either pin a python with PyYAML available or vendor the YAML reader for the entity checker.

Out of scope

• none

---

← Back to Tasks