# Update Vi > VI-update workflow (PM phase) — refresh/re-do an existing Value Increment. Resolves the VI Jira-import-first (source of truth) with a 3-day freshness gate, grounds on the VI + comments + any ARD/spec/transcript, updates it via a relentless grill against _shared/vi-format.md, gated by the Opus vi-reviewer, and writes canonical + archived revisions to $SPECS_PATH/specifications/-/. Product-level (no code scan). Activated when the user prompt starts with "update-vi:". - Skill: `ihudak/update-vi` (Agent Skill) - Install (CLI): `npx skillmds@latest add ihudak/update-vi` - Raw SKILL.md: https://api.skillmd.com/api/skills/ihudak/update-vi/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ihudak (https://skillmd.com/u/ihudak) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ihudak/update-vi --- Update the Value Increment for the Jira item: the argument (text following the `update-vi:` trigger) `update-vi:` refreshes an **existing** Value Increment (PM phase). It covers routine refreshes (new information, scope tweaks, wording) and the rare obstacle-driven re-do (a human read an ARD/spec finding, discussed it in Jira, and decided the VI must change). The VI is **product-level** — what / why / for-whom, not how. Zero code scan; no repos. Usage: `update-vi: [@transcript-or-notes ...] [--no-docs]` (`--no-docs` turns off documentation grounding for the run — see Phase 1). --- ## Phase 0 — Resolve inputs 1. **`KEY` (mandatory).** Parse the first non-flag token; validate `^[A-Z][A-Z0-9_]*-\d+$`. If absent or malformed, stop: `UPDATE_VI_NEEDS_KEY: update-vi: needs the VI's Jira key — 'update-vi: '.` 2. **`$SPECS_PATH` (required).** If unset, stop naming `SPECS_PATH` (`choices: ["Set SPECS_PATH (enter the path)", "Cancel"]`). 3. **Feature folder.** `/specifications/-/` — honor an existing dir matched by key-number (tolerate a stray `-`/`_` and a human-adjusted slug). 4. **Resolve the base VI — Jira-import-first.** Execute `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/vi-source-resolution.md` (`resolve-existing-vi `): the re-imported `$VAULT_PATH/jira-products/` VI (body + `-comments.md`) is the **authoritative base**; not imported → stop and ask to import; stale (>3 days) → offer re-import. 5. **Secondary grounding (read-only).** Discover in the feature folder: the frozen specs draft (glob `_*.md`, `issue_type: ValueIncrement`), any `*_ARD.md`, `specification.md`; plus any `@transcript` / notes path(s) passed in the argument. These reads are deliberately **not** gated: `require-on-main` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §3) is never executed by this command. `update-vi:`'s authoritative base is the Jira import, and Phase 2 already rules that the import wins where a frozen draft disagrees. Gating advisory grounding would block a legitimate VI refresh because an unrelated ARD sits on a branch. Where a discovered `*_ARD.md` or `specification.md` is **not** on the specs repo's default branch, say so in the Phase 1 confirmation — the user should know the grounding is unapproved, not be stopped by it. `update-vi:` is **cwd-agnostic** and needs **no repos mounted** (product-level; no code scan). **Specs-repo preflight.** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` and execute its `specs-preflight` entry point (§3) inline: flush any leftover session artifacts from an earlier run, retry an artifact commit that failed to push, and settle the branch. Prompt-free and silent when the specs repo is clean and on its default branch. If a guard fires, emit its §5 notice; if it returns `specs_git: blocked` (§3.3 G0), carry that flag for the whole run — the terminal `commit-artifacts` step skips on it. --- ## Phase 1 — Configure Use `choices` arrays; the last choice is always `"Other… (describe)"`. 1. **Confirm** the feature folder; the resolved Jira-import base **with its import date**; and the secondary artifacts discovered (specs draft / ARD / spec / transcript). - Show the `docs grounding:` line in the form `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/docs-grounding.md` resolved — `ON (retrieval: …)` or `OFF ()` — verbatim, including any index-build, staleness, or shadowing clause it carries (off switch: --no-docs). - Report any discovered `*_ARD.md` or `specification.md` that is not on the specs repo's default branch — per Phase 0 step 5, this grounding is unapproved but advisory-only; it is never a reason to stop the run. 2. **Scope of the update.** `choices: ["Refresh (incorporate new info / comments / transcript) (Recommended)", "Re-do (substantive re-scope driven by an ARD/spec obstacle)", "Cancel", "Other… (describe)"]`. --- ## Phase 1.5 — Classify + model routing Load and follow the model-routing policy at `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/model-routing.md`, then record: ```yaml model_routing: classification: MODERATE # typical; SIGNIFICANT for large/cross-cutting VIs reason: current_model: detection_model: <§2.1 detection chain: claude-sonnet-4.6, fallback claude-sonnet-4.5/gpt-5.4> # impl-maintenance review_model: <§2 Opus chain> # vi-reviewer (caller-pinned via `task(model:)`; recorded) authoring_model: <= current_model> # the interactive grill + VI authoring (session model, not a delegated subagent) opus_available: notes: ``` The grill + authoring run inline on `current_model` (the §2 Opus chain — interactive judgment, not a delegated subagent). If no Opus resolves, **degrade to best-available + record** in `notes` and the final report — do not hard-block. --- ## Phase 2 — Read the base + grounding Read the Jira-import VI **body + `-comments.md`** (the authoritative base and the signal for *what to change*), then the secondary artifacts (specs draft, ARD, spec, transcript). Do NOT treat the frozen specs draft as authoritative where it disagrees with the Jira import — the import wins; surface a notable divergence to the user. **No code scan; no repos.** Then run `resolve-docs-grounding update-vi` per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/docs-grounding.md`. When `docs_grounding: ON`, `dispatch-docs-grounder` with `feature_summary` = the VI goal + the change signal from comments, `jira_key` = ``. Carry the digest into the Phase 3 grill with **grill-rank** consumption. When OFF, skip silently. --- ## Phase 3 — Update via grill **Interview technique (grilling — embedded; no runtime dependency).** Conduct a **relentless** interview per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/grilling-technique.md` — **rounds** rhythm (per that file's `## Rhythm`): ask the whole settled frontier as one numbered round, recompute from the answers, repeat to an empty frontier. Recommend each answer, fact-vs-decision split, walk the design tree in dependency order, and clear the confirmation gate before writing. Update the VI live against `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/vi-format.md`, applying the no-hard-wrap prose convention in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/prose-formatting.md`, **diffing against the base** rather than authoring from blank: surface what changed and why (drawing on comments / ARD / spec / transcript), resolve open questions, keep the VI product-level. Apply the **self-consistency check** — no `[AC#N]` delivering an Out-of-scope behaviour, no `## Goal` vs `## Scope` contradiction, no conflicting `[US#N]`; record a deliberately-kept tension under `## Assumptions & open questions`. Preserve the frontmatter provenance fields (`sources`, `derived_from`, `seeded_from_vi` if present). --- ## Phase 3.5 — Dynatrace style check Run the corporate style check on the updated VI **before** the review gate — a **quality enhancement, not a gate**; it never blocks the handoff (mirrors `create-vi:` Phase 3.5). → task(agent_type: "dt-style-guide:dt-style-checker", model: ): > "Run the style check for this brief: > > files: [absolute path to the updated _.md] > doc_type: vi > emphasis: terminology and customer-facing captions, labels, messages, and text" Act on the return: `OK` → proceed; `VIOLATIONS_FOUND` → apply the MAJOR fixes inline and re-run `dt-style-checker` once (record remaining MINOR/NIT); `ERROR` → surface and proceed (non-gating). If `dt-style-checker` is unavailable (the `dt-style-guide` plugin is not installed), **skip gracefully** and note `SKIPPED (dt-style-checker unavailable)`. --- ## Phase 3.6 — Structural pre-lint Before the review gate, run the deterministic checks in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/pre-lint.md` against the updated file: the **Universal checks**, the **Jira-key collision** check (run on the body below the frontmatter), and the **VI** block. Surface every finding; inline-fix the mechanical ones; leave content gaps for the grill. **Advisory** — never blocks; `vi-reviewer` remains the gate. --- ## Phase 4 — Review gate Dispatch `vi-reviewer` (Opus, caller-pinned via `task(model:)`; recorded as `review_model`): → task(agent_type: "dev-workflows:vi-reviewer", model: ): > "Review the Value Increment: > > VI path: [absolute path to the updated _.md] > Profile: [lean | hybrid | full — infer from the sections present]" Act on the verdict as `create-vi:` Phase 4 does: on `BLOCK`, fix the BLOCKER findings inline (the orchestrator/grill edits the VI — no delegated writer) and re-review **once**. If still `BLOCK`, escalate per the `Review verdict BLOCK` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md` for each unresolved BLOCKER. Cap: one fix cycle + one re-review. --- ## Phase 5 — Handoff (canonical + archive) + Jira round-trip 1. **Archive the current canonical VI** (if one exists) to `/revisions/__.md` before overwrite (same-day second revision → suffix `-2`, `-3`, …). 2. **Write the refreshed VI** to the **canonical** path `/_.md`. Record `revision_of: ` and `built_from_import: ` (the Jira-import date the update was built from) in the frontmatter. 3. **Hand off** (commit-when-asked — never automatic). Present `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §4.3's consent choice verbatim: `choices: ["Branch + commit + push + open PR to main (Recommended)", "Just write the files — I'll handle git (the next phase will stop until this is on main)", "Cancel"]`. On the first choice, execute `handoff-to-main` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §2) with `prefix: vi`; `feature_folder` as resolved in Phase 0; `deliverable_paths` = the canonical VI file (step 2) and the archived snapshot file (step 1); `title: Update Value Increment`; and `body_facts` = which sections changed, the Jira-import date the update was built from, the open-question count, and the `vi-reviewer` verdict. Emit its §4.1 outcome line in the Final report. ### Jira round-trip (document to the user — they will otherwise miss it) 1. **Paste** the updated VI body (below the frontmatter) back into the Jira workitem ``. 2. **Re-import** the VI to `$VAULT_PATH/jira-products/` (via `https://github.com/ivan-gudak/jira-workitem-import`) so the downstream pipeline and the next `update-vi:` see the current text. Without these steps the update silently diverges from Jira again. --- ## Phase 6 — Next steps Offer these — guidance only, never auto-invoke — per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/next-phase-offer.md`: ``` choices: ["Re-draft the release note — release-notes: (PM)", "Re-run architecture — create-ard: (PA, if one exists)", "Re-run epics — epics: (PE)", "Re-run the spec — specify: (PE, if one exists)", "Stop here", "Other… (describe)"] ``` ### Context hygiene The resume pointer is written in the terminal maintenance phase (Phase 7), per `session-hygiene.md` §1. Then: continuing as PM → run **`/compact`**; handing to PA/PE → run **`/clear`**. Guidance only — nothing is auto-run. See `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md`. --- ## Phase 7 — Session maintenance & feedback Terminal phase — runs after Phase 6, NEVER interrupts an earlier phase. **Capture-at-block invariant.** If an EARLIER phase **halts on a plugin / skill / command / reference gap** (a capability the run needed but the plugin lacked), `emit-block` (per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/feedback-emission.md`) at that halt **before** escalating. NEVER `emit-block` for an environment / user halt (missing key, unset `$SPECS_PATH`, not-imported, cancellation) or a work-quality review BLOCK. **Session-hygiene invariant.** End Phase 6 with a `### Context hygiene` block per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md` — prepare-first (the `resume.md` write runs later, as step 3 of this terminal phase, per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md` §1 — this block prints the guidance only), then a span suggestion (PM continue → `/compact`; PA/PE handoff → `/clear`). Guidance only, never auto-run. 1. **Invoke `impl-maintenance`** (agent_type: "dev-workflows:impl-maintenance", model: ``) with a compact handoff: command `update-vi:`; what was updated (which sections changed + why); key events (import/freshness friction, BLOCK reviews, unresolved clarifications — or 'none'); workarounds; the `vi-reviewer` verdict; test result N/A; project root = the feature folder. 2. **Persist plugin feedback (automatic).** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/feedback-emission.md` and call its `emit-auto` entry point (§6) with the Lessons Learned report, `command: update-vi:`, the run's `jira_key`, `source`, and `plugin_version` (read from `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/.plugin/plugin.json`). Surface the persisted path (or "no plugin-facing signal — nothing persisted"). 3. **Write the resume pointer.** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md` §1 and write/overwrite `/dev-workflows/resume.md` now — after the feedback entry above, so the pointer reflects the completed run, and before the commit step below, so it is included in it. Redact per §1. Silent; the printed `### Context hygiene` guidance already appeared in the report. 4. **Commit session artifacts (terminal).** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` and execute its `commit-artifacts` entry point (§4) inline — the LAST action of the run. It stages ONLY the §2.1 bounded artifact paths inside `$SPECS_PATH`, commits ` Add dev-workflows session artifacts (update-vi:)` with no `Co-Authored-By` trailer, and pushes to the branch this run's handoff phase created (§4.1). It NEVER touches a code repo, a docs repo, the vault, or the current working directory; NEVER force-pushes; NEVER fails the run; and skips entirely when the run carries `specs_git: blocked` (§3.3 G0), re-emitting that notice. Hold its §6 outcome line for the Final report. ADDITIVE — this phase NEVER fails the run, NEVER commits the deliverable (git for the deliverable is offered only in Phase 5; the terminal step above commits only the bounded session-artifact paths in `$SPECS_PATH`), and NEVER writes into a code/docs repo or the current working directory; no user name is ever written. --- ## Final report Report: the canonical VI path + the archived snapshot path; which sections changed; the Jira-import date the update was built from; open-question count; the `vi-reviewer` verdict; the Dynatrace style-check outcome; the `Phase handoff:` outcome line from `handoff-to-main` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §4.1); the Jira round-trip reminder; resolved model routing (+ any Opus degradation); the feedback path; the `Specs repo:` outcome line from `commit-artifacts` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` §6), with any guard notice repeated in full; and the next-step recommendations.