skilldrop-cli 0.16.44 → 0.16.46

package/catalogue.json

@@ -42,6 +42,7 @@
         "agent-budget",
         "terraform-module",
         "mcp-pairing",
+        "context-graph",
         "event-contract-draft"
       ]
     },

package/model-routing.json

@@ -270,6 +270,7 @@
       "tier": "standard",
       "rationale": "Reads a SKILL.md and synthesizes eval cases — requires understanding of skill intent but not heavy reasoning."
     },
+    "context-graph": {"tier": "standard", "rationale": "The decision graph and its consistency checks are computed by its script; the model quotes the governing record and writes the fixes."},
     "event-contract-draft": {
       "tier": "standard",
       "rationale": "Contract drafting against the AsyncAPI shape with fixed rules on ordering, delivery and versioning; mid tier is enough."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.44",
+  "version": "0.16.46",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/packs/converters/skills/md-to-html/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "md-to-html",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Turn a Markdown draft into one self-contained, print-friendly HTML file that survives being emailed or attached, with headings that have anchor links, tables, code, quotes, an optional table of contents, local images embedded, brand colours and fonts from a brand.json, Mermaid diagrams kept as text or drawn from a pinned CDN, and raw HTML escaped so nothing in the source runs. Use when the user wants Markdown \"as a web page\", \"as an HTML file I can send\", \"something people can open in a browser and print\", or says \"convert this to HTML\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/converters/skills/md-to-html/scripts/md_to_html.py

@@ -552,6 +552,9 @@ def build_toc(headings):
 
 
 def convert(src_text, base_dir, brand_path=None, toc=False, mermaid="none", allow_html=False):
+    # \x00 and \x01 mark the converter's own placeholders (code spans, line breaks); a source
+    # that contains them would collide with those markers, and neither belongs in a document.
+    src_text = src_text.replace("\x00", "").replace("\x01", "")
     ctx = Ctx(base_dir, allow_html, mermaid)
     brand = load_brand(brand_path, ctx)
     lines = src_text.replace("\r\n", "\n").replace("\r", "\n").split("\n")

package/packs/design/skills/brand-kit/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "brand-kit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Capture a brand once as a reusable brand.json — logo files (and an on-dark version), colour roles as hex codes, heading and body fonts, voice, imagery rules, a PowerPoint template, contact details and the legal footer — plus a one-page BRAND.md, with text contrast checked and every value traced to where it came from. Use when the user wants decks, flyers or documents in their branding, says \"use our brand\", \"here's our logo and colours\", \"set up our brand kit\", or hands over brand guidelines.",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/design/skills/brand-kit/scripts/check_brand.py

@@ -35,7 +35,7 @@ def contrast(a, b):
     return (la + 0.05) / (lb + 0.05)
 
 
-def main(argv):
+def _main(argv):
     if len(argv) != 1:
         print(__doc__)
         return 2
@@ -116,5 +116,15 @@ def main(argv):
     return 1 if fails else 0
 
 
+
+def main(argv):
+    """Run, and turn an input that parses but has the wrong shape into one clear error."""
+    try:
+        return _main(argv)
+    except (KeyError, TypeError, AttributeError, IndexError, ValueError) as e:
+        print("error: couldn't read the input as a brand file (%s: %s). If it is one, this is a bug: "
+              "please report it with the file." % (type(e).__name__, e), file=sys.stderr)
+        return 2
+
 if __name__ == "__main__":
     sys.exit(main(sys.argv[1:]))

package/packs/dev-team/skills/behaviour-equivalence/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "behaviour-equivalence",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Prove that a rewritten, migrated or refactored component behaves the same as the old one with a golden-master comparison — record inputs and outputs at a boundary (HTTP, function calls, batch files, DB writes, events) from production-shaped traffic and edge cases, run the old system twice to find its nondeterminism, normalise narrowly field by field, replay against the new one, triage every difference as defect, intended change (with a named approver) or missing normalisation, and give a verdict of EQUIVALENT, EQUIVALENT EXCEPT LISTED CHANGES, NOT EQUIVALENT or NOT PROVEN. Use when the user asks \"does the new one behave the same as the old one\", \"can we sign off the rewrite\", \"are these diffs just noise\", wants a golden-master, approval or shadow-traffic comparison, a parity check between old and new outputs, or says \"prove behaviour equivalence\".",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },

