deprecation-triage

Deprecation triage

Table of Contents

• Overview
• When to use
• Inputs
• Workflow
• Issue template
• Resources

Overview

Apply the deprecation warning triage policy to prevent warning drift and ensure issues are tracked and resolved in-cycle or deferred explicitly.

When to use

The primary trigger is the detect-deprecation-warnings PostToolUse hook (hooks/scripts/detect-deprecation-warnings.sh). After any test command (pytest, cargo test, go test, etc.), the hook scans output for deprecation-warning patterns. When it finds one, it injects context telling the agent to invoke this skill after completing the current task.

The skill can also be invoked directly via /vergil-tooling:deprecation-triage when a deprecation warning surfaces outside the hook's scope (manual testing, log review, dependency changelog reading, etc.).

Inputs

Collect or request:

• Full warning text
• Location (file/module and call site)
• Environment (dev/test/prod)
• First seen date and version
• Whether the warning is user-visible

Workflow

1. Search for an existing issue that matches the warning text and location.
2. If an issue exists and the warning is mid-cycle, defer to the next dependency update.
3. If no issue exists, create one using the template below.
4. Attempt a code-only fix if no dependency upgrade is required.
5. If a dependency upgrade is required, defer to the start-of-cycle upgrade.
6. If user-visible and deferred, suppress and document the suppression.
7. Update the issue with each re-test and close when resolved.

Identity check (step 3). Creating issues requires write access. If the acting identity (USER / AUDIT) cannot create the issue, prepare the title and body and hand them to the human to create — do not fail silently.

Issue template

Title: Deprecation: <dependency or component> - <short description>

Warning text:
<full warning message>

Location:
- file/module:
- call site:
- environment (dev/test/prod):

Reproduction:
- minimal command or steps:
- notes on reproducibility:

First seen:
- date:
- version:

Impact assessment:
- user-visible: yes/no
- behavior risk:

Attempted fixes:
- code changes tried:
- result:

Upgrade assessment:
- required dependency version:
- upgrade scope:

Decision:
- fix now / defer to next cycle
- rationale:

Suppression (if any):
- suppression method:
- removal criteria:

Resources

• docs/development/deprecation-warnings.md