stash-shelve

name: "stash-shelve" description: "Use to temporarily shelve, inspect, apply, or recover local work without losing staged or unstaged changes." maturity-level: "L4" risk-scope: "R0-R5" version: "1.1.0"

Stash Shelve

Core Question

How should temporary work be safely shelved, restored, or inspected without losing user changes or staged boundaries?

When To Use

Use this skill when:

• the user asks to stash, shelve, apply stash, pop stash, list stash, or inspect stash
• dirty work blocks sync or branch switch
• temporary preservation is needed before another Git action
• the user asks to include or exclude untracked files from a stash

When Not To Use

Do not use this skill when:

• permanent undo/recovery after destructive action
• normal commit instead of temporary shelf
• conflict resolution after stash apply
• cleaning untracked files

Route to:

• destructive recovery routes to undo-recover
• stash apply conflicts route to resolve-conflicts
• commit instead of stash routes to atomic-commits
• branch sync after stash routes to sync-branch

Required Evidence

Before action, inspect or establish:

• status with staged/unstaged/untracked groups
• stash list and stash show evidence
• whether staged boundary must be preserved
• untracked inclusion request
• target stash reference
• conflict state after apply

No-evidence rule:

• Do not make strong claims without observed evidence.
• State assumptions when proceeding under incomplete evidence.
• Stop when missing evidence affects safety, correctness, user work, remote state, or irreversible action.

Operating Contract

You MAY:

• inspect relevant repository state and project files.
• generate a plan, report, or local artifact within the declared risk scope.
• route to another skill when the requested action is outside this skill's owner boundary.

You MUST:

• inspect before acting.
• keep the task within the declared owner boundary.
• classify state and risk before any meaningful action.
• preserve unrelated user work.
• verify outcomes proportional to risk.
• report evidence, assumptions, actions, verification, and residual risk.

You MUST NOT:

• invent project policy.
• expose secrets or sensitive values.
• mutate unrelated files or refs.
• perform destructive, remote, shared, history-rewriting, or irreversible actions without explicit action-specific confirmation.
• continue after unexpected destructive output.

State / Risk Table

Workflow

1. Identify the user goal and current owner boundary.
2. Inspect required evidence.
3. Classify repository/task state.
4. Classify risk using the declared scope.
5. Choose the minimal sufficient action or route.
6. Execute only allowed actions, if any.
7. Verify outcome or self-check the artifact.
8. Report result, evidence, verification, assumptions, and residual risk.

Decision Rules

• Prefer stash apply over pop when safety matters.
• Do not drop a stash until restored state is verified.
• Include untracked files only with explicit request.
• Preserve staged state when staged boundary matters.

Workflow Guardrails

Apply Does Not Drop

Trigger:

• The user asks to apply, pop, drop, or recover a stash entry.

Default:

• Use git stash apply stash@{n} semantics first; keep the stash entry until restored state is verified.

Must:

• Inspect git stash list, git stash show --stat stash@{n}, and current git status --short before apply/drop when a target stash is involved.
• Treat stash application and stash deletion as separate operations; apply-only never implies git stash drop.

Must not:

• Use git stash pop when the user only asked to apply or restore.
• Run git stash drop stash@{n} after apply-only requests.
• Drop a stash after apply until status is verified and the user separately confirms the drop.

Requires explicit confirmation:

• Exact stash ref for pop or drop.
• Whether the user wants apply plus deletion, or apply only.

Verification:

• Verify status after apply.
• Verify git stash list still contains the stash after apply-only, or no longer contains it after confirmed drop.

Tool Rules

• May inspect stash list and contents.
• May create named stashes when user intent is clear.
• Must not drop or pop stashes without exact confirmation.
• Must not clean untracked files.

Verification

Minimum verification:

• Verify stash list after create/drop.
• Verify status after apply.
• Report conflicts and route to resolve-conflicts.

Risk-based floor:

• R0-R1: evidence inspected and output self-checked.
• R2: inspect resulting diff or local state.
• R3: verify local state and report recovery limits.
• R4-R5: require explicit confirmation, preflight evidence, and post-action verification where this skill owns the action.

Output Contract

Final response must include:

## Result

- Decision, action, or artifact produced.

## Evidence

- Files, commands, diffs, refs, or assumptions used.

## Verification

- Checks performed and their result.

## Risks / Limitations

- Remaining uncertainty, blocked actions, or routed next steps.

Stop / Confirmation Rules

Stop when the repository state is dirty, conflicted, diverged, missing required evidence, or ambiguous in a way that could overwrite user work, invalidate the requested scope, or require a gated action.

Require explicit action-specific confirmation for:

• destructive local mutation.
• remote/shared mutation.
• history rewriting.
• security/secret/data impact.
• irreversible or hard-to-recover operation.

Broad approval such as "do whatever" is not enough for R4-R5 actions.

Lazy-load References

Load references/stash-safety.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.

Load references/staged-boundaries.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.

Load references/apply-vs-pop.md when:

• the task needs the detailed guidance described by the file name.
• the state/risk table identifies an ambiguous or high-risk path.