skilldrop-cli 0.16.45 → 1.0.0

package/packs/solution-architect/skills/context-graph/examples/inputs/order-events/docs/adr/0009-sqs-for-order-events.md

@@ -0,0 +1,19 @@
+---
+status: accepted
+date: 2026-02-10
+---
+# Order events on SQS
+
+## Context
+
+Only two consumers ever replayed, and the Kafka cluster is the team's largest on-call load.
+
+## Decision
+
+Supersedes ADR-0004. Order events move to SQS queues, one per consumer, published from
+`services/orders/`. The bridge in `services/kafka-bridge/` is removed once billing has moved.
+
+## Consequences
+
+One fewer system to run, and the volume fits SQS. Replay for a new consumer now means a
+backfill from the orders table.

package/packs/solution-architect/skills/context-graph/examples/order-events.md

@@ -0,0 +1,63 @@
+# Worked example: why do order events go through Kafka?
+
+A made-up repository, in [`inputs/order-events/`](inputs/order-events/), with three ADRs:
+- **ADR-0004** chose Kafka for order events in 2025.
+- **ADR-0006** has receipts sent when the notifications service reads an OrderPlaced event, and
+  cites ADR-0004.
+- **ADR-0009** moved order events to SQS in 2026, and says it supersedes ADR-0004. Nobody updated
+  ADR-0004's Status line, and ADR-0009 names a bridge folder that has since been deleted.
+
+## The request
+
+> I'm changing `services/orders/publisher.py`. Why do we publish order events to Kafka, and is
+> that still the plan?
+
+## Script runs
+
+```bash
+python3 scripts/context_graph.py --root examples/inputs/order-events --why services/orders/publisher.py
+python3 scripts/context_graph.py --root examples/inputs/order-events
+```
+
+The `--why` output:
+
+```text
+# Decisions governing services/orders/publisher.py
+
+- **ADR-0009 Order events on SQS** (accepted, current, 2026-02-10), via `services/orders/`: docs/adr/0009-sqs-for-order-events.md
+- **ADR-0004 Kafka for order events** (marked accepted, but superseded by ADR-0009, 2025-03-02), via `services/orders/`: docs/adr/0004-kafka-for-order-events.md
+```
+
+The full check, which exits 1 because it found problems:
+
+```text
+## Problems (2)
+
+- ADR-0004 is still marked Accepted, but ADR-0009 supersedes it: mark it 'Superseded by ADR-0009'
+- ADR-0009 is accepted but points at code that is gone: services/kafka-bridge
+
+## Warnings (1)
+
+- ADR-0006 is current but cites ADR-0004, which ADR-0009 supersedes: check it still holds
+```
+
+## The reply
+
+It isn't the plan any more. ADR-0009 (accepted 2026-02-10) moved order events from Kafka to SQS
+queues, one per consumer, published from `services/orders/`. Its reasons: "only two consumers
+ever replayed, and the Kafka cluster is the team's largest on-call load". It replaces ADR-0004,
+which chose Kafka in 2025. ADR-0004's own Status line still says Accepted, so anyone reading it on
+its own gets the wrong answer.
+
+Before you change the publisher:
+
+1. **ADR-0004 needs its status fixed.** Change `## Status` to `Superseded by ADR-0009`, linked
+   to `0009-sqs-for-order-events.md`.
+2. **ADR-0009 names `services/kafka-bridge/`, which no longer exists.** If billing has moved, add a
+   line saying the bridge was removed. If it hasn't, find where the bridge went.
+3. **ADR-0006 (receipts) still cites ADR-0004.** It has the notifications service read OrderPlaced
+   events, which now come from an SQS queue. Check that the receipts consumer has its queue before
+   you change what the publisher sends.
+
+What the records don't say: when billing moved off Kafka, and whether replay for a new consumer
+(now a backfill from the orders table, per ADR-0009) has been tested.

package/packs/solution-architect/skills/context-graph/manifest.json

@@ -0,0 +1,33 @@
+{
+  "name": "context-graph",
+  "version": "0.1.0",
+  "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.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [
+    "adr-generator",
+    "codebase-tour",
+    "reverse-architecture",
+    "decision-log"
+  ],
+  "handoff": [
+    {
+      "to": "adr-generator",
+      "when": "a decision is live but unrecorded, or a record needs superseding, deprecating or correcting",
+      "purpose": "Write the new or corrected record, with the supersession link the graph found missing.",
+      "fallback": "If adr-generator is absent, give the record's title, status line, the context in two sentences, the decision and its consequences, and the exact Superseded by line for the old record."
+    }
+  ],
+  "tags": ["architecture", "adr", "decision-records", "onboarding", "documentation"],
+  "permissions": {
+    "network": [],
+    "commands": ["git"],
+    "files": "named-paths",
+    "notes": "context_graph.py reads the decision-record folders under --root and checks whether the paths they name exist. With --git it runs `git log` read-only. It writes only to the -o and --mermaid paths."
+  },
+  "model": {
+    "tier": "standard",
+    "rationale": "The graph and its checks are computed by the script; the model reads records, quotes the rationale and writes the fixes."
+  }
+}

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