package/packs/dev-team/skills/behaviour-equivalence/scripts/golden_diff.py

@@ -495,7 +495,7 @@ def render(rep, max_diffs):
     return "\n".join(out) + "\n"
 
 
-def main(argv=None):
+def _main(argv=None):
     ap = argparse.ArgumentParser(description="Golden-master diff of old vs new recorded outputs.")
     ap.add_argument("old", help="directory or JSONL file of the old system's outputs")
     ap.add_argument("new", help="directory or JSONL file of the new system's outputs")
@@ -522,5 +522,15 @@ def main(argv=None):
     return 0 if rep["verdict"] != "NOT EQUIVALENT" else 1
 
 
+
+def main(argv=None):
+    """Run, and turn an input that parses but has the wrong shape into one clear error."""
+    try:
+        return _main(argv)
+    except (KeyError, TypeError, AttributeError, IndexError, ValueError) as e:
+        print("error: couldn't read the input as recordings and rules (%s: %s). If it is one, this is a bug: "
+              "please report it with the file." % (type(e).__name__, e), file=sys.stderr)
+        return 2
+
 if __name__ == "__main__":
     sys.exit(main())

package/packs/frontend/skills/bundle-size-review/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "bundle-size-review",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Find what makes a JavaScript bundle heavy and what can safely come out, from the bundler's stats file (webpack stats.json, an esbuild metafile, or the rollup-plugin-visualizer raw-data JSON that Vite builds use) read together with the repo around it (package.json, .browserslistrc, the lockfile, the bundler config and the source files that import the heavy modules). Gives each entry's first-load JavaScript in the exact bytes the stats record, kept apart from lazy chunks; finds whole-library imports, CommonJS packages that can't be tree-shaken, packages bundled twice and polyfills the browser targets don't need; names the import chain that pulls each module in before suggesting a removal; and, given before and after stats, says what grew, why, whether it lands in the first load and which per-entry budget would have caught it. Use when the user says \"why is our bundle so big\", \"what can we cut from the bundle\", \"review this stats.json\", \"why is lodash or moment in our bundle\", \"the bundle grew in this PR\", or \"set a bundle size budget\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/frontend/skills/bundle-size-review/scripts/bundle_stats.py

@@ -500,6 +500,8 @@ def load(path):
                 text = fh.read()
     except OSError as e:
         raise InputError("cannot read %s: %s" % (path, e))
+    except UnicodeDecodeError:
+        raise InputError("%s is not UTF-8 text; save it as UTF-8" % path)
     if not text.strip():
         raise InputError("%s is empty" % path)
     try:
@@ -1574,7 +1576,7 @@ def to_jsonable(o):
     raise TypeError(type(o))
 
 
-def main(argv=None):
+def _main(argv=None):
     ap = argparse.ArgumentParser(description="Size a JS bundle from webpack stats, an esbuild metafile or rollup-plugin-visualizer raw data, and read the project files around it.")
     ap.add_argument("stats", nargs="?", help="stats file, or - for stdin")
     ap.add_argument("--compare", nargs=2, metavar=("BEFORE", "AFTER"), help="diff two stats files")
@@ -1629,5 +1631,15 @@ def main(argv=None):
     return 1 if over else 0
 
 
+
+def main(argv=None):
+    """Run, and turn an input that parses but has the wrong shape into one clear error."""
+    try:
+        return _main(argv)
+    except (KeyError, TypeError, AttributeError, IndexError, ValueError) as e:
+        print("error: couldn't read the input as webpack, esbuild or Vite stats (%s: %s). If it is one, this is a bug: "
+              "please report it with the file." % (type(e).__name__, e), file=sys.stderr)
+        return 2
+
 if __name__ == "__main__":
     sys.exit(main())

