update-impact

Files (1)

• SKILL.md

SKILL.md (first lines)

# Does a document need updating after a change?

Goal: given **what changed** (a saved comparison report, or an old+new revision
pair) and a **target document** (a policy, contract, manual, or summary that was
written against the old state), classify each change as affecting the target or
not, and point at the exact target sections that need editing.

Rules:
- Report only what the fetched texts show; never guess from titles, headings, or
  outside knowledge.
- Every claim about the target document needs a `[d.x.N]` citation to the target
  chunk it came from, and every claim about a change needs the report's (or
  revisions') citation. An AFFECTED finding therefore carries citations to BOTH
  sides.
- **Never classify a change as UNAFFECTED from search silence alone.**
  `search_docs` is ranked retrieval and can miss; before writing UNAFFECTED,
  `check_text` the target for the change's key term(s) — the old value, the
  renamed body, the amount — and only assert UNAFFECTED after "not found".
- The decisive AFFECTED signal is the target still stating the OLD rule: run
  `check_text` on the target with the superseded value or name (e.g. the old
  fee cap, the abolished committee). A hit is proof, and its citation is the
  edit location.
- Do not draft the corrected text unless the user asks; the deliverable is the
  impact report. If asked to also propose edits, quote the current target text
  and the new rule side by side, both cited.
- Quote numbers, amounts, dates and names exactly as written.

## Step 1 — Identify the inputs

You need (a) the change source and (b) the target document, as scoped ids
(`u.N`, `s.N`, `p.N`, or `p<project>.N` for another project's document).

- **Change source**: prefer a saved comparison report (`list_documents` — save_doc
  reports are usually titled "Comparison: …"). If none exists but the user named
  two revisions, produce one first with the compare-versions flow (align_docs
  mode "versions"), save it, then continue here.
- **Target**: resolve from the user's wording via `list_documents` (match the
  description, not just the title). If several documents plausibly match,
  `ask_user`.

## Step 2 — Pair the report's changes with the target's sections

    align_docs({"doc_a": "<report id>", "doc_b": "<target id>", "mode": "topical"})

The summary pairs each change item in the report with the target sections about
the same subject. Fetch the paired sections (view="pairs", batching pair numbers
like compare-versions does) — each pair shows a change next to the target text
that may embody the old rule.

Report sections with NO target counterpart in the summary are only *candidates*
for UNAFFECTED — confirm in Step 3.

## Step 3 — Verify each change against the target

For every substantive change in the report, in pair order:

1. Extract its key terms: the old value, the new value, and the topic's
   distinctive words (both old and new names when something was renamed).
2. `check_text` the target for the OLD value/name.
   - Found → **AFFECTED**: the target still states the superseded rule. Cite the
     target chunk (the edit location) and the report chunk (the reason).
3. If the old value is absent, `check_text` for the topic term; also use the
   Step 2 pair text.
   - The target discusses the topic but with wording that neither matches the
     old nor reflects the new rule → **REVIEW**: a human must judge; cite the
     closest target chunk and say what to compare.
   - "not found" for both old value and topic → **UNAFFECTED** (state which
     check_text probes came back empty).

## Step 4 — Report

1. **Verdict** — one sentence: does the target need updating, and how much
   (e.g. "3 sections must change, 2 need review, 9 changes don't touch it").
2. **Must update** — numbered AFFECTED findings: target section (cited) →
   what it currently says → what changed (cited) → what the edit must reflect.
3. **Review** — the REVIEW findings with what to compare.
4. **Not affected** — one line per UNAFFECTED change, with the probe terms that
   came back "not found".

## Step 5 — Save the report (default ON)

Unless the user said not to save it:

    save_doc({"title": "Update impact: <target title> vs <report title>", "content": "<the full report>"})

Do NOT pass a scope — the default is correct. Keep all `[d.x.N]` citations in
the saved content. Tell the user it was saved, **state its scoped id from the
save_doc result** (e.g. "saved as **p.22**" — the clients render that id as a
clickable link that opens the report, so never omit it), and that they can ask
to draft the actual edits next.

From ivoras/harlequin, AGPL-3.0.

More from ivoras/harlequin