@@ -0,0 +1,104 @@
+# context-graph reference
+
+What `scripts/context_graph.py` reads, how it decides each field, and every check it makes.
+
+## Where records are found
+
+Without `--docs`, every one of these folders under `--root` that exists:
+`docs/adr`, `docs/adrs`, `docs/decisions`, `docs/architecture/decisions`, `doc/adr`,
+`doc/architecture/decisions`, `adr`, `adrs`, `decisions`, `architecture/decisions`, `docs/rfcs`,
+`docs/rfc`, `rfcs`, `rfc`, `docs/design`, `docs/designs`.
+
+Every `.md` file in them, recursively, is a record, except:
+- `README.md` and `index.md`;
+- any file with "template" in its name;
+- a `0000-` file, which by convention is the template.
+
+## Fields
+
+| Field | Read from, in order |
+|---|---|
+| id | frontmatter `id`, `adr` or `rfc`; else the filename's leading number (`0007-…`, `adr-7-…`). Formatted as `ADR-0007`, `RFC-0007` or `DR-0007`, by whether the folder path says adr/decision or rfc |
+| title | frontmatter `title`; else the first `# ` heading with any "ADR 7:" prefix removed; else the filename |
+| status | frontmatter `status`; else a `Status: X` line (bold allowed); else the first line under a `## Status` heading |
+| date | frontmatter `date`, `created`, `decided` or `accepted`; else a `Date:` line; else the first ISO date in the first 15 lines |
+| supersedes | frontmatter `supersedes` or `replaces`; text "Supersedes ADR-3" or "Replaces RFC 12" |
+| superseded by | frontmatter `superseded_by` or `replaced_by`; text "Superseded by ADR-9", including in the Status line |
+| amends | frontmatter `amends`; text "Amends ADR-4", or "Extends", "Refines", "Narrows", "Overrides" or "Modifies" followed by an id |
+| cites | every id mentioned (`ADR-4`, `ADR 0004`, `RFC-12`), and every Markdown link to another record file |
+| governs | each path named in backticks or linked, that exists under `--root`: a file, or a folder (shown with a trailing `/`). `src/auth/*` counts as `src/auth` |
+| missing paths | a path that looks like the repository's (its first part is a top-level folder that exists) but doesn't exist |
+| moved | for a missing path, an existing sibling with a close name (`services/ledger-sync` → `services/ledger`), where the code may have gone |
+| commits | with `--git`: commits whose subject or body mentions the id, newest first, up to 20 |
+
+**Statuses, normalised:**
+
+| Status | Words read as it |
+|---|---|
+| proposed | draft, open, review, rfc |
+| accepted | approved, agreed, adopted, active |
+| implemented | done, shipped |
+| rejected | declined, withdrawn |
+| deprecated | retired, obsolete |
+| superseded | replaced |
+
+Accepted and implemented count as **current**. A record with no status line is `unknown`, and an
+unknown word is `unrecognised`.
+
+## Checks
+
+| Severity | Finding | The fix |
+|---|---|---|
+| problem | A record another record supersedes is still marked accepted, proposed or with no status | Set its Status to `Superseded by <id>` |
+| problem | A record is superseded by an id that doesn't exist | Correct the id, or write the missing record |
+| problem | A current record names a path that is gone, with no close-named sibling | Deprecate the record if the decision died, or find where the code went |
+| warning | A current record names a path that has moved or been renamed | Update the path in the record |
+| warning | A guide or README outside the record folders cites a superseded record | Update the guide: it may still teach the old decision |
+| problem | Two records share an id | Renumber one, and fix the references to it |
+| problem | A supersession cycle | Break it: one record must be the current one |
+| warning | "Superseded by X", but X doesn't say it supersedes this record | Add "Supersedes <id>" to X |
+| warning | Marked superseded, but no successor is named | Name it |
+| warning | Supersedes an id that doesn't exist | Correct the id |
+| warning | A reference to an id that doesn't exist | Correct it, or remove it |
+| warning | No status, or a status word it doesn't know | Add or correct the Status line |
+| warning | A current record cites one that has since been superseded | Check the citing decision still holds against the newer one |
+| warning | Two current records govern the same path, and neither supersedes nor amends the other | A person reads both and decides: supersede, amend, or narrow one's scope |
+
+Exit codes:
+- 0: no problems (warnings allowed), or a `--why` or `--record` query was answered;
+- 1: the full check found problems;
+- 2: no records, an unreadable `--root` or `--docs`, or an unknown `--record` id.
+
+A file that isn't UTF-8 is skipped, with a note in the report.
+
+## JSON (`--json`)
+
+```json
+{
+  "root": "/abs/path",
+  "records": [{
+    "id": "ADR-0004", "title": "…", "status": "accepted", "status_text": "Accepted",
+    "date": "2025-03-02", "path": "docs/adr/0004-….md",
+    "supersedes": [], "superseded_by": [], "amends": [], "cites": [], "cited_by": [],
+    "governs": ["services/orders/"], "missing_paths": [], "commits": [],
+    "successors": ["ADR-0009"], "successors_only_claimed_by_successor": ["ADR-0009"],
+    "moved": {"services/kafka-bridge": ["services/bridge"]}
+  }],
+  "docs": [{"path": "docs/onboarding.md", "cites": ["ADR-0004"]}],
+  "findings": [{"severity": "problem", "record": "ADR-0004", "message": "…"}],
+  "notes": [],
+  "query": null
+}
+```
+
+`successors` joins a record's own "superseded by" with every record that says it supersedes this
+one. The second list holds the ones only the newer record records.
+
+## Limits
+
+- **A decision made in a ticket or a chat, and never written down, isn't in the graph.** The
+  answer for that is "no recorded decision".
+- **A path counts as governed only when the record names it.** A decision about "the billing
+  service" that never names its folder governs nothing here. Name the folder in the record.
+- **Ids are recognised as `ADR`, `RFC`, `DR` or `DD`, plus a number.** Other schemes are read from
+  the filename only.