Arch Linux triage
Diagnose an Arch Linux problem report, transform update and constraint details into a rolling-release-safe triage plan, and return copy-paste-ready remediation, validation, and rollback commands.
When to invoke
- "Triage this Arch Linux failure."
- "Fix a pacman or broken upgrade problem."
- "Debug an Arch service after a recent update."
- "Why did my Arch kernel update break boot or drivers?"
- "Give me Arch remediation commands with rollback."
Request facts to capture
Preserve these original inputs when they are supplied by the caller: ${input:ArchSnapshot}, ${input:ProblemSummary}, and ${input:Constraints}. If any are absent, collect equivalent evidence with read-only commands.
| Fact |
How to collect |
Why it matters |
| Recent update set |
`grep -E "[ALPM] (upgraded |
installed |
| Kernel/runtime match |
uname -r; pacman -Q linux linux-lts 2>/dev/null; bootctl status when systemd-boot is used |
Drivers fail when the running kernel and installed modules do not match. |
| Package health |
pacman -Qk; pacman -Dk; pacman -Qu |
Finds missing files, dependency issues, and pending upgrades. |
| Failing unit |
systemctl status <unit> --no-pager; journalctl -u <unit> -b --no-pager |
Identifies service, dependency, and configuration failures. |
| Constraints |
no reboot, no full upgrade, metered network, production host |
Determines whether a full pacman -Syu, reboot, or package cache rollback is acceptable. |
A step-by-step triage plan should still stay small enough to validate after each major command.
Triage command map
| Symptom |
First commands |
Evidence to read |
| Service failed |
systemctl status <unit> --no-pager; journalctl -u <unit> -b --no-pager |
Exit status, missing library, config parse error, dependency failure. |
| Broken upgrade |
pacman -Syu; pacman -Qkk <package>; pacman -Dk |
Partial upgrade, interrupted transaction, missing files, dependency drift. |
| Boot regression |
journalctl -b -1 -p warning --no-pager; ls /boot; mkinitcpio -P after config review |
initramfs, bootloader entry, kernel/module mismatch. |
| Network/DNS |
ip link; ip addr; ip route; resolvectl status; networkctl status |
Interface down, route missing, resolver issue, NetworkManager/systemd-networkd mismatch. |
| Pacman lock |
fuser /var/lib/pacman/db.lck; inspect running pacman processes |
Active transaction versus stale lock. |
| AUR-related issue |
Identify AUR packages with pacman -Qm |
AUR rebuilds may be needed after library soname updates. |
Remediation patterns
| Problem |
Preferred fix |
Avoid |
| Partial upgrade |
Bring the system forward with pacman -Syu from a healthy mirror. |
Installing one package with pacman -Sy <pkg> without full upgrade. |
| Broken package files |
Reinstall the package: pacman -S <package> after confirming the database is healthy. |
Manually copying files into /usr. |
| Kernel module mismatch |
Reboot into the installed kernel, or install matching kernel/modules and regenerate initramfs with mkinitcpio -P. |
Loading modules built for a different kernel. |
| Mirror failure |
Refresh mirror list with a trusted method, then pacman -Syyu only when mirror metadata is suspect. |
Repeated -Syy as routine maintenance. |
| Stale lock |
Remove /var/lib/pacman/db.lck only after confirming no pacman process owns it. |
Deleting the lock while pacman is running. |
| AUR rebuild needed |
Rebuild affected foreign packages after core library upgrades. |
Treating AUR packages as officially supported pacman packages. |
Rolling-release safety rules
- Treat partial upgrades as unsupported; prefer a coherent full-system update when package state is involved.
- Read Arch News before major manual interventions when core packages, kernels, Python, OpenSSL, or filesystem layout changed recently.
- Keep rollback grounded in the package cache under
/var/cache/pacman/pkg/ or a known snapshot from the user's environment.
- Include reboot guidance whenever kernel, initramfs, graphics driver, systemd, glibc, or low-level libraries changed.
Output template
## Arch Linux triage result
**Status:** diagnosed | remediated | blocked
**Snapshot/update context:** `<ArchSnapshot or collected evidence>`
**Problem:** `<ProblemSummary>`
**Constraints:** `<Constraints or none stated>`
### Summary
<one-paragraph diagnosis and risk statement>
### Triage Steps
1. `<read-only command>` — <evidence expected>
2. `<read-only command>` — <evidence expected>
### Remediation Commands
```bash
# precheck
<command>
# change
<command>
```
### Validation
```bash
<command proving the fix>
```
### Rollback/Cleanup
- **Rollback/Cleanup**
```bash
<command to undo, downgrade, reboot, or clean up>
```
Quality gate
1---2name: arch-linux-triage-23description: Diagnose and remediate Arch Linux incidents with pacman, systemd, journal analysis, rolling-release upgrade discipline, kernel awareness, and rollback practices. Use when the user asks to triage Arch service failures, package conflicts, broken upgrades, boot issues, or post-update regressions.4---56# Arch Linux triage78Diagnose an Arch Linux problem report, transform update and constraint details into a rolling-release-safe triage plan, and return copy-paste-ready remediation, validation, and rollback commands.910## When to invoke1112- "Triage this Arch Linux failure."13- "Fix a pacman or broken upgrade problem."14- "Debug an Arch service after a recent update."15- "Why did my Arch kernel update break boot or drivers?"16- "Give me Arch remediation commands with rollback."1718## Request facts to capture1920Preserve these original inputs when they are supplied by the caller: `${input:ArchSnapshot}`, `${input:ProblemSummary}`, and `${input:Constraints}`. If any are absent, collect equivalent evidence with read-only commands.2122| Fact | How to collect | Why it matters |23| --- | --- | --- |24| Recent update set | `grep -E "\[ALPM\] (upgraded|installed|removed)" /var/log/pacman.log | tail -50` | Arch failures often follow a partial or recent upgrade. |25| Kernel/runtime match | `uname -r`; `pacman -Q linux linux-lts 2>/dev/null`; `bootctl status` when systemd-boot is used | Drivers fail when the running kernel and installed modules do not match. |26| Package health | `pacman -Qk`; `pacman -Dk`; `pacman -Qu` | Finds missing files, dependency issues, and pending upgrades. |27| Failing unit | `systemctl status <unit> --no-pager`; `journalctl -u <unit> -b --no-pager` | Identifies service, dependency, and configuration failures. |28| Constraints | no reboot, no full upgrade, metered network, production host | Determines whether a full `pacman -Syu`, reboot, or package cache rollback is acceptable. |2930A step-by-step triage plan should still stay small enough to validate after each major command.3132## Triage command map3334| Symptom | First commands | Evidence to read |35| --- | --- | --- |36| Service failed | `systemctl status <unit> --no-pager`; `journalctl -u <unit> -b --no-pager` | Exit status, missing library, config parse error, dependency failure. |37| Broken upgrade | `pacman -Syu`; `pacman -Qkk <package>`; `pacman -Dk` | Partial upgrade, interrupted transaction, missing files, dependency drift. |38| Boot regression | `journalctl -b -1 -p warning --no-pager`; `ls /boot`; `mkinitcpio -P` after config review | initramfs, bootloader entry, kernel/module mismatch. |39| Network/DNS | `ip link`; `ip addr`; `ip route`; `resolvectl status`; `networkctl status` | Interface down, route missing, resolver issue, NetworkManager/systemd-networkd mismatch. |40| Pacman lock | `fuser /var/lib/pacman/db.lck`; inspect running pacman processes | Active transaction versus stale lock. |41| AUR-related issue | Identify AUR packages with `pacman -Qm` | AUR rebuilds may be needed after library soname updates. |4243## Remediation patterns4445| Problem | Preferred fix | Avoid |46| --- | --- | --- |47| Partial upgrade | Bring the system forward with `pacman -Syu` from a healthy mirror. | Installing one package with `pacman -Sy <pkg>` without full upgrade. |48| Broken package files | Reinstall the package: `pacman -S <package>` after confirming the database is healthy. | Manually copying files into `/usr`. |49| Kernel module mismatch | Reboot into the installed kernel, or install matching kernel/modules and regenerate initramfs with `mkinitcpio -P`. | Loading modules built for a different kernel. |50| Mirror failure | Refresh mirror list with a trusted method, then `pacman -Syyu` only when mirror metadata is suspect. | Repeated `-Syy` as routine maintenance. |51| Stale lock | Remove `/var/lib/pacman/db.lck` only after confirming no pacman process owns it. | Deleting the lock while pacman is running. |52| AUR rebuild needed | Rebuild affected foreign packages after core library upgrades. | Treating AUR packages as officially supported pacman packages. |5354## Rolling-release safety rules5556- Treat partial upgrades as unsupported; prefer a coherent full-system update when package state is involved.57- Read Arch News before major manual interventions when core packages, kernels, Python, OpenSSL, or filesystem layout changed recently.58- Keep rollback grounded in the package cache under `/var/cache/pacman/pkg/` or a known snapshot from the user's environment.59- Include reboot guidance whenever kernel, initramfs, graphics driver, systemd, glibc, or low-level libraries changed.6061## Output template6263````markdown64## Arch Linux triage result6566**Status:** diagnosed | remediated | blocked67**Snapshot/update context:** `<ArchSnapshot or collected evidence>`68**Problem:** `<ProblemSummary>`69**Constraints:** `<Constraints or none stated>`7071### Summary72<one-paragraph diagnosis and risk statement>7374### Triage Steps751. `<read-only command>` — <evidence expected>762. `<read-only command>` — <evidence expected>7778### Remediation Commands79```bash80# precheck81<command>82# change83<command>84```8586### Validation87```bash88<command proving the fix>89```9091### Rollback/Cleanup92- **Rollback/Cleanup**93```bash94<command to undo, downgrade, reboot, or clean up>95```96````9798## Quality gate99100- [ ] `${input:ArchSnapshot}`, `${input:ProblemSummary}`, and `${input:Constraints}` were used or marked unknown.101- [ ] Recent updates and environment assumptions were checked before remediation.102- [ ] Triage used `systemctl`, `journalctl`, and `pacman` where applicable.103- [ ] Kernel update, initramfs, module, or reboot considerations were addressed when relevant.104- [ ] Every major change includes validation and rollback or cleanup commands.105- [ ] No partial-upgrade remediation was recommended without calling out the risk.