Update to Syntheia

{
  "name": "redline-issues-list",
  "description": "Turn a Word document's tracked changes (redline, markup, blackline) into a structured issues list for lawyers. Use this whenever someone uploads or refers to a redlined .docx and wants the changes reviewed, summarised, risk-assessed, or turned into an issues list or change log -- including casual phrasings like 'review this redline', 'what did they change', 'go through the counterparty's markup', 'summarise the blackline', or 'is there anything nasty in here'. Reads w:ins/w:del revisions straight from the OOXML in document order with real clause numbers, separates out formatting-only edits, picks up Word comments and counter-edits, and builds a change / comments / impact table -- then asks which side of the deal the user is on and re-weights the impact ratings from that position.",
  "included_files": [
    {
      "relative_path": "scripts/extract_changes.py",
      "size_in_bytes": 49906
    }
  ],
  "skill_md_contents": "---\nname: redline-issues-list\ndescription: \"Turn a Word document's tracked changes (redline, markup, blackline) into a structured issues list for lawyers. Use this whenever someone uploads or refers to a redlined .docx and wants the changes reviewed, summarised, risk-assessed, or turned into an issues list or change log -- including casual phrasings like 'review this redline', 'what did they change', 'go through the counterparty's markup', 'summarise the blackline', or 'is there anything nasty in here'. Reads w:ins/w:del revisions straight from the OOXML in document order with real clause numbers, separates out formatting-only edits, picks up Word comments and counter-edits, and builds a change / comments / impact table -- then asks which side of the deal the user is on and re-weights the impact ratings from that position.\"\n---\n\n# Redline Issues List\n\nProduces a lawyer-facing issues list from a redlined `.docx`: every substantive\ntracked change, in document order, with a plain description, an analysis of\nwhat it does in practice, and a 1-10 impact score -- then revised once you know\nwhich side of the deal the user is on.\n\nThe value here is not in listing the edits (the script does that). It's in the\ncomments column: what the change actually does given *this document's*\ndefinitions and cross-references. A reviewer who could only get a list of\ndiffs would open Word and read the redline themselves.\n\nBackground you need: a `.docx` is a zip; the body is `word/document.xml`;\ntracked insertions are `w:ins` elements, deletions are `w:del` elements whose\ntext sits in `w:delText`; comments live in `word/comments.xml` and list\nnumbering in `word/numbering.xml`. The script below handles all of that.\n\n## Extraction\n\n`scripts/extract_changes.py` walks the document once and classifies every\nrevision. Use it rather than reading `document.xml` yourself: Word tags\nformatting-only edits with `*Change` elements that read like content edits;\nrevisions nest (an `<w:ins>` wrapping a `<w:del>` is a counter-edit across\nmarkup rounds, not a plain deletion); a substitution is routinely split by a\nstray space into what looks like two unrelated edits; clause numbers usually\nlive in `numbering.xml` rather than in the paragraph text; and changes hide in\ntable cells, footnotes, and deleted paragraph marks.\n\n```bash\npython scripts/extract_changes.py redline.docx > changes.json      # full detail\npython scripts/extract_changes.py redline.docx --markdown          # starter table\npython scripts/extract_changes.py redline.docx --all-parts         # + headers/footers\npython scripts/extract_changes.py redline.docx --seq 20-40         # one batch, full context\npython scripts/extract_changes.py redline.docx --brief             # compact index\npython scripts/extract_changes.py redline.docx --text              # greppable plain text\n```\n\nAccepts a `.docx`, an unzipped folder, or a bare `document.xml` (clause numbers\nand comments need the full package). Body, footnotes, and endnotes are scanned\nby default. Read the script's docstring for its limitations before trusting a\nclause number in an unusually numbered document.\n\n**What comes back:** `content_changes` (the table's raw material),\n`formatting_changes` (excluded, but see below), `comments`, and\n`unanchored_comments`. Each content change carries `sequence` (document order),\n`type`, `old_text` / `new_text`, `inserted_then_deleted` for counter-edits,\n`location` (heading path plus clause number), `paragraph_context` with the edit\nmarked inline as `⟦DELETED: …⟧` / `⟦INSERTED: …⟧`, plus author and date.\n\n## Workflow\n\n### 1-2. Extract, with formatting changes set aside\n\nRunning the script covers both steps: every revision is picked up, and\nformatting-only ones are already separated. Two things to do before moving on:\n\n**Check `summary.formatting_changes_needing_review`.** A `pPrChange` that also\nshifted numbering or list level is flagged there. Promoting or demoting a\nclause changes what it is subordinate to, and renumbering can silently break\ncross-references elsewhere in the document -- that is substantive even though\nWord records it as formatting. Pull anything real into the content list.\n\n**Read the `comments` list now, not later.** Word comments in a counterparty\nmarkup usually carry the negotiating rationale (\"client can't accept this\nwithout a carve-out\"), which is often the most useful thing in the file. They\naren't revisions so they don't get their own table rows, but they should inform\nthe comments column of the rows they anchor to, and any comment that raises an\nissue with no corresponding edit deserves a row of its own.\n\n### 3. The \"change\" column\n\n**One row per issue, not per revision.** A comparison tool emits a revision\nevery time the text diverges, so a single negotiated change routinely arrives\nas three or four. Twenty-nine revisions in a nine-clause agreement is normally\nabout twelve issues. Merge revisions that a lawyer would discuss as one point\n-- usually meaning they sit in the same clause and pull in the same direction\n-- and note the count in the row so nothing looks dropped (\"3 revisions\").\nKeep issues in document order.\n\nThree patterns come up constantly and each collapses to one row:\n\n- **Several edits within one clause.** A definition narrowed by adding \"clearly\n  marked as confidential\", then having \"customer lists\" struck from its\n  examples, is one issue: the definition was narrowed. Describe the net effect,\n  not each edit.\n- **A replaced table.** When `summary.replaced_tables` is non-zero, or rows\n  carry `table_status` of `wholly-inserted` / `wholly-deleted`, the tool tore\n  the table down and rebuilt it rather than editing cells. Diff the deleted row\n  set against the inserted set and report only the rows that actually differ.\n  Four inserted plus three deleted rows usually means one figure changed and\n  one row was added.\n- **A deleted clause and its renumbering wake.** Removing a clause makes the\n  headings below it shift, which surfaces as heading substitutions (\"Audit\" →\n  \"Termination\", \"9.\" → \"8.\") scattered across later clauses. That's one issue:\n  the clause was deleted and everything after it renumbered. Say so once, and\n  flag it as a cross-reference risk -- any provision that referred to the old\n  numbers now points somewhere else.\n\nLead each row with the location so it can be found in Word:\n\n| change |\n|---|\n| §1 (Definitions): \"Confidential Information\" narrowed — now requires clear marking at disclosure, and customer lists removed from the examples (3 revisions) |\n| §2.1 (Initial Term): term extended from three years to five |\n| §2.2 (Renewal): non-renewal notice cut from 90 to 30 days, and a new termination-for-convenience right added on 60 days' notice (2 revisions) |\n| §3 (Fees) — fee table: monthly fee raised from $10,000 to $12,500 and a new late payment fee of 1.5% per month added (table rebuilt, 7 revisions) |\n| §7: Audit clause deleted in full; clauses 8 and 9 renumbered to 7 and 8 (6 revisions) |\n\nSummarise long insertions rather than reproducing them; the exact wording is in\nthe JSON. Keep the \"so what\" out of this column -- that's the next one.\n\n### 4. The \"comments\" column\n\nThis is where the work is. For each row, explain the practical consequence,\ngrounded in the document rather than in what a clause of that kind usually\nsays. Get a clean searchable copy of the text first:\n\n```bash\npython scripts/extract_changes.py redline.docx --text > plain.txt   # then grep it\n```\n\nThat prints the document with changes accepted, one paragraph per line prefixed\nby its clause number, so a hit tells you where the definition lives. It uses\nthe same parser as the extraction, so it works on any file the extraction\nworked on -- `pandoc -t plain` is fine too but refuses some valid `.docx`\nfiles, and finding that out mid-analysis wastes a step.\n\nFor each row, check the things that change the answer:\n\n- **Defined terms.** If the changed text or its surrounding context uses a\n  capitalised term, find its actual definition in this document before\n  commenting. A one-word change to a heavily cross-referenced term can be the\n  highest-impact row in the table precisely because of its reach -- but only\n  checking tells you that. Grep the plain text for how many times the term\n  appears; a term used forty times is a different proposition from one used\n  twice.\n- **Cross-references.** \"Subject to Section 8\" or \"as defined in Clause 1.1\"\n  means you need to read that provision as it now stands. Note that if a\n  paragraph-mark insertion or a numbering shift appears in the list, the\n  numbers referred to elsewhere in the document may no longer point where the\n  drafter intended -- worth checking whether any cross-reference has been\n  orphaned.\n- **Interaction between changes.** Edits are rarely independent. A deleted\n  liability cap plus an expanded indemnity is a different story than either\n  alone. Where two rows combine, say so in both.\n- **Counter-edits.** For a `counter-edit` row, the negotiating history matters:\n  who proposed what, who struck it, and whether the net position is the\n  original wording or something new. Name the authors.\n\nWrite these as a lawyer would annotate a markup for a colleague: what's\ndifferent in practice, what it exposes or protects, what to check. Where a\nchange plainly favours one party, say which -- but keep the framing neutral\nuntil step 7, since the user's side isn't known yet.\n\nIf a check comes up empty (a defined term you can't locate, a cross-reference\nto a schedule that isn't in the file), say so in the row rather than\nsubstituting a plausible-sounding generality. \"Refers to Schedule 3, not\nincluded in this file\" is useful; a confident guess about what Schedule 3 says\nis worse than nothing.\n\n### 5. Review before scoring\n\nThe script won't miscount rows, so checking the count against the JSON proves\nlittle. The real risk is a wrong or shallow comment. So:\n\n- **Account for every revision.** Since rows group multiple revisions, the row\n  count won't match `content_change_count` -- so check that the revisions you\n  merged into each row add up to the total. A revision that belongs to no row\n  is one you've silently dropped.\n- **Re-read the full clause** for every row you're about to score 7 or above,\n  using `paragraph_context` or the plain text. High-impact rows are the ones\n  where an error costs the most, and a change often reads differently in the\n  context of the whole clause than as an isolated diff.\n- **Distrust `move` classifications.** Comparison tools tag text as moved when\n  it merely also appears elsewhere. If a row reads as a move, confirm the text\n  really is the same in both places before describing it as relocated.\n- **Sanity-check clause numbers** on a few rows against the rendered document.\n  Inserted and deleted paragraphs shift Word's displayed numbering, so a\n  computed number is a locator to verify, not a citation:\n\n  ```bash\n  soffice --headless --convert-to pdf redline.docx   # LibreOffice, if available\n  pdftoppm -jpeg -r 100 redline.pdf page              # then read the images\n  ```\n\n  If no converter is available, skip the visual check and say so in the\n  output rather than presenting computed numbers as verified.\n\n- **Look at the densest pages** in that render if the markup is heavy. Adjacent\n  unrelated edits can group into one row, and one edit a person reads as a\n  single substitution can split across rows.\n- **Ask what's conspicuously absent.** If the counterparty rewrote the\n  indemnity but left the liability cap untouched, or accepted a clause you'd\n  expect them to fight, that's worth a line under the table. Silence in a\n  redline is information.\n\n### 6. The \"impact\" column, 1-10\n\nScore the commercial and legal significance of each change on its own terms,\nbefore accounting for the user's side. Consistency matters more than\nprecision, so use these anchors:\n\n- **9-10** — changes the deal's basic economics or risk allocation: liability\n  caps removed or multiplied, indemnity scope reversed, IP ownership moved,\n  price or payment mechanics rewritten, exclusivity granted or lost,\n  termination-for-convenience added, a condition precedent deleted.\n- **7-8** — materially shifts a party's position without redefining the deal:\n  a cap resized, an indemnity carve-out added, notice or cure periods that\n  change whether a remedy is usable, governing law or forum changed, a defined\n  term with wide reach narrowed or broadened, a numbering shift that orphans\n  cross-references.\n- **4-6** — real but bounded: term length, a specific notice period, an\n  assignment or subcontracting consent, reporting and audit obligations, a\n  single figure in a fee table.\n- **2-3** — tightening rather than substance: clarifying wording, a\n  belt-and-braces addition that restates an existing obligation, a\n  cross-reference corrected.\n- **1** — housekeeping with no legal effect: party name spelling, a date\n  correction, defined-term capitalisation made consistent.\n\nDon't compress the range. If a redline of thirty changes produces thirty scores\nbetween 4 and 6, the column isn't doing its job -- most markups contain a\nhandful of things that matter and a long tail that doesn't, and the point of\nthe score is to surface that difference. Say so explicitly if the redline\ngenuinely is all housekeeping.\n\nPresent the full table -- change / comments / impact -- as the draft.\n\n### 7. Ask the user's position, then revise\n\nThe table so far is deliberately side-agnostic, and impact isn't symmetric: a\nhigher liability cap is bad for the party bearing the liability and good for\nthe counterparty; a client focused on IP weights an ownership clause above\npayment terms. So ask:\n\n- Which side they're on (buyer/seller, licensor/licensee, borrower/lender,\n  landlord/tenant -- whatever fits), unless it's already clear from context.\n- Their key concerns, if any.\n\nAsk in plain language and offer the likely options as a short list so the\nanswer is one tap or one word. Don't stall the draft waiting for it: produce\nthe neutral table first, then ask.\n\nThen revise: re-score `impact` as risk *to them*, and rewrite comments where\nperspective changes the meaning (\"favours the Company\" becoming concretely good\nor bad news). Keep both numbers visible -- a `neutral → adjusted` column, or\nthe original in brackets -- so the user can see what their position changed,\nand reorder or flag the top few rows as the ones to negotiate. If a change is\nstrictly good for them, say so; an issues list that treats every edit as a\nproblem is not useful.\n\n## Using the Syntheia workspace\n\nThe comments column depends on reading definitions and cross-referenced\nclauses as they stand in the full agreement. When the agreement (or the\nversion it was marked up from) is indexed in the user's Syntheia workspace,\nuse the Syntheia tools for that instead of grepping the plain text:\n\n- `list-syntheia-documents` to confirm the document is there and resolve its\n  `doc_id`; `list-syntheia-documents-by-tag` if the user names a matter,\n  party, or jurisdiction rather than a title.\n- `get-syntheia-index-json` on that `doc_id`, then one\n  `get-syntheia-index-provisions` call for the definitions and every clause\n  a changed provision points to. It returns verbatim text with one level of\n  cross-references already expanded and a link to each source clause, which\n  is exactly what a row's comment should cite.\n- `search-syntheia-provisions` when the user asks how the changed clause\n  compares to the firm's other agreements: search the workspace for the\n  clause as it now reads and report where the redlined position sits against\n  the precedents that come back.\n\nQuote provision text from these tools verbatim in the comments column and\nkeep the source links; never paraphrase a definition you retrieved. If the\ndocument is not in the workspace, fall back to the plain-text extraction\nabove and say which source you used.\n\n## Large redlines\n\nA 200-change markup won't fit in one readable table or one context window.\nDon't truncate silently or drift into shorter comments as the table goes on --\neither would leave the user unsure whether the tail was reviewed.\n\nInstead: start with `--markdown` for the index of every change with its\nlocation, tell the user the count, and work in batches of roughly 20-30 with\n`--seq 1-25`, `--seq 26-50`, filling comments and scores per batch. Then\nconsolidate. Two things help keep it manageable:\n\n- **Group conforming changes.** Eight instances of the same defined term being\n  replaced throughout is one issue, not eight rows -- one row, noting where it\n  recurs.\n- **Offer a materiality floor.** For very large markups, ask whether the user\n  wants everything or only rows scoring above a threshold, with the rest listed\n  in a short appendix. Let them choose rather than deciding for them.\n\n## Output\n\nDefault to the table inline in the conversation -- that's where the review\nhappens. Offer a `.docx` or `.xlsx` export for circulating to the deal team\nrather than assuming one is wanted.\n\nOne caution worth stating in the output: this is a review aid, not advice. It\nflags what changed and what it appears to do, for a lawyer to verify against\nthe document and the deal.\n"
}