RCA-2026-05-18-001: Analysis

Root Cause

5 Whys Analysis

Why # Question and Answer

1

Why did Neovim error on launch?
Because: Auto-session tried to restore a session file containing an oil:// URI buffer. Vim’s :file command treats oil://…​ as a literal filename, hits a stale swap file, and prompts interactively — which fails in non-interactive session restore.

2

Why was an oil:// buffer in the session file?
Because: The bypass_session_save_file_types list only contained alpha, dashboard, and neo-tree. The oil filetype was not included, so auto-session serialized oil buffers into the session .vim file like any regular buffer.

3

Why was oil not in the bypass list?
Because: Oil.nvim was added to the config after auto-session was configured. The bypass list was written for the plugins that existed at setup time and never revisited when new special-buffer plugins were added.

4

Why was there no systematic process to update session exclusions when adding plugins?
Because: There is no checklist or verification step when adding buffer-type plugins (file explorers, terminals, sidebars) to domus-nvim. The interaction between session management and buffer-type plugins is implicit, not documented.

5

Why are plugin interactions not documented?
Because: The domus-nvim config lacks an architectural decision record or plugin interaction matrix. Each plugin spec is self-contained in tools.lua without cross-referencing plugins that share concerns (buffer lifecycle, session persistence, filetype registration).

Root Cause Statement

The oil filetype was absent from auto-session’s bypass_session_save_file_types, allowing oil.nvim’s oil:// URI buffers to be serialized into session files. These URI buffers cannot be restored by Vim’s native session mechanism, causing E325 and empty-buffer errors on every subsequent launch.

Contributing Factors

Factor Description Preventable?

Missing bypass entry

oil not in bypass_session_save_file_types — the direct cause

Yes

Stale swap files

Process killed without clean exit left .swp files that triggered E325 during restore

Partially — kill vs :qa is user behavior, but swap cleanup could be automated

No plugin interaction review

Adding oil.nvim never triggered a review of session management implications

Yes

Implicit filetype contracts

auto-session relies on knowing every non-file buffer type; oil.nvim doesn’t advertise that it creates non-restorable buffers

No — upstream design gap

Impact

Metric Value

Severity

P3 — Workflow disruption

Duration

Persistent until manual cleanup (errors on every launch)

Systems Affected

Neovim launch in domus-captures directory

Sessions Corrupted

1 (%2Fhome%2F…​%2Fdomus-captures.vim)

Swap Files Orphaned

5

Data Loss

None