Classify the request.
- Search only: no content changes expected.
- Transform in stream: stdin/stdout pipeline usage.
- Transform files: in-place updates over globs.
Identify scope strategy.
- Regex scope only.
- Language scope only.
- Combined language + regex scope.
- Custom tree-sitter query scope.
Identify action strategy.
- Replacement (positional replacement argument after --).
- Composable actions (--upper, --lower, --titlecase, --normalize, --symbols, --german).
- Standalone actions (-d, -s).
Apply safety controls.
- Prefer --dry-run for file operations.
- Keep globs quoted.
- Add --fail-no-files when missing files should fail CI.
Choose output mode.
- Human-readable (default tty).
- Machine-readable (--stdout-detection force-pipe).
Validate behavior.
- Confirm expected match count.
- Confirm no out-of-scope edits.
- Re-run with stricter scope if needed.

Safety Protocol

Default to non-destructive behavior first.
- Prefer stdin-based or search-mode examples before in-place rewrites.
For file edits, require preview path.
- Use --dry-run first.
- Then run the same command without --dry-run only after confirmation.
Protect shell parsing boundaries.
- Quote regex.
- Quote globs: --glob '**/*.py'.
- Use -- before replacement values.
--glob accepts exactly one pattern (cannot repeat).
- Glob syntax: *, ?, [...], ** only. No {a,b} brace expansion.
- For multiple files: broader glob + --dry-run, or per-file via fd (CWD only—no [path] arg): fd -e <ext> --strip-cwd-prefix -x srgn --glob '{}' --stdin-detection force-unreadable [OPTIONS] [PATTERN]
Use the narrowest scope that solves the task.
- Prefer language scope + anchored regex over broad regex-only replacement.
Treat -d and -s as high-risk operations.
- Always provide explicit scope for them.

Command Construction Template

Use this template when building commands:

srgn [LANGUAGE_SCOPE_FLAGS...] [GLOBAL_FLAGS...] [ACTION_FLAGS...] [SCOPE_REGEX] -- [REPLACEMENT]

Build incrementally:

srgn --python 'imports' '^old_pkg' --glob '**/*.py' --dry-run -- 'new_pkg'

srgn --python 'function-calls' '^print$' --glob '**/*.py' --dry-run -- 'logging.info'

srgn --rust 'uses' '^good_company' --glob '**/*.rs' --dry-run -- 'better_company'

srgn --csharp 'comments' -d '.*'

srgn --rust 'unsafe'

srgn --python 'doc-strings' --fail-any 'param.+type'

srgn --python 'strings' --stdout-detection force-pipe '(foo|bar)'

srgn --typescript 'imports' '^legacy-lib' --glob 'src/**/*.ts' --sorted --dry-run -- 'modern-lib'

For broader, categorized examples, load references/cli-cookbook.md.

No matches when matches are expected.
- Verify language scope and prepared query name.
- Remove regex temporarily to test scope alone.
- Add --stdout-detection force-pipe to inspect exact matched columns.
Too many matches.
- Anchor regex (^...$) where possible.
- Narrow from generic language scope to a specific prepared query.
Wrong files targeted.
- Confirm --glob pattern and shell quoting.
- Add --fail-no-files in CI to catch empty globs.
--glob used multiple times.
- --glob is a single-value argument; cannot repeat.
- Broader glob + --dry-run, or per-file (CWD only—no [path] arg): fd -e <ext> --strip-cwd-prefix -x srgn --glob '{}' --stdin-detection force-unreadable [OPTIONS] [PATTERN]
Unclear behavior across multiple language scopes.
- Default is intersection (left-to-right narrowing).
- Use -j for OR behavior.
Special characters misinterpreted as regex.
- Use --literal-string when literal matching is intended.

Load reference files based on request type:

references/cli-cookbook.md
- Load for routine command construction and practical recipes.
references/language-scopes.md
- Load for prepared query selection by language.
references/advanced-patterns.md
- Load for custom queries, capture substitutions, join semantics, and CI failure modes.
references/deepwiki-recursive-notes.md
- Load for complete DeepWiki-derived background and architecture context.

Use this map to respond quickly:

"Rename imports safely"
- Use language import scope + anchored regex + --glob ... --dry-run.
"Update function calls only"
- Use language call-site scope (for example --python 'function-calls') + exact name regex.
"Only comments/docstrings"
- Use prepared comment/docstring scopes, add -j only when OR semantics are required.
"CI should fail if pattern appears"
- Use scoped search + --fail-any.
"CI should fail if required pattern is missing"
- Use scoped search + --fail-none.
"I need parseable output"
- Use --stdout-detection force-pipe.
"Regex escaping is painful"
- Use --literal-string and explicit replacement via --.

Before returning a final command, verify:

Scope is minimal and syntax-aware where possible.
Replacement argument is after -- (if replacement is used).
Globs are quoted.
--dry-run is present for file edits unless user requested direct apply.
Join semantics are explicit when multiple language scopes are used (-j vs default intersect).
Failure flags align with user intent (--fail-any, --fail-none, --fail-no-files).
Output mode is explicit if user needs machine parsing.