Update Assessment

Update Assessment

Assess whether one repository app is worth updating, before any code change.

This skill implements docs/ai-sdlc/10-update-assessment-workflow.md.

Supporting files in this skill:

• checklist.md
• facts-to-collect.md
• prompt-fragments.md
• report-template.md

Inputs

• app name (required)
• candidate version (optional, detected when missing)

Steps

1. Run .venv/bin/libs scan --app <app> --json and use its output as the primary version fact source.
2. Run .venv/bin/libs app-drift --app <app> --json and use its output as the primary dependency and drift fact source.
3. Read repository facts only when scan or drift outputs are missing required facts.
4. Classify the candidate as patch, minor, major, or security.
5. Read upstream release notes, changelog, or upgrade guide.
6. Check whether the candidate fits the app's update policy and cadence.
7. Assess breaking risk for compose, env keys, volumes, init flow, login flow, and data path.
8. Perform a read-only repository conformance screening for the current app package against current quality gates and generation rules. Record only issues that materially affect update cost, safety, or readiness; do not expand into a full implementation review.
9. Assess the database dependency when .venv/bin/libs app-drift lists a DB engine image:
   • Read W9_DB_VERSION from apps/<app>/.env as the authoritative current DB version.
   • Read metadata/db-lifecycle.json; if the engine is missing or the snapshot is stale (older than 45 days), run .venv/bin/libs db-refresh first.
   • Read the vendor-tested minimum from official release notes or docs, not from externalDB.
   • Compute candidates: alive tracks with version >= vendor minimum; LTS/stable preferred over innovation/short-term.
   • Judge the vendor-tested upper bound from release notes or docs; untested majors are not eligible.
   • If the current W9_DB_VERSION is EOL'd or a better LTS candidate exists, report a DB finding with recommendation and reason. It does not block the main version decision.
10. Decide one result: auto-update, review-first, defer, or skip.

Output

A short assessment report:

• candidate version
• candidate class
• decision
• short rationale
• repository conformance finding (ok, minor-fixes, or blocking-fixes) with short scope note
• database finding (current, min, recommendation + reason, or no change)
• upstream references
• owner attention points

Rules

• Assessment only. Do not edit any files. Exception: .venv/bin/libs db-refresh may run to refresh the shared metadata/db-lifecycle.json fact snapshot.
• The conformance screening is read-only and scoped. Check for structural, policy, metadata, or generated-doc drift only when it could change the update decision, increase implementation scope, or block validation.
• Typical screening targets include required files, src/ mount alignment, JSON/YAML validity, env key policy, variables.json required fields, and README generation compatibility.
• DB findings use two machine fact sources: W9_DB_VERSION in .env is the current version, and db-lifecycle.json is the engine lifecycle source. Vendor minimums come from official docs. externalDB is user-facing help text only and must not be used for computation.
• Never pick a DB major above the vendor-tested upper bound; prefer LTS over innovation.
• An EOL'd current DB version is a P1 finding; report it even when the app itself needs no update.
• auto-update means an implementation issue may start now.
• review-first means stop after assessment and wait for owner approval.
• defer means record the candidate and check again in the next cadence.
• skip means no update work should start for this candidate.
• Prefer x.x image tags. Use x.x.x only when upstream has no usable x.x tag or exact patch pinning is required (see docs/devops-spec.md).
• Report in the same language the user used.
• Use report-template.md when the user asks for a formal assessment report, or when the adapter layer explicitly requests formal output.
• If .venv/bin/libs app-drift returns not-declared or source-error, AI may research missing upstream sources, but should not redo local dependency inventory already produced by CLI.