sh-snippet-vault-maintainer

name	sh-snippet-vault-maintainer
description	Use this skill when acting as the maintainer of the sh-snippet-vault repo and you need repo-specific standards for Rust architecture, TUI quality, SQLite boundaries, Nix workflow, and proactive cleanup.
metadata	{"skill_type":"workflow","framework":"rust","framework_version":"stable","scope":"repository","topics":["maintenance","refactoring","architecture","sqlite","tui"]}

sh-snippet-vault Maintainer

Use this skill when you are not just making a change, but maintaining the quality of the sh-snippet-vault repo as a long-lived Rust project.

Start by loading:

1. .github/skills/sh-snippet-vault-architecture/SKILL.md
2. this skill

The architecture skill is the factual map. This skill is the judgment layer for how to improve the repo well.

Core stance

Act like a strong repo owner:

• improve structure, naming, consistency, and maintainability proactively
• fix nearby architectural problems when leaving them untouched would make the result incomplete
• prefer meaningful cleanup over clever abstraction
• stay conservative around persistence, migrations, and user-visible TUI behavior

Maintainer checklist

1. Identify the correct boundary for the change:
   • flake.nix for environment and flake checks
   • crates/sh-snippet-vault/src/domain/ for business rules and validation
   • crates/sh-snippet-vault/src/storage/ for SQLite and repository access
   • crates/sh-snippet-vault/src/app/ for TUI flows and rendering
   • crates/sh-snippet-vault/src/cli/ for scripted workflows
2. Decide whether the request reveals a root-cause issue nearby.
3. Improve tightly related structure when it clearly increases correctness or maintainability.
4. Keep the result easy for the next maintainer or agent to understand.
5. Validate with the least risky path that matches the change.

What to improve proactively

Good candidates

• duplicated validation or query logic
• confusing state ownership between TUI and storage
• weak naming around snippets, tags, or shell metadata
• ad hoc keybinding handling that would be clearer as explicit actions
• docs or repo guidance that become inaccurate after structural changes
• migration or schema ownership that is spread across unrelated files

Usually not worth it

• speculative abstractions for backends not in use
• premature plugin systems
• broad file reshuffles without clear architectural payoff
• adding macros or generic layers that hide simple business logic

Repo-specific heuristics

• Keep the CLI and TUI thin by sharing core logic instead of duplicating behavior.
• Keep SQLite behind a disciplined storage boundary.
• Prefer explicit domain types over unstructured maps or loosely typed records.
• Treat migrations as intentional history, not incidental setup noise.
• Keep the app small enough that a new agent can regain context quickly.
• When the repo uses GitHub Issues, treat the issue as the source of truth for scope and acceptance criteria.
• Prefer one issue and one branch per task instead of bundling unrelated work together.

Dangerous areas

• schema migrations
• destructive snippet-edit flows
• import/export logic that could silently lose data
• TUI editing state that can corrupt unsaved user input
• broad dependency additions that add complexity without clear gain

In those areas, optimize for clarity, rollback safety, and explicit error handling.

Validation workflow

Use the least risky proof first:

nix develop
just fmt-check
just lint
just test

When repo wiring or packaging changes:

nix flake check

Patterns to prefer

• narrow edits with clear architectural intent
• typed domain models and explicit state transitions
• one storage boundary reused by all interfaces
• docs and skills that evolve with the repo
• behavior-focused tests around domain and storage invariants

Patterns to avoid

• letting TUI widgets own business rules
• scattering SQL across the app
• adding silent fallbacks that hide persistence or parsing failures
• keeping architecture only in your head instead of in repo-local guidance
• copying global skill text without rewriting it for this repo

References

• .github/skills/sh-snippet-vault-architecture/SKILL.md
• references/maintainer-checklist.md