Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skillz/windows-filename-guidance/SKILL.md

Raw
Rendered preview

name: windows-filename-guidance os: win32 description: "Use for Windows filename rules and failures involving reserved DOS device names such as NUL, invalid or trailing characters, inaccessible cross-platform names, long paths, or files that Windows cannot inspect, rename, or delete normally."

Windows Filename Guidance

Diagnose

  • Separate filesystem rules, Win32 namespace/normalization, and application API handling. An unusual name alone does not prove corruption or permission failure.
  • Obtain the exact absolute path, entry type, filesystem, and error. Enumerate the parent; never use Test-Path NUL or if exist NUL as file-existence evidence.
  • Classify reserved names, trailing characters, path length, open handles, ACLs, or independently evidenced corruption.
  • Consult current Microsoft naming rules through Devdocs rather than retaining character/device-name tables here.
  • Prefer the namespace or tool that created the entry when it can address it safely.

Namespace and shell boundaries

  • Exact absolute extended paths: local \\?\C:\absolute\path; UNC \\?\UNC\server\share\path. The prefix does not bypass filesystem rules, permissions, locks, or corruption. Never combine it with relative paths.
  • Git Bash/MSYS2 can rewrite arguments to native executables, including embedded shell text. Use the documented MSYS2_ARG_CONV_EXCL boundary; do not assume MSYS_NO_PATHCONV covers every executable.
  • Bash double quotes consume one leading backslash from \\. Preserve extended-path spelling with single quotes at that boundary; native cmd.exe quoting is not portable to Bash.
  • Consult MSYS2 path conversion for exact syntax before constructing a cross-shell command.

Removal and verification

  • Show the exact target and obtain explicit confirmation before deletion. Reject wildcards, relative paths, drive/share roots, and ambiguous targets.
  • Enumerate nonempty directories and obtain separate recursive-delete confirmation.
  • Choose an operation matching file/directory type and the exact namespace. Preserve spelling, extension, spaces, and periods. Explain forced read-only removal before using it.
  • If using an 8.3 alias, verify its mapping to the exact target first.
  • Enumerate the parent afterward; success requires the literal entry to be absent. Missing parent entry means stop, not further deletion attempts.
  • Git status is not direct filesystem verification. If it alone remains stale, bypass its filesystem monitor/untracked cache once:
git -c core.fsmonitor=false -c core.untrackedCache=false status --short
  • If that resolves the stale report and Git uses the built-in monitor, restart that monitor rather than deleting again.
  • Identify lock owners and permission boundaries before remediation. Do not elevate, change ownership, or repair a filesystem without independently supported need and authorization.

Sources

---
name: windows-filename-guidance
os: win32
description: "Use for Windows filename rules and failures involving reserved DOS device names such as NUL, invalid or trailing characters, inaccessible cross-platform names, long paths, or files that Windows cannot inspect, rename, or delete normally."
---

# Windows Filename Guidance

## Diagnose

- Separate filesystem rules, Win32 namespace/normalization, and application API handling.
  An unusual name alone does not prove corruption or permission failure.
- Obtain the exact absolute path, entry type, filesystem, and error.
  Enumerate the parent; never use `Test-Path NUL` or `if exist NUL` as file-existence evidence.
- Classify reserved names, trailing characters, path length, open handles, ACLs, or independently evidenced corruption.
- Consult current [Microsoft naming rules](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file) through Devdocs rather than retaining character/device-name tables here.
- Prefer the namespace or tool that created the entry when it can address it safely.

## Namespace and shell boundaries

- Exact absolute extended paths: local `\\?\C:\absolute\path`; UNC `\\?\UNC\server\share\path`.
  The prefix does not bypass filesystem rules, permissions, locks, or corruption.
  Never combine it with relative paths.
- Git Bash/MSYS2 can rewrite arguments to native executables, including embedded shell text.
  Use the documented `MSYS2_ARG_CONV_EXCL` boundary; do not assume `MSYS_NO_PATHCONV` covers every executable.
- Bash double quotes consume one leading backslash from `\\`.
  Preserve extended-path spelling with single quotes at that boundary; native cmd.exe quoting is not portable to Bash.
- Consult [MSYS2 path conversion](https://www.msys2.org/docs/filesystem-paths/) for exact syntax before constructing a cross-shell command.

## Removal and verification

- Show the exact target and obtain explicit confirmation before deletion.
  Reject wildcards, relative paths, drive/share roots, and ambiguous targets.
- Enumerate nonempty directories and obtain separate recursive-delete confirmation.
- Choose an operation matching file/directory type and the exact namespace.
  Preserve spelling, extension, spaces, and periods.
  Explain forced read-only removal before using it.
- If using an 8.3 alias, verify its mapping to the exact target first.
- Enumerate the parent afterward; success requires the literal entry to be absent.
  Missing parent entry means stop, not further deletion attempts.
- Git status is not direct filesystem verification.
  If it alone remains stale, bypass its filesystem monitor/untracked cache once:

```text
git -c core.fsmonitor=false -c core.untrackedCache=false status --short
```

- If that resolves the stale report and Git uses the built-in monitor, restart that monitor rather than deleting again.
- Identify lock owners and permission boundaries before remediation.
  Do not elevate, change ownership, or repair a filesystem without independently supported need and authorization.

## Sources

- [Microsoft undeletable NTFS entries](https://learn.microsoft.com/en-us/troubleshoot/windows-server/backup-and-storage/cannot-delete-file-folder-on-ntfs-file-system)
- [Bash quoting](https://www.gnu.org/software/bash/manual/html_node/Double-Quotes.html)
- [Git filesystem monitor](https://git-scm.com/docs/git-fsmonitor--daemon)