Use context-graph

Map the decisions behind a codebase from its ADRs, RFCs and design records

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 and the commits that changed each decision's code since it was made, and who made them — 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, code that has drifted from its decision, two current decisions governing the same path, and references to records that don't exist.

Reach for it when the user asks "why do we use X", "which decisions govern this file or service", "is this ADR still current", "has the code drifted since we decided this", "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.

Install it

npx skilldrop-cli install context-graph                 # Claude Code, your user folder
npx skilldrop-cli install context-graph --project       # Claude Code, this repo
npx skilldrop-cli install context-graph --ide cursor    # or kiro, codex, antigravity, copilot

It is part of the Core pack: --pack core installs it with its neighbours.

It ships scripts, so it needs Python 3 (standard library only, nothing to install). What they may touch is declared in its manifest.

Ask for it

Say it the way you would to a colleague. Requests like these route to it:

• "Why do we use Kafka for order events? Is the ADR that chose it still the current decision?"
• "I'm about to refactor services/billing/invoice.py. Which architecture decisions govern it that I should read first?"
• "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"
• "Give me a map of our RFCs and ADRs: what supersedes what, and which folders each one covers, for onboarding the new hires"
• "Is ADR-0012 still true? I think the code it talks about was deleted last year"

Requests like these belong to a different skill, so it shouldn't answer them:

• "We just decided to move our search from Postgres full-text to a hosted search engine. Write the ADR for it in MADR format"
• "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?"
• "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"

If another skill answers instead, ask for this one by name: "use context-graph".

Check what you get

A good result:

• 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".
• Drift is a requirement the code no longer meets, with the record's words, the line, and the commit when the history shows one. A count of commits is a reason to look, never a finding by itself.
• 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.

See a worked example

• order events

Use something else when

• 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

Where a loop runs it

• Stage constrain of the design loop
• Stage record of the design loop
• Stage survey of the modernize loop

Next

• SKILL.md, the instructions the agent reads
• Its page on the site
• Related: adr-generator, codebase-tour, reverse-architecture, decision-log

Edit this page on GitHub · View source