package/packs/frontend/skills/web-performance-review/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "web-performance-review",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Read a Lighthouse report or PageSpeed Insights result, with field data when there is any (CrUX, PSI loadingExperience or RUM p75), and say what makes the page slow for real users and what to fix first, ranked by how much each fix moves LCP, INP and CLS at the 75th percentile. Names the LCP element and which LCP phase dominates, the elements that shift and why, the long tasks and third parties by main-thread time, and treats estimated savings as lab estimates that overlap. Use when the user shares a Lighthouse JSON or PSI result and asks \"why is this page slow\", \"what should we fix first\", \"we score 92 but Search Console says LCP is poor\", \"did our change fix INP\", \"review this Lighthouse report\", or \"how do we pass Core Web Vitals\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/frontend/skills/web-performance-review/scripts/lh_summary.py

@@ -702,7 +702,7 @@ def cmp_md(c):
     return "\n".join(L)
 
 
-def main():
+def _main():
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("reports", nargs="+", help="Lighthouse JSON, PSI JSON or CrUX JSON path, or - for stdin (max 2)")
     ap.add_argument("--field", help="extra field data: a PSI response or CrUX API record JSON")
@@ -744,5 +744,15 @@ def main():
         print(text)
 
 
+
+def main():
+    """Run, and turn an input that parses but has the wrong shape into one clear error."""
+    try:
+        return _main()
+    except (KeyError, TypeError, AttributeError, IndexError, ValueError) as e:
+        print("error: couldn't read the input as a Lighthouse, PageSpeed Insights or CrUX report (%s: %s). If it is one, this is a bug: "
+              "please report it with the file." % (type(e).__name__, e), file=sys.stderr)
+        return 2
+
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

package/packs/grc/skills/risk-register/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "risk-register",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Build or update an enterprise or project risk register — each risk written as cause, event and consequence, scored for likelihood and impact on a defined scale, inherent and residual ratings, a named owner, a treatment (avoid, reduce, transfer, accept), controls, a due date and a review trigger — with a heat map, the top risks that need a decision, and a stdlib script that validates the register CSV and flags overdue reviews. Use when the user wants a risk register, a risk log, a RAID log's risk section, a heat map, or says \"what are our top risks\", \"update the risk register\", \"score these risks\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/grc/skills/risk-register/scripts/check_register.py

@@ -152,8 +152,16 @@ def main(argv=None):
     except (IOError, OSError) as exc:
         print("error: cannot read %s: %s" % (args.csv, exc), file=sys.stderr)
         return 2
+    except UnicodeDecodeError:
+        print("error: %s is not UTF-8 text; save it as UTF-8 (in Excel: CSV UTF-8)" % args.csv, file=sys.stderr)
+        return 2
 
-    reader = csv.DictReader(io.StringIO(text))
+    try:  # parse once up front, so a malformed file is one clear error, not a traceback mid-loop
+        list(csv.reader(io.StringIO(text, newline="")))
+    except csv.Error as exc:
+        print("error: %s is not a readable CSV: %s" % (args.csv, exc), file=sys.stderr)
+        return 2
+    reader = csv.DictReader(io.StringIO(text, newline=""))
     if not reader.fieldnames:
         print("error: %s has no header row" % args.csv, file=sys.stderr)
         return 2

package/packs/infra-as-code/skills/terraform-plan-review/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "terraform-plan-review",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Review a terraform plan before apply, from the plan text or terraform show -json output. Flags every destroy and replace with the attribute forcing it, changes to stateful resources such as databases, buckets and volumes, IAM and security-group widening, drift nobody made in code, and changes outside the intended scope, then gives a SAFE TO APPLY, APPLY WITH CARE or DO NOT APPLY verdict with reasons. Use when the user pastes a plan, says \"review this terraform plan\", \"is this plan safe to apply\", \"why is terraform replacing my database\", or \"check the plan before I apply\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/infra-as-code/skills/terraform-plan-review/scripts/plan_summary.py

@@ -338,7 +338,7 @@ def to_markdown(r):
     return "\n".join(lines) + "\n"
 
 
-def main():
+def _main():
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("plan", help="path to `terraform show -json` output, or - for stdin")
     ap.add_argument("--scope", action="append", default=[],
@@ -359,5 +359,15 @@ def main():
         sys.stdout.write(text)
 
 
+
+def main():
+    """Run, and turn an input that parses but has the wrong shape into one clear error."""
+    try:
+        return _main()
+    except (KeyError, TypeError, AttributeError, IndexError, ValueError) as e:
+        print("error: couldn't read the input as a Terraform JSON plan (%s: %s). If it is one, this is a bug: "
+              "please report it with the file." % (type(e).__name__, e), file=sys.stderr)
+        return 2
+
 if __name__ == "__main__":
-    main()
+    sys.exit(main())

package/packs/product-manager/skills/feedback-synthesis/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "feedback-synthesis",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn raw customer feedback — interview notes, support tickets, NPS or CSAT verbatims, app-store reviews, sales-call notes — into ranked themes a product decision can rest on, each a problem statement rather than a feature request, counted by distinct people or accounts not mentions, with segments, severity kept separate from frequency, verbatim quotes with source IDs, what people value, where sources disagree, what the sample cannot tell, and the questions for the next interviews. A stdlib script computes the counts. Use when the user says \"what are customers telling us\", \"synthesise this feedback\", \"find the themes in these tickets / reviews / NPS comments\", \"affinity map these interview notes\", or \"what should we fix first based on feedback\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/product-manager/skills/feedback-synthesis/scripts/theme_counts.py

@@ -75,6 +75,8 @@ def load(path: Path, person_col: str, ignore: set, segments_wanted: list):
         text = path.read_text(encoding="utf-8-sig")
     except OSError as e:
         die(f"cannot read {path}: {e}")
+    except UnicodeDecodeError:
+        die(f"{path} is not UTF-8 text; save it as UTF-8 (in Excel: CSV UTF-8)")
     reader = csv.DictReader(text.splitlines())
     if not reader.fieldnames:
         die(f"{path} has no header row")
@@ -334,7 +336,10 @@ def main(argv=None) -> int:
     a = ap.parse_args(argv)
 
     ignore = DEFAULT_IGNORE | {c.lower() for c in a.ignore}
-    rows, segs, warnings = load(a.csv, a.person_col, ignore, a.segment)
+    try:
+        rows, segs, warnings = load(a.csv, a.person_col, ignore, a.segment)
+    except csv.Error as e:  # e.g. a NUL byte, which Python before 3.11 rejects
+        die(f"{a.csv} is not a readable CSV: {e}")
     if not rows:
         die(f"{a.csv} has no feedback rows")
     label = a.person_label or ("person" if a.person_col == "person_id" else a.person_col.replace("_id", "").replace("_", " "))

package/packs/research/skills/hypothesis-comparison/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "hypothesis-comparison",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Compare rival explanations for an observation with analysis of competing hypotheses (ACH) — list the hypotheses and the evidence, build a consistency matrix (consistent / inconsistent / neutral), rank hypotheses by how little evidence contradicts them rather than how much supports them, name the diagnostic evidence and the linchpins, and say which next observation would tell the leaders apart. Use when the user asks \"why did X happen\", \"which explanation fits the evidence\", \"what's really causing this\", wants to stop arguing over a favourite theory, or says \"compare these hypotheses\", \"competing explanations\", \"ACH\".",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/research/skills/hypothesis-comparison/scripts/ach_matrix.py

@@ -33,6 +33,7 @@ Exit codes: 0 report written, 2 bad input.
 
 import argparse
 import csv
+import io
 import sys
 from pathlib import Path
 
@@ -53,7 +54,11 @@ def load(path):
     p = Path(path)
     if not p.is_file():
         fail("file not found: " + str(path))
-    with p.open(newline="", encoding="utf-8-sig") as f:
+    try:
+        text = p.read_text(encoding="utf-8-sig")
+    except UnicodeDecodeError:
+        fail("{} is not UTF-8 text; save it as UTF-8 (in Excel: CSV UTF-8)".format(path))
+    with io.StringIO(text, newline="") as f:
         reader = csv.DictReader(f)
         if not reader.fieldnames:
             fail("the CSV is empty")
@@ -123,7 +128,10 @@ def main():
     ap.add_argument("-o", "--output", help="write the report here instead of stdout")
     args = ap.parse_args()
 
-    hyps, rows = load(args.matrix)
+    try:
+        hyps, rows = load(args.matrix)
+    except csv.Error as e:  # e.g. a NUL byte, which Python before 3.11 rejects
+        fail("{} is not a readable CSV: {}".format(args.matrix, e))
     s = scores(hyps, rows)
     order = ranking(hyps, s)
     top = leaders(hyps, s)

package/packs/solution-architect/skills/context-graph/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: context-graph
+description: Map the decisions behind a codebase from its ADRs, RFCs and design records — each record's status and date, what supersedes or amends what, which records cite which, the files and folders each decision governs, and with git the commits that implemented it — then answer "why is it like this?" from the record and check the record is still true. Finds supersessions only one side records, current decisions pointing at code that is gone, two current decisions governing the same path, and references to records that don't exist. Use when the user asks "why do we use X", "which decisions govern this file or service", "is this ADR still current", "are our ADRs out of date", "what was decided before I change this", wants a map of the architecture decisions, or is onboarding onto a codebase's history.
+---
+
+# context-graph
+
+Answers "why is it like this?" from what the team actually decided and wrote down, and says
+plainly when nothing was written down. It reads every decision record (ADRs, RFCs, design
+decisions), builds the graph between them and the code they govern, and checks that graph against
+the repository as it is today. Writing a new or corrected record is `adr-generator`. Explaining how
+the code works now, with no decision history, is `codebase-tour`. Recovering the architecture from
+the code itself is `reverse-architecture`.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
+- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
+- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
+- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
+- **For this skill:** A rationale comes only from a record, quoted or cited by its id, and a record is only as true as the code: check the one that answers the question against the files it governs. When no record covers it, say "no recorded decision" and, at most, what the code shows, labelled as inferred. Never mention the script, the graph or any tool in the reply; say what the records and the code show.
+
+1. **Find the records and build the graph with the script.** Read numbers, statuses and links from its output, not by eye. It finds records in the usual folders (`docs/adr`, `docs/decisions`, `docs/rfcs`, `architecture/decisions`, …) or the ones you name, and exits 2 when there are none.
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/context_graph.py" --root .
+   python3 "${CLAUDE_SKILL_DIR}/scripts/context_graph.py" --root . --why services/orders/consumer.py
+   python3 "${CLAUDE_SKILL_DIR}/scripts/context_graph.py" --root . --record ADR-0004 --git
+   # Other IDEs (from the skill folder)
+   python3 scripts/context_graph.py --root <repo> --docs architecture/decisions --json -o graph.json --mermaid graph.mmd
+   ```
+   `--git` adds the commits whose messages mention each record. A path counts as governed when a record names it in backticks or links to it, and it exists. Without the script, do the same by hand and say the links were found by reading, not computed.
+
+   **The script's findings are leads, not answers.** Confirm each one by reading the records and the code before you report it, and drop the ones that don't hold. Two records "governing the same path" often don't clash at all: say so only when their decisions actually conflict, and quote both.
+
+2. **Answer "why" from the current record, and show the chain.** Say which decision governs the thing now, with its id, title, status and date, and the reason as the record states it. Then name what it replaced, if anything.
+   - ✅ *"Order events moved from Kafka to SQS in ADR-0009 (accepted 2026-02-10): 'one fewer system to run, and the volume fits SQS'. ADR-0004 chose Kafka in 2025 and is still marked Accepted, so anyone reading it alone gets the wrong answer."*
+   - ❌ *"You use Kafka for order events (ADR-0004), which gives you durability and ordering."* That reads the superseded record and adds a rationale that isn't in it.
+
+3. **Trust the newest record only when the chain agrees.** A record superseded by another is history, even when its own Status line still says Accepted. The script lists each such one-sided supersession as a problem. Say which record a reader should rely on and why.
+
+4. **Check the deciding record against the code.** Open the files it governs and check each thing the record requires (every "must", every named field, check, limit or setting), not only its headline. Confirm or contradict each with the code, quoting the line: ✅ *"`scheduler/jobs.py` line 18 still opens a database transaction per job, as ADR-0012 says."* Report drift as a finding with both sides: ✅ *"ADR-0015 promises 30 days of audit-log retention; `ops/logging.yaml` sets `retention_days: 14`."* When the record describes a phased change (a migration, a dual-write, a rollout), say which phase the code is in. While it's mid-rollout, the old decision still holds for the parts not yet moved: that is a missing cross-reference, not a contradiction.
+
+5. **For "can I remove or change X?", search the code for every use of X,** not only the records: imports, client constructors, config keys, environment variables and container definitions. A use that no record covers is still a dependency: list it as "in use, no recorded decision", with its file. The records tell you why; only the code tells you everything that would break.
+
+6. **Find the decisions that bear on it, not only the ones that name its path.** Read any record that amends, extends or narrows the governing one, and any that sets a rule for the same concern across the codebase (error handling, data access, logging, authentication), even when it names a different folder. A shared-library rule governs a change that creates a shared library. Before you call a related record unrelated, read it.
+
+7. **Report what is no longer true, worst first.** Problems before warnings:
+   - **Supersession recorded on one side only:** "ADR-0004 still says Accepted". Fix it by marking it "Superseded by ADR-0009".
+   - **A current decision pointing at code that is gone:** the record names a folder or file that no longer exists. When the script suggests where it moved (a renamed sibling), or a README says so, report it as moved, not gone, and give the path to update. Only a path with no successor is gone; then the decision is dead, so deprecate it.
+   - **A guide that still teaches a superseded decision:** an onboarding doc or a README that cites the old record, or describes its choice. Name the file and the line to change.
+   - **Two current decisions governing the same path, neither superseding nor amending the other:** a possible conflict. Read both, quote the clash if there is one, and recommend which one supersedes or amends the other.
+   - **A reference to a record that doesn't exist, a status that's missing or unrecognised, or a duplicate id.**
+
+8. **Give each fix as the exact edit.** The line to change in which record, such as changing `## Status` to `Superseded by ADR-0009`, linked to that record's file, or the new record that's needed and what it must decide. Don't rewrite records nobody asked about.
+
+9. **Say what the record can't tell.** Decisions made in chat or tickets and never written down, code that no record governs, and, without `--git`, whether anything was actually implemented. When a question has no record, say so, and suggest writing one only if the decision is still live.
+
+10. **Write the reply in this order, at the size asked for:**
+   - the answer, in two or three sentences, with the governing record's id;
+   - the chain or the problems, as a short list, each with its record id and the fix;
+   - what the records don't cover;
+   - "To confirm", only for inputs that are missing.
+
+   Answer each question someone asked, in their order. A length they set is a limit: "two lines" is two lines, with the decision and the one thing they must not miss. When they say "keep it short" or "don't need an essay", give a few lines per question, and at most one line on record hygiene that doesn't change the answer. Give a table when they ask for a map, a list or something to paste; otherwise none. No closing offer or summary line.
+
+**Non-interactive runs** (subagent, CI, headless): with no records found, emit `BLOCKED: no decision records found; name the folder that holds the ADRs or RFCs`. Exit 1 from the full check means problems were found. Report them; never edit the records yourself.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): the record formats read (MADR, Nygard, RFC frontmatter), how status, supersession, amendment and governed paths are detected, every check and its fix, and the JSON shape
+- [`scripts/context_graph.py`](scripts/context_graph.py): stdlib; builds the graph, checks it, answers `--why PATH` and `--record ID`; `--json`, `--mermaid`, `--git`; exits 1 on problems and 2 on bad input
+- [`examples/order-events.md`](examples/order-events.md): worked example, a repo whose Kafka ADR was superseded on one side only and whose newer ADR names a folder that was deleted
+
+## Quality bar
+
+- **The answer names the governing record by id, status and date**, and the rationale is quoted or closely paraphrased from that record. No reason is supplied that the record doesn't give.
+- **A superseded record is never presented as current**, including one whose own Status line wasn't updated.
+- **"No recorded decision" is said when it's true**, and any reading of the code is labelled as inferred.
+- **Every problem names its record id and the exact fix.** Problems come before warnings.
+- **Two current records on the same path are raised as a possible conflict**, not silently resolved by date.
+- **The deciding record is checked against the code it governs, claim by claim,** with the line quoted, and drift is reported with both sides. A line number is given only when read from the file.
+- **Every script finding in the reply has been confirmed by reading;** one that doesn't hold is dropped.
+- **A removal or change question lists every use of the thing in the code,** recorded or not.
+- **Related records are read before they're called unrelated:** amendments, and rules for the same concern elsewhere in the codebase.
+- **A moved path is reported as moved, with its new location; only a path with no successor is "gone".**
+- **A mid-rollout pair of records is a missing cross-reference, not a contradiction.**
+- **The reply fits the size asked for (a stated limit is obeyed exactly), and never mentions a script, a graph or a tool.**
+- **Statuses, links and governed paths come from the script's output**, or are marked as read by hand when it couldn't run.
+- **No invented records, ids, dates, paths or commits.**
+
+## When to use this skill
+
+- ✅ "Why do we use X?" or "Why is this service built this way?" in a repo with ADRs or RFCs
+- ✅ "Which decisions govern this file, folder or service before I change it?"
+- ✅ "Are our ADRs still current?" or "Find the stale or contradictory decisions"
+- ✅ A map of a codebase's architecture decisions for onboarding or a review
+
+## When NOT to use this skill
+
+- ❌ Writing a new ADR or fixing one: use `adr-generator`
+- ❌ How the code works now, with no decision history: use `codebase-tour`
+- ❌ Recovering the architecture from code with no records: use `reverse-architecture`
+- ❌ A record of business or product decisions for stakeholders: use `decision-log`
+
+## Anti-patterns to avoid
+
+- ❌ **Reading one ADR and stopping.** The record that answers the question may have been superseded by a later one that never touched the first file.
+- ❌ **Trusting a Status line over the chain.** "Accepted" on a record another record supersedes means someone forgot to update it, not that it is still in force.
+- ❌ **Supplying the reason.** "Kafka gives you ordering" is general knowledge, not the team's decision. If the record doesn't say why, say it doesn't.
+- ❌ **Resolving a conflict by date alone.** Two current records on the same path need a person to decide which wins; the newer one isn't automatically right.
+- ❌ **Listing every record.** Answer the question; the full table is for a map that was asked for.
+- ❌ **Passing on a script warning unread.** "Both govern the same path" is a prompt to read both, not a conflict.
+- ❌ **Answering "can I remove it?" from the records alone.** The uses nobody recorded are the ones that break.
+- ❌ **Taking the record's word for it.** A decision the code no longer follows is the most useful thing to find; read the files.
+- ❌ **"Gone" for a folder that was renamed.** Look for where it went before telling someone the decision is dead.
+- ❌ **Telling the reader how you found it.** "The script shows" or "the graph says" means nothing to them; say what the records and the code say.

package/packs/solution-architect/skills/context-graph/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  {"query": "Why do we use Kafka for order events? Is the ADR that chose it still the current decision?", "should_trigger": true},
+  {"query": "I'm about to refactor services/billing/invoice.py. Which architecture decisions govern it that I should read first?", "should_trigger": true},
+  {"query": "Our docs/adr folder has 40 records going back five years. Find the ones that are stale, superseded without being marked, or contradict each other", "should_trigger": true},
+  {"query": "Give me a map of our RFCs and ADRs: what supersedes what, and which folders each one covers, for onboarding the new hires", "should_trigger": true},
+  {"query": "Is ADR-0012 still true? I think the code it talks about was deleted last year", "should_trigger": true},
+  {"query": "We just decided to move our search from Postgres full-text to a hosted search engine. Write the ADR for it in MADR format", "should_trigger": false},
+  {"query": "I start on the checkout repo on Monday. How do I run it locally, run the tests, and where's the code for applying discount codes?", "should_trigger": false},
+  {"query": "There are no design docs for this monolith. Work out its architecture from the code and the docker-compose file and draw me a C4 diagram", "should_trigger": false},
+  {"query": "Here are the notes from this morning's pricing steering meeting. Pull out what was decided, who owns each action and when it's due", "should_trigger": false}
+]