Update

Skill: update

Purpose: Produce a single Update Report at artifacts/00-updates/update-YYYY-MM-DD-NN.md summarising what changed in the Elicitation Document and downstream artefacts since the previous Update Report, and recommending which downstream skills to re-run to bring the pipeline back to a consistent state. The skill is the framework's update coordinator — it runs after /elicit has been re-run with new inputs and APPROVED, compares the current pipeline state against the element snapshot embedded in the previous Update Report (if any), and writes a fresh dated report. The skill is diagnostic, not generative: it mints no IDs, modifies no upstream artefact, never invokes another skill, and has no APPROVED gate of its own. Re-runs always produce a new dated file; prior reports persist for audit. The skill is forward-compatible with Component 3 (the Amendment Protocol): Section 3.5 of the Update Report template is a placeholder that becomes a populated table once AM-### amendment proposals exist.

Invocation:

• Claude Code: /update
• GitHub Copilot: "Run the update skill" or "Follow skills/update/skill.md"

Inputs (all optional except the elicit doc):

• artifacts/01-elicitation/elicitation-document.md — required; the canonical source of element state for SH / BUC / FR / NFR / CON / AC / ASMP / RSK / OQ
• inputs/manifest.md — informational; used to populate Section 2 (Inputs Processed Since Last Run) and to determine last-modified-by per element
• artifacts/00-updates/update-*.md — previous Update Reports; the highest-dated + highest-NN file is the baseline for delta computation
• artifacts/02-epics/, artifacts/03-user-stories/, artifacts/04-srs/, artifacts/05-test-concept/, artifacts/07-implementation-tasks/ — used for the Pipeline State After /elicit section and the recommendation heuristics

Outputs:

• artifacts/00-updates/update-YYYY-MM-DD-NN.md — one new file per run. Never overwrites a prior report. NN is a per-day sequence (01, 02, ...) auto-incremented for same-day re-runs.

Step 0 — No gate; ensure prerequisites exist

/update is diagnostic, not generative. It runs whenever the user invokes it. There is no upstream-Approved gate.

Two hard prerequisites:

• If artifacts/01-elicitation/elicitation-document.md does not exist: stop with "Run /elicit first; no elicit doc to derive an update report from."
• If inputs/ is empty (no files, only a README): stop with "No inputs in inputs/; /update has nothing to coordinate. Drop input documents into inputs/ and run /elicit first."

No other gates. The skill operates on whatever pipeline state exists.

Step 1 — Locate the previous Update Report

Read every file matching artifacts/00-updates/update-*.md (excluding .gitkeep).

If none exist:

• prev_snapshot = None
• Flag this run as first run; the report's frontmatter records previous-report: "none (first run)"
• next_run_number = 01 (always 01 for first run)

If one or more exist:

• Sort by run-date (descending), then by run-number (descending)
• Take the first entry as previous_report
• Parse its Appendix A YAML block — capture as prev_snapshot (mapping id → {type, status, content-hash, last-modified-by})
• For next_run_number:
  • If any existing report has today's run-date: take the max run-number for today, increment by 1
  • Otherwise: 01
  • Format as zero-padded two-digit string

Step 2 — Snapshot the current pipeline state

Walk every artefact in the pipeline and build current_snapshot — a mapping id → {type, status, content-hash, last-modified-by} for every first-class element.

For each element in the pipeline:

For each element compute:

• id: canonical identifier
• type: SH / BUC / FR / NFR / CON / AC / ASMP / RSK / OQ / EP / US / SRS / TC / TASK
• status: the value present in the element's frontmatter or status line — never reinterpreted (Pending / Accepted / Rejected / Open / Resolved / Validated / Invalidated / Mitigated / Closed depending on element type)
• content-hash: sha256 of the element's normalised body content. Normalisation rules: strip leading/trailing whitespace; collapse internal whitespace runs (spaces + tabs + newlines) to single spaces; preserve case; the hash is computed on the original normalised content (do not lowercase for hashing). Output as lowercase hex digest, 64 chars.
• last-modified-by: for elements minted/refined by /elicit: the filename in inputs/manifest.md whose most recent processing line mentions this element ID. For elements minted by downstream skills (TCs, TASKs, EPs, USs, SRS): the literal string "skill-generated".

current_snapshot is the canonical state record for this run.

Step 3 — Compute the delta

Compare current_snapshot against prev_snapshot.

If prev_snapshot is None (first run): every element is reported as "baseline" — none of the categories below apply; Sections 3.1 through 3.4 of the report show "(none — first run)". Section 3.5 shows the Component-3 placeholder text. Continue to Step 4 with an empty delta (Step 4 will recommend only /trace).

Otherwise apply these classification rules to each element ID across the union of prev_snapshot and current_snapshot:

The anomalous content change category is the Component-3 forward-compatibility hook. Component 1 does not have an amendment-proposal mechanism, so for each anomaly the skill records a Note in Section 3.5 of the report:

Note: TASK-### shows content-hash drift on Accepted element. Component 3 (Amendment Protocol) is required to handle this case properly. Manual reconciliation required: review the element, decide whether to flip status back to Pending (allowing refinement) or to keep the Accepted version (treating the input change as out-of-scope).

When Component 3 ships, the anomaly path is replaced by AM-### amendment proposals raised inside /elicit itself; /update just surfaces them in 3.5 as a table.

Step 4 — Determine downstream re-run recommendations

Apply the published heuristic table to the delta. Every recommendation carries its triggering rationale (the specific element IDs that caused it) — this rationale renders in Section 4 of the report.

If no triggers fire other than /trace: Section 4 of the report contains only the /trace recommendation with the note "No upstream changes recommend a downstream re-run; /trace is recommended only to confirm chain integrity."

The skill never invokes any of these — it only recommends.

Step 5 — Build the Mermaid cascade diagram

Render Section 5 of the Update Report as a Mermaid flowchart LR showing exactly the recommended re-runs in their dependency order. Skills NOT recommended are omitted.

Vault Mermaid rules apply: %%{init: {'theme': 'neutral'}}%% first line; short single-phrase labels; no <br/>.

Example (full cascade):

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    elicit[/elicit done/]
    epics[/create-epics needed/]
    stories[/create-stories needed/]
    srs[/create-srs needed/]
    tests[/create-tests needed/]
    tasks[/create-tasks needed/]
    trace[/trace always/]
    elicit --> epics --> stories --> srs --> tests --> tasks --> trace

Example (only /trace recommended):

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    elicit[/elicit done/]
    trace[/trace always/]
    elicit --> trace

Step 6 — Write the Update Report

Render artifacts/00-updates/update-YYYY-MM-DD-NN.md from skills/update/templates/update-report.md. Populate:

• Frontmatter: run-date (today), run-number (from Step 1), previous-report, inputs-processed (from inputs/manifest.md — only the files processed in the most recent /elicit run, not the full history)
• Section 1: narrative + counters from the delta
• Section 2: table built from the manifest (one row per input file processed in the most recent /elicit run)
• Section 3.1 — 3.4: tables populated from the delta classifications
• Section 3.5: Component-3 placeholder text plus any Anomalous-content-change Notes from Step 3
• Section 4: ordered recommendation list from Step 4
• Section 5: Mermaid diagram from Step 5
• Section 6: Pipeline state — read each artefact's frontmatter / index, fill the table
• Section 7: Open Questions table aggregated from elicit doc + every downstream artefact (current statuses)
• Section 8: Revision History — single row for this run
• Appendix A: the YAML snapshot from Step 2

If artifacts/00-updates/ does not exist: create the directory.

The file is always a fresh file, never overwriting prior reports.

Step 7 — Review summary (no APPROVED)

Present to the user:

Update report — <PROJECT_NAME>, run <YYYY-MM-DD-NN>

• Previous report: <previous filename> or "none (first run)"
• Inputs processed since previous report: <count and one-line list>
• Element-level deltas:
  • New: <N>
  • Refined Pending: <N>
  • OQs resolved: <N>
  • OQs newly raised: <N>
  • Status transitions: <N>
  • Anomalous content changes: <N> (manual reconciliation required until Component 3)
• Recommended downstream re-runs (in order): <list with one-line rationale per item, or "/trace only">
• Open Questions across the pipeline: <count by severity>

Read artifacts/00-updates/<filename>.md for the full report (cascade Mermaid diagram + Appendix A snapshot). There is no APPROVED prompt — /update is informational. Proceed by invoking each recommended downstream skill in order, reviewing and Approving its review gate as usual. After the cascade, re-run /update to confirm the next baseline.

If the delta is empty (no changes since the previous report): state "No changes detected since the previous Update Report. The new report at <filename> captures the current snapshot as the next-run baseline. Only /trace is recommended."

If this is the first run: state "First Update Report for this project. The Appendix A snapshot is the baseline for future delta computation. No downstream re-runs recommended at this time (re-run /trace to confirm chain integrity)."

ID Reference

/update mints no element-level IDs. It does not add to the OQ-### namespace (findings render inline in the report). It does not modify any upstream artefact.

When Component 3 ships, the AM-### (Amendment Proposal) namespace will be minted by /elicit, not by /update. /update will only surface AM-### proposals already present in the elicit doc.

Edge Cases