Merge pull request #2044 from fullsend-ai/agent/1727-broaden-stale-ref-grep

feat(#1727): add bare-word grep pattern guidance for rename PRs

Author: ralphbean

internal/scaffold/fullsend-repo/skills/code-review/SKILL.md

@@ -184,6 +184,12 @@ readability or correctness.
 - Do documentation files reference behavior, APIs, or configurations
   changed by this PR?
 - Are any docs now stale as a result of the change?
+- **Rename/deprecation completeness:** When a PR renames or removes an
+  identifier, grep for stale references using a bare-word pattern
+  (`\bOLD_NAME\b`) in addition to any syntax-specific pattern (e.g.,
+  `OLD_NAME:` for YAML). Documentation files (`.md`, `.adoc`, `.rst`)
+  often reference field names in prose without syntax suffixes and will
+  be missed by syntax-specific patterns alone.
 
 #### Cross-repo contracts
 

internal/scaffold/fullsend-repo/skills/docs-review/SKILL.md

@@ -94,6 +94,15 @@ and exit — there is nothing to check.
 
 Write a shell script that takes the identifiers from step 2 and
 greps for each one across the documentation files from step 3.
+
+**Rename/deprecation PRs:** When a PR renames or removes an identifier,
+use a bare-word pattern (`\bOLD_NAME\b`) in addition to any
+syntax-specific pattern (e.g., `OLD_NAME:` for YAML). Documentation
+files often reference field names in prose without syntax suffixes and
+will be missed by syntax-specific patterns alone. See the
+`docs-currency` sub-agent's "Rename/deprecation pattern strategy"
+section for the full approach.
+
 Run the script in a single Bash call:
 
 ```bash

internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/docs-currency.md

@@ -18,3 +18,21 @@ references to renamed/removed identifiers.
 Extract identifiers from the diff, then search documentation files for
 references. Flag docs that reference identifiers modified or removed in
 this PR.
+
+## Rename/deprecation pattern strategy
+
+When a PR renames or removes an identifier (config key, CLI flag, API
+field, function name, etc.), search for stale references using **both**
+broad and syntax-specific grep patterns:
+
+1. **Bare-word pattern** (`\bOLD_NAME\b`) — catches all mentions
+   including prose, comments, backtick-wrapped references, and code.
+   Run this first and evaluate hits in context.
+2. **Syntax-specific pattern** (e.g., `OLD_NAME:` for YAML keys,
+   `--OLD_NAME` for CLI flags) — catches structured usage in config
+   and code files.
+
+Documentation files (`.md`, `.adoc`, `.rst`) frequently reference field
+names in prose without syntax-specific suffixes (e.g., "set the
+`repository` field"). Always include the bare-word pattern when scanning
+these file types — a syntax-specific pattern alone will miss them.