@skill-graph/cli 0.5.6

package/marketplace/skills/context-management/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: context-management
+description: "Use when deciding what to load into an active agent session, recovering from context drift, preparing compaction or restart, distilling raw inputs into a working summary, or writing a handoff another agent can resume quickly. Covers intake triage, the six-step context-management loop, working-set shaping, evidence-first loading, drift signals, anti-drift rules, compaction-ready handoffs, and selective rebuild after context loss. Do NOT use for token math (use `context-window`), prompt wording (use `prompt-craft`), persistent memory curation, or multi-graph context architecture (use `context-graph`)."
+license: MIT
+compatibility: Runtime-agnostic. The intake-triage / loop / drift / handoff discipline applies to any LLM-coding harness regardless of context window size or compaction implementation.
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/context\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"context management\\\\\\\",\\\\\\\"working set discipline\\\\\\\",\\\\\\\"intake triage four buckets\\\\\\\",\\\\\\\"context drift recovery\\\\\\\",\\\\\\\"context management loop\\\\\\\",\\\\\\\"compaction-ready handoff\\\\\\\",\\\\\\\"distill raw inputs\\\\\\\",\\\\\\\"one active hypothesis\\\\\\\",\\\\\\\"selective context rebuild\\\\\\\",\\\\\\\"lost-thread recovery\\\\\\\",\\\\\\\"active question one sentence\\\\\\\",\\\\\\\"prove or disprove minimum evidence\\\\\\\",\\\\\\\"collapse confirmed facts\\\\\\\",\\\\\\\"drop disproven assumptions\\\\\\\",\\\\\\\"working set shaping\\\\\\\",\\\\\\\"distillation pattern\\\\\\\",\\\\\\\"anti-drift rules\\\\\\\",\\\\\\\"handoff in 30 seconds\\\\\\\"]\",\"examples\":\"[\\\\\\\"the session feels noisy and I'm re-reading the same files — what discipline pulls it back?\\\\\\\",\\\\\\\"the agent keeps citing assumptions that were already disproven — how do I clear them out?\\\\\\\",\\\\\\\"I'm about to compact — what do I need to preserve so the next session resumes correctly?\\\\\\\",\\\\\\\"the thread is lost; what's the recipe for rebuilding only what's needed instead of warming up everything?\\\\\\\",\\\\\\\"I have a 300-line error log and a 600-line component file in context — how do I distill them?\\\\\\\",\\\\\\\"the active question changed three times this session — how do I prevent the old context from steering the new one?\\\\\\\",\\\\\\\"this conversation has 40K tokens of evidence; what should the working set actually contain?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"calculate the per-zone token budget for the 200K context window\\\\\\\",\\\\\\\"improve this prompt template for the grader\\\\\\\",\\\\\\\"curate the persistent memory index file\\\\\\\",\\\\\\\"design the multi-graph architecture for skills + docs + memory\\\\\\\",\\\\\\\"review this AI-generated PR for correctness\\\\\\\",\\\\\\\"why is this skill not routing — fix the keyword config\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"context-graph\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"context-graph maps the static topology — what skills, docs, memory, scripts exist and how they connect; context-management is the live working-set discipline inside one running session\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"prompt-craft\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"prompt-craft is wording and structure of one prompt; context-management is the discipline of what enters, stays in, and exits the session around any prompt\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"context-engineering\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"context-engineering is the system-level design (injector quality, failure metrics); context-management is the per-session operating discipline within that system\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"tool-call-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"tool-call-strategy decides which tool to call next for the agent's job; context-management decides what context that decision should be made against\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"context-engineering\\\\\\\",\\\\\\\"context-graph\\\\\\\",\\\\\\\"tool-call-strategy\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"context-engineering\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/context-management/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1322\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/context-management/SKILL.md
+---
+
+# Context Management
+
+## Coverage
+
+The working discipline that controls what enters, stays in, and exits an active agent session. Intake triage that sorts every candidate context source into a four-bucket classification (must-have / useful soon / durable background / noise) before any large file is read. The six-step context-management loop: state the active question in one sentence, name the minimum evidence needed to answer it, load the cheapest sources first (index → search → narrow file slice), collapse confirmed facts into a checkpoint, drop disproven assumptions from the active thread, re-check whether the question changed before reading more. Working-set shaping rules — what to keep active vs what to push out — and the distillation pattern that converts a 300-line log into a 2-line summary, a whole file into a function name plus slice plus invariant, a long conversation into current-state-blocker-next-step. Drift detection signals (re-reading the same file, ideas changing every turn, search-space unbounded, the agent forgetting what was proven) and the anti-drift rules (one active hypothesis at a time, one primary question, one verification target). The compaction-ready handoff format with five required fields (task / question / proven facts / rejected paths / next step) and the under-thirty-seconds resume test. The selective-rebuild recipe for recovering after the thread is lost.
+
+## Philosophy
+
+Context management is the practical layer between _having_ the right information available somewhere in the workspace and _having_ it active in the agent at the right moment. The goal is _not_ to load more context — it is to keep the smallest working set that still lets the agent act correctly. Without this discipline, agents speculate from stale assumptions, re-read files they already processed, and lose the decision trail at the moment of compaction. Every context slot occupied by noise is a slot unavailable for the evidence that would actually resolve the current question.
+
+The hardest part is not what to load. It is _what to drop_. Disproven hypotheses, raw logs after the key pattern is extracted, full files after the needed lines are identified, alternative hypotheses that have already been falsified — all of these continue to occupy context until they are _deliberately_ removed. The working set is what the agent is actively reasoning over, not everything it has ever seen.
+
+## 1. Outcomes
+
+| Job         | What success looks like                           | Common failure                                      |
+| ----------- | ------------------------------------------------- | --------------------------------------------------- |
+| Intake      | Only task-critical context is loaded first        | Reading five files before the problem is even named |
+| Working set | The active context matches the _current_ question | Old assumptions keep steering new work              |
+| Handoff     | Another session can resume cleanly                | Compaction loses the decision trail                 |
+| Recovery    | The agent can rebuild the thread quickly          | Re-reading everything from scratch                  |
+
+## 2. The Context-Management Loop
+
+Use this loop whenever a task starts to sprawl or the session feels noisy:
+
+1. **Define the active question** in one sentence.
+2. **Name the minimum evidence** that would answer it — both the _prove_ set and the _disprove_ set.
+3. **Load the cheapest sources first**: index, search result, narrow file slice. Avoid full-file reads until evidence demands the rest of the file.
+4. **Collapse confirmed facts** into a short checkpoint that the agent can re-read at any later turn.
+5. **Drop stale or disproven assumptions** from the active thread — disprove ≠ delete-from-history, but delete-from-active-context.
+6. **Re-check whether the active question changed** before reading more. If yes, restart the loop. Do not drag old context along.
+
+The loop is recursive — every "load more" decision restarts it. The goal is not to never read; it is to read _only when evidence demands it_.
+
+## 3. Intake Triage — Four Buckets
+
+Before reading anything large, sort every candidate context source into one of four buckets:
+
+| Bucket                 | Load now? | Examples                                                                 | Rule                                                               |
+| ---------------------- | --------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| **Must-have**          | Yes       | The user-named file, the failing route, the owning skill                 | Read first                                                         |
+| **Useful soon**        | Maybe     | Neighbouring docs, related tests, adjacent skill files                   | Load only after the active question is stable                      |
+| **Durable background** | Rarely    | Broad architecture overview, long design guide, full module README       | Use the index first; slice narrowly only if the index points there |
+| **Noise**              | No        | Adjacent-but-unneeded files, unrelated generated output, one-off scripts | Ignore unless evidence later points there                          |
+
+### Intake rules
+
+- Start from the user's _concrete_ artefact (file, error, ticket) before loading background.
+- Prefer an _owning_ doc over a broad repo-wide reference.
+- Prefer a _search result_ over a full-file read.
+- Prefer _one decisive file slice_ over three speculative reads.
+- If you cannot explain — out loud, in one sentence — _why_ a source is being loaded, do not load it.
+
+## 4. Working-Set Shaping
+
+The working set is what the agent is _actively reasoning over_ — not everything it has ever seen.
+
+### Keep these in the working set
+
+- The current problem statement
+- The current hypothesis
+- The smallest evidence set that can _prove or disprove_ it
+- The next verification step
+
+### Push these out of the working set
+
+- Raw logs after the key pattern is extracted
+- Full files after the needed lines are identified
+- Alternative hypotheses that have already been disproven
+- Background docs once their actionable rule has been distilled
+
+### Distillation pattern
+
+| Raw input                | Keep in active context instead                        |
+| ------------------------ | ----------------------------------------------------- |
+| 300-line error log       | 2-line summary of the repeating error and its trigger |
+| Whole component file     | Function name + line slice + one key invariant        |
+| Large skill body         | The one rule that changes the current decision        |
+| Long conversation thread | Current state, blocker, next step                     |
+| Multi-page doc           | The single section that answers the active question   |
+
+The distillation is the _artefact_ — write it down, paste it into the active context, then drop the raw input. Distillation that lives only in the agent's "memory" is fragile; distillation written into the conversation is durable.
+
+## 5. Drift Detection
+
+Context drift means the session is no longer solving the same problem it started with, _or_ is still reasoning from assumptions that have already been falsified.
+
+| Drift signal                                              | What it usually means                        | Response                                                             |
+| --------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------- |
+| Re-reading the same file repeatedly                       | The active question is vague                 | Rewrite the question and search narrower                             |
+| Fix ideas change every turn                               | No anchored hypothesis                       | Stop implementing; restate the evidence; pick one hypothesis to test |
+| New files keep getting pulled in                          | Search space is unbounded                    | Identify the _first failing boundary_ and stay there                 |
+| The agent forgets what was already proven                 | Facts were never collapsed into a checkpoint | Write the checkpoint _before_ continuing                             |
+| The agent restates earlier conclusions in different words | Active context is too large to scan          | Distil and drop the original sources                                 |
+
+### Anti-drift rules
+
+- **One active hypothesis** at a time.
+- **One primary question** at a time.
+- **One verification target** at a time.
+- When evidence contradicts the plan, _update the checkpoint_ before moving on. Do not silently abandon the contradicted hypothesis.
+
+## 6. Compaction-Ready Handoffs
+
+This skill does not own token math or compaction triggers. It owns _handoff quality_ — the artefact a successor agent reads when the current session compacts, restarts, or hands over.
+
+Before any compaction, restart, or handover, preserve five fields:
+
+1. **The active task** (identifier, link, or short description)
+2. **The current question** (one sentence)
+3. **The strongest supported hypothesis** (and the evidence supporting it)
+4. **The evidence already verified** (proven facts the next session should not re-prove)
+5. **The next concrete step** (the action a successor would take if they had no other context)
+
+### Good handoff format
+
+| Field          | Example                                                                                                         |
+| -------------- | --------------------------------------------------------------------------------------------------------------- |
+| Task           | `ABC-123` (a single task ID or link)                                                                            |
+| Question       | "Why does the settings save path ignore org scope?"                                                             |
+| Proven facts   | "The route uses an unscoped query helper, not the org-scoped one; failure reproduces only for non-owner roles." |
+| Rejected paths | "Not a session bug — auth claims are correct."                                                                  |
+| Next step      | "Patch the org-scoped update path; rerun the failing request."                                                  |
+
+If the handoff cannot tell another agent _where to start_ in under thirty seconds of reading, it is incomplete. Optimise for the _cold start_, not for the agent that already has full context.
+
+## 7. Recovery After Lost Context
+
+When the thread is lost — after compaction, after a session restart, after a long context-switching gap — rebuild _selectively_, in this order:
+
+1. **Re-read the user request** (the canonical task statement, not your own paraphrase).
+2. **Re-read the last checkpoint** (or continuation artefact, or the most recent agent-written summary).
+3. **Re-open only the files that directly support the current question** — not "everything that might be relevant."
+4. **Reconstruct the current hypothesis from evidence**, not from memory of what you used to think.
+5. **Resume from the next unverified step.**
+
+Do not "warm up" by re-reading everything. Recovery is a _selective_ rebuild, not a context flood. Loading 30 files to "get back into the task" recreates the original drift on a fresh canvas.
+
+## Verification
+
+- [ ] I can state the active question in one sentence
+- [ ] I know — and could explain — why each currently loaded source is in context
+- [ ] I have reduced raw inputs into a smaller written working summary that lives in the conversation, not in the agent's memory
+- [ ] I have removed or ignored disproven hypotheses from the active thread
+- [ ] I have a handoff-ready checkpoint with all five required fields before any compaction or session restart
+- [ ] I am loading new context because _evidence demands it_, not because I feel uncertain
+- [ ] One active hypothesis, one primary question, one verification target — no exceptions
+- [ ] A successor agent could resume from my checkpoint in under thirty seconds
+
+## Do NOT Use When
+
+| Use instead                        | When                                                                                                                                       |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| A context-window budget skill      | Calculating per-zone token budgets, compaction thresholds, or 1M-vs-200K decisions                                                         |
+| `prompt-craft`                     | Writing or improving a prompt template — wording, structure, format constraints                                                            |
+| A persistent-memory curation skill | Curating cross-session memory files, pruning the memory index, deciding what _survives_ a session                                          |
+| `context-graph`                    | Designing the architectural model for the multi-graph context system itself                                                                |
+| `context-engineering`              | Designing the system-level information architecture, injector quality, and failure metrics — context-engineering is upstream of this skill |
+| `code-review`                      | Reviewing AI-generated code — orthogonal concern                                                                                           |
+| `tool-call-strategy`               | The dispatch decision (which tool to call next) — context-management is the _input_ to that decision, not the decision itself              |

package/marketplace/skills/context-window/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: context-window
+description: "Use when allocating context-window budget across system, skill-injection, working, and output zones; monitoring context health; deciding when to compact; preserving state before compaction; recovering after compaction; or choosing strategies for 1M, 200K, or 128K context windows. Covers zone budgets, practical model-budget tables, the 80% compaction rule, pre/post-compact protocols, persistence hierarchy, operation token costs, and token-reduction techniques. Do NOT use for deciding what information belongs in the working set (use `context-management`), prompt design (use `prompt-craft`), graph architecture (use `context-graph`), or memory curation."
+license: MIT
+compatibility: "Provider-agnostic. The zone model, 80% rule, persistence hierarchy, and token-reduction techniques apply across Anthropic, OpenAI, Google, and open-weight contexts of any size. Specific token figures are illustrative — substitute the figures of the model you actually run."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"agent\",\"domain\":\"agent/context\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"context window management\\\\\\\",\\\\\\\"context budget allocation\\\\\\\",\\\\\\\"80% compaction rule\\\\\\\",\\\\\\\"context health states\\\\\\\",\\\\\\\"pre-compact hook\\\\\\\",\\\\\\\"post-compact recovery\\\\\\\",\\\\\\\"cross-session persistence hierarchy\\\\\\\",\\\\\\\"token consumption per operation\\\\\\\",\\\\\\\"deterministic cli vs mcp tool result tokens\\\\\\\",\\\\\\\"targeted file read offset limit\\\\\\\",\\\\\\\"progressive skill disclosure\\\\\\\",\\\\\\\"grep before reading files\\\\\\\",\\\\\\\"1M context window strategy\\\\\\\",\\\\\\\"200K context window strategy\\\\\\\",\\\\\\\"128K context window strategy\\\\\\\",\\\\\\\"checkpoint before compact\\\\\\\",\\\\\\\"continuation signal\\\\\\\",\\\\\\\"what survives compaction\\\\\\\"]\",\"examples\":\"[\\\\\\\"the agent's tool results are starting to truncate — what state are we in and what should I do next?\\\\\\\",\\\\\\\"I have a 1M-context model — does that mean I can ignore budget management?\\\\\\\",\\\\\\\"the session is at 75% context — should I compact now or finish the current operation first?\\\\\\\",\\\\\\\"I just compacted and lost the decision trail; what should the pre-compact hook have preserved?\\\\\\\",\\\\\\\"the agent reads 5 files looking for a function and burns 100K tokens — what's the right pattern?\\\\\\\",\\\\\\\"I'm running on a 128K-context model — what's the per-task budget I can plan against?\\\\\\\",\\\\\\\"what survives compaction and what doesn't, ranked from most to least durable?\\\\\\\",\\\\\\\"the skill payload is 30K and I haven't even read a file yet — how do I shrink it?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"decide what context to load or drop in the working set\\\\\\\",\\\\\\\"design the multi-graph architecture for skills + docs + memory\\\\\\\",\\\\\\\"improve the prompt template the agent uses\\\\\\\",\\\\\\\"curate the durable memory index across sessions\\\\\\\",\\\\\\\"which skill should activate for this query\\\\\\\",\\\\\\\"review this AI-generated PR for correctness\\\\\\\",\\\\\\\"the README has drifted from the actual CLI flags — which wins?\\\\\\\",\\\\\\\"the docs have drifted from the code — which is canonical?\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"context-management\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"context-management decides what to load and drop in the working set; context-window is the budget math underneath that decides how much fits and when to compact\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"context-graph\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"context-graph maps the static topology of skills / docs / memory; context-window is the runtime budget for the part of that topology that is actually loaded\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"tool-call-strategy\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"tool-call-strategy decides which tool to invoke; context-window decides how much budget the result of that tool is allowed to occupy\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"prompt-craft\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"prompt-craft is wording / structure of one prompt; context-window is the per-session budget the prompt and its results live within\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"context-management\\\\\\\",\\\\\\\"context-graph\\\\\\\",\\\\\\\"tool-call-strategy\\\\\\\",\\\\\\\"context-engineering\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"context-management\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":180,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/context-window/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1352\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/context-window/SKILL.md
+---
+
+# Context Window
+
+## Coverage
+
+The quantitative discipline behind an agent's working memory. Allocates the context-window budget across three zones: System (system prompt, rules, tool schemas), Skill Injection (the SKILL.md files auto-loaded for the current task), and Working (conversation, tool results, file contents, agent output). Names the three context health states — `ok` (< 60% used), `compact` (60–80%), `exhausted` (> 80%) — and the **80% compaction rule** that compaction must always trigger before the budget is fully consumed, leaving 20% as the safety margin for finishing the current operation, writing the checkpoint, running the closeout protocol, and emitting the continuation signal. Specifies the pre-compact protocol (commit uncommitted changes, write the continuation signal, update the checkpoint, save state that cannot be re-derived from git or disk) and the post-compact recovery flow (re-injection of git status, active-task reference, recent commits, critical findings). Catalogs typical token consumption per operation type (full file read 20–40K, large tool-result JSON 10–30K, single SKILL injection 3–8K, fixed system overhead) and the five token-reduction techniques: deterministic-CLI over heavy MCP / tool-result paths, targeted file reads with `offset` + `limit` instead of full-file reads, search-before-read (grep first, read the match), progressive skill disclosure (small SKILL.md kept always loaded; large reference files loaded on demand), and count-mode for exploration (count matches, then read the few that matter). Specifies the cross-session persistence hierarchy — git history > files on disk > durable memory > live context — and uses it to decide _what to checkpoint_ before compaction. Lists per-model-class context strategies for 1M, 200K, and 128K windows.
+
+## Philosophy
+
+The context window is the agent's _working memory_. Unlike human memory, it has a hard ceiling — when it fills, information is permanently lost from the live session unless it has been checkpointed somewhere durable. Managing the window is not optional. It is the difference between completing a long task and crashing mid-work with the most recent reasoning gone.
+
+The trap of large windows is the assumption that they are _effectively_ unlimited. A 1M-token window feels infinite until a single 2000-line file read consumes 30K, three of those plus a long tool-result chain pushes past 200K, and the agent is at 60% before any real implementation has happened. The ceiling is real, and it is closer than the headline number suggests. Discipline at 200K is identical to discipline at 1M; only the absolute numbers move.
+
+The 80% rule exists because compaction is _itself_ an operation that needs budget. Hitting 100% mid-operation loses the operation. Compacting at 80% preserves it — the remaining 20% pays for the act of preserving.
+
+## Zone Model
+
+A useful per-session mental partition of the available budget:
+
+| Zone                | Typical share | What lives here                                                          |
+| ------------------- | ------------- | ------------------------------------------------------------------------ |
+| **System**          | ~5–10%        | System prompt, repo rules, tool schemas, always-loaded directives        |
+| **Skill injection** | ~2–5%         | The SKILL.md files auto-loaded by the routing layer for the current task |
+| **Working**         | ~85–93%       | Conversation, tool results, file contents, agent output                  |
+
+The exact share varies by model, harness, and task type. The zones are useful because budget breaches show up in different places: a System overrun is a rules / tool-schema problem, a Skill overrun is a routing / over-injection problem, a Working overrun is a context-management / file-read problem. Each has a different remediation.
+
+### Practical budget by model class
+
+Replace these illustrative figures with the actual figures of your runtime — they shift over time and across vendors.
+
+| Model class                                                  | Total context | Typical system overhead | Practical working budget |
+| ------------------------------------------------------------ | ------------- | ----------------------- | ------------------------ |
+| Frontier 1M-context (Anthropic Opus / Sonnet 1M tier)        | ~1,000,000    | ~70K                    | ~930K                    |
+| Frontier 200K-context (default tier of most frontier models) | ~200,000      | ~70K                    | ~130K                    |
+| Long-context Haiku class                                     | ~200,000      | ~50K                    | ~150K                    |
+| ~128K class (some OpenAI / open-weight)                      | ~128,000      | ~20K                    | ~108K                    |
+
+## Context Health States
+
+| State       | Used budget | Meaning          | Action                                           |
+| ----------- | ----------- | ---------------- | ------------------------------------------------ |
+| `ok`        | < 60%       | Normal operation | Continue working                                 |
+| `compact`   | 60–80%      | Getting crowded  | Plan compaction at the next logical boundary     |
+| `exhausted` | > 80%       | Critical         | Stop after the current item, compact immediately |
+
+### The 80% rule
+
+**Always compact at 80% of the working budget — never at 100%.** The remaining 20% is the safety margin for:
+
+- Completing the operation currently in flight
+- Writing the checkpoint state
+- Running whatever session-closeout / wrap protocol the runtime ships
+- Emitting the continuation signal so the next session can resume
+
+Hitting 100% mid-operation loses work. Compacting at 80% preserves it.
+
+## Compaction Protocol
+
+### When to compact
+
+1. Context health reaches `compact` or `exhausted`
+2. After completing a logical unit of work (one task, one file, one audit item)
+3. Before starting a large new operation that will read many files
+4. When tool results begin to truncate (a leading indicator of context pressure)
+
+### Pre-compact checklist
+
+Before triggering compaction:
+
+1. **Commit any uncommitted changes** — git work survives compaction; live context does not.
+2. **Write the continuation signal** — the next-session contract: active task, current question, remaining work.
+3. **Update any loop or task checkpoint** — advance the recorded phase to the actual phase.
+4. **Save critical state** — anything that cannot be re-derived from git history or files on disk goes into a durable artefact now.
+
+### Pre-compact hook
+
+A pre-compact hook is the deterministic enforcer of the checklist. The hook captures, at minimum:
+
+- The active task identifier and the current question
+- The agent mode / phase
+- The current git branch and the most recent commit hashes
+- The current context-health state
+- A small bag of custom state (whatever the runtime needs to resume)
+
+Any runtime that supports compaction without a pre-compact hook is _one accidental compaction away from losing the decision trail_. The hook is not optional infrastructure for any session that runs more than a few minutes.
+
+### Post-compact recovery
+
+After compaction, the session-start brief should re-inject:
+
+- Git status (branch, recent commits, dirty files)
+- The active task pulled from the continuation signal
+- A short summary of the in-progress board state
+- Any critical findings recorded in the pre-compact checkpoint
+
+The agent does not re-load the lost conversation. It rebuilds _selectively_ from the durable artefacts.
+
+## Token Consumption Patterns
+
+### What consumes the most context
+
+| Operation                           | Typical tokens | Impact     |
+| ----------------------------------- | -------------- | ---------- |
+| Full file read (2000 lines)         | 20–40K         | High       |
+| Grep results, 50 matches            | 5–10K          | Medium     |
+| Tool result, large JSON             | 10–30K         | High       |
+| Skill injection, one SKILL.md       | 3–8K           | Low–Medium |
+| Agent response, code + explanation  | 2–5K           | Low        |
+| System prompt + always-loaded rules | ~50K (fixed)   | Baseline   |
+
+### Five token-reduction techniques
+
+#### 1. Deterministic CLI over heavy tool-result paths
+
+Where the runtime offers both a heavy tool-result path (e.g., a large MCP-style JSON dump) and a deterministic CLI / scripted path that returns the same data shaped tighter, prefer the CLI. The savings can easily be 50–100× per call. The principle: ship structured output through tools the model can read efficiently, not through whatever path the runtime happens to expose by default.
+
+#### 2. Targeted file reads (offset + limit)
+
+```
+BAD:  read the whole 2000-line file
+      → 30K tokens
+GOOD: read 30 lines starting at the function you actually need
+      → 500 tokens
+```
+
+If a code-search step has already located the relevant lines, _use_ those line numbers. A "read everything because I might need it" pattern is the single biggest avoidable burn.
+
+#### 3. Search before read
+
+```
+BAD:  read 5 candidate files looking for a function
+      → 100K tokens
+GOOD: grep for the function name first, then read 30 lines from the one match
+      → 2K tokens
+```
+
+The search step costs ~1K tokens and replaces 50–100K of speculative reading.
+
+#### 4. Progressive skill disclosure
+
+Skills should follow a two-tier structure:
+
+- **`SKILL.md`** — the core patterns, the routing-contract description, the verification checklist. Always loaded when the skill is selected. Should fit comfortably in 3–8K tokens.
+- **`references/*.md`** — detailed reference material, long examples, deep specifications. Loaded _only_ when explicitly needed.
+
+Only `SKILL.md` is auto-injected. References are loaded by the agent when the task demands the depth.
+
+#### 5. Count mode for exploration
+
+```
+BAD:  list every TODO comment in the repo, full match content
+      → 50K tokens
+GOOD: count first, then read selectively
+      grep --count "TODO"                                  → 200 tokens
+      grep "TODO" path: src/lib/ --head 10                 → 2K tokens
+```
+
+Exploration should be a _count → narrow → read_ sequence, not a single exhaustive read.
+
+## Cross-Session Persistence Hierarchy
+
+What survives a compaction or session restart, ranked from most to least durable:
+
+1. **Git** — code, commits, branches. Permanent.
+2. **Files on disk** — checkpoints, continuation signals, structured logs (JSONL is ideal). Persistent until manually deleted.
+3. **Durable memory** — index files and topic files in a memory directory consumed by the next session. Persistent and indexed.
+4. **Live context** — conversation history, in-flight reasoning, tool results. **Lost on compaction.**
+
+The hierarchy drives the pre-compact checklist: anything that lives only at level 4 needs to be promoted to levels 1–3 _before_ compaction, or it is gone.
+
+### Planning for compaction
+
+When starting a complex multi-step task:
+
+1. Break it into subtasks each of which can complete inside one context window
+2. After each subtask: commit + update checkpoint + write continuation signal
+3. If a subtask risks exceeding the budget mid-flight, split further or read fewer files
+
+The rhythm is: small unit → commit → checkpoint → next unit. Compaction becomes a routine boundary instead of a crisis.
+
+## Per-Model-Class Strategies
+
+| Model class                                 | Typical task sizing                                     | Compaction cadence      | Key disciplines                                                         |
+| ------------------------------------------- | ------------------------------------------------------- | ----------------------- | ----------------------------------------------------------------------- |
+| 1M context (frontier Opus / Sonnet 1M tier) | 5–10 file reads + full implementation per session       | After 3–4 complex tasks | Progressive skill disclosure; targeted reads still required             |
+| 200K context (default frontier tier)        | 2–4 file reads + one focused implementation per session | After every 2 tasks     | Aggressive search-before-read; skill targeting; offset+limit reads      |
+| Long-context Haiku class                    | 2–3 file reads per task                                 | After every task        | Minimise skill payload; targeted labels only; commit between tasks      |
+| ~128K class                                 | 1 task per session                                      | Hard boundary           | Count-mode first; read only essentials; one verification step at a time |
+
+A 1M window is not a license to ignore the rules — it just shifts the breaking point further out. Apply the same discipline; the budget math just lets you run longer between compactions.
+
+## Anti-Patterns
+
+| Anti-pattern                                             | Why it fails                                                               | Correct                                                                            |
+| -------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Reading entire large files when 30 lines would do        | Burns 20–40K per file with no benefit                                      | Use `offset` + `limit`                                                             |
+| Loading every available skill regardless of task         | Skill injection should be 2–5%, not 25%                                    | Use targeted routing labels; trust the routing layer                               |
+| Ignoring the `compact` health signal                     | Skipping past 80% guarantees a 100% loss event sooner or later             | Compact at the next logical boundary once `compact` triggers                       |
+| Compacting without a pre-compact checkpoint              | The decision trail is lost; the next session re-derives wrong              | Always run the pre-compact checklist; keep the hook always-on                      |
+| Letting tool results dump unstructured JSON into context | A 30K tool result evicts 30K of useful conversation                        | Wrap heavy results in a CLI / script that returns the shape you need               |
+| Speculative reads ("I might need this")                  | Speculation has the same cost as evidence-based reads, with worse outcomes | Read on evidence; if you cannot name _what you'll do with the file_, don't read it |
+| Treating the 1M window as effectively unlimited          | A complex task crosses 60% in minutes; the ceiling is real                 | Apply the same discipline at 1M as at 200K; the budget just stretches              |
+
+## Verification
+
+- [ ] The current context-health state has been correctly classified as `ok`, `compact`, or `exhausted` based on actual usage estimates
+- [ ] The pre-compact checklist has been followed before any compaction (commit, continuation signal, checkpoint, custom state)
+- [ ] A pre-compact hook is installed and runs deterministically — compaction is never invoked without it firing
+- [ ] File reads use `offset` + `limit` targeting for any file beyond ~200 lines
+- [ ] The session prefers deterministic CLI / scripted tool paths over heavy MCP-style result dumps where both exist
+- [ ] No compaction has been triggered at 100% — the 80% rule has been respected
+- [ ] What needs to survive the session has been promoted from live context to git / files / durable memory before any compaction
+- [ ] The active model's actual context budget (not assumed budget) is the planning baseline
+
+## Do NOT Use When
+
+| Use instead             | When                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `context-management`    | Deciding _what_ to load, keep, or drop from the working set — the qualitative side of context health                                 |
+| `context-graph`         | Designing the multi-graph architecture (skills + docs + memory + scripts) — the topology, not the runtime budget                     |
+| `prompt-craft`          | Writing or improving a prompt — wording, structure, format constraints                                                               |
+| A memory-curation skill | Curating cross-session persistent memory files, pruning the memory index                                                             |
+| `tool-call-strategy`    | Choosing which tool to call next — context-window decides the _budget_ for the call's result, not whether the call is the right call |
+| `code-review`           | Reviewing AI-generated code — orthogonal concern                                                                                     |
+| `context-engineering`   | Designing the system-level information architecture — context-engineering is upstream of this skill                                  |

package/marketplace/skills/contract-testing/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: contract-testing
+description: "Use when verifying the interface between two services or components by capturing the consumer's expectations as a contract artifact and verifying the provider satisfies it. Covers the consumer-driven contracts pattern (Fowler 2006; Pact), the contrast with schema-only validation (OpenAPI/JSON Schema captures shape, not behavioral expectations), the broker as the integration point between consumer and provider deploy schedules, two-phase verification (consumer-side mocks; provider-side replay), the difference between contract testing (verifies the interface) and integration testing (verifies the implementation through it), and how contract tests replace brittle cross-service e2e. Do NOT use for in-system integration (use `integration-test-design`), full user-journey testing (use `e2e-test-design`), single-unit testing (use `testing-strategy` + `test-doubles-design`), or pure OpenAPI schema validation (API-spec tooling)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/testing\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"contract testing\\\\\\\",\\\\\\\"consumer-driven contracts\\\\\\\",\\\\\\\"Pact\\\\\\\",\\\\\\\"Spring Cloud Contract\\\\\\\",\\\\\\\"Specmatic\\\\\\\",\\\\\\\"contract broker\\\\\\\",\\\\\\\"provider verification\\\\\\\",\\\\\\\"consumer test\\\\\\\",\\\\\\\"CDC\\\\\\\",\\\\\\\"OpenAPI conformance\\\\\\\"]\",\"triggers\":\"[\\\\\\\"should this be a contract test or an integration test\\\\\\\",\\\\\\\"Pact vs OpenAPI\\\\\\\",\\\\\\\"how do we decouple deploys between services\\\\\\\",\\\\\\\"the consumer broke when the provider changed\\\\\\\",\\\\\\\"should we e2e test across services\\\\\\\"]\",\"examples\":\"[\\\\\\\"design a consumer-driven contract test between a frontend and a backend service\\\\\\\",\\\\\\\"decide whether to use Pact or schema-only validation for a new API\\\\\\\",\\\\\\\"diagnose a contract test that passes consumer-side but fails provider-side — implementation drift\\\\\\\",\\\\\\\"explain how the contract broker decouples deploy schedules between consumer and provider teams\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"test internal seams of a system (use integration-test-design)\\\\\\\",\\\\\\\"validate an HTTP response against an OpenAPI schema (use API-spec tooling)\\\\\\\",\\\\\\\"test a complete user journey through the UI (use e2e-test-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"testing-strategy\\\\\\\",\\\\\\\"integration-test-design\\\\\\\",\\\\\\\"e2e-test-design\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"system-interface-contracts\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"integration-test-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"integration-test-design owns tests that exercise the real implementation through an interface; this skill owns tests that verify the interface contract independently of the implementation behind it. Contract tests can replace cross-service e2e tests; they cannot replace integration tests that verify behavior through the interface.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"e2e-test-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"e2e-test-design owns user-journey tests across the whole stack; this skill owns service-boundary contract verification. Cross-service e2e tests are often the wrong tool — they are slow and verify too much; contract tests verify the interface specifically.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the design of the request/response surface; this skill owns the testing of whether the implementation meets that design's contract. The two compose: api-design produces the contract; contract testing verifies it.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"system-interface-contracts\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"system-interface-contracts owns the design and documentation of contracts between systems, modules, and services; this skill owns the testing of those contracts. system-interface-contracts is the design discipline; this skill is the verification technique.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"event-contract-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"event-contract-design owns the design of asynchronous event contracts; this skill applies to verifying message-bus contracts (Pact supports asynchronous message contracts). The two compose for event-driven systems.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"api-design\\\\\\\",\\\\\\\"integration-test-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"A contract test is to a service interface what a lease is to a tenancy — the consumer writes down the specific obligations they depend on (utilities included, quiet hours, this exact rent), the landlord (provider) verifies independently that they can honor those obligations, and the lease in the broker's filing cabinet lets either party prove compatibility without re-negotiating from scratch each time one of them moves.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Contract testing is the technique of verifying that an interface between a consumer and a provider — typically two services across a network boundary — works as both sides expect, by capturing the consumer's expectations as a *contract* artifact and then running that contract against both sides independently. The contract is consumer-driven: it expresses the specific interactions the consumer actually performs (this HTTP request → this response shape and content), not the full surface of the provider's API. The consumer side verifies its code by replaying the contract against a generated mock provider; the provider side verifies its implementation by replaying the contract against the real provider. When both verifications pass independently, the two sides are known to be compatible without ever running them together. The technique decouples deploy schedules between consumer and provider teams and replaces brittle cross-service end-to-end tests with focused interface verification.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/contract-testing/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1176\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/contract-testing/SKILL.md
+---
+
+# Contract Testing
+
+## Coverage
+
+The technique of verifying interfaces between consumer and provider components by capturing the consumer's expectations as a contract artifact and running that contract against both sides independently. Covers the consumer-driven contracts pattern (Fowler 2006; Pact ecosystem), the two-phase verification (consumer-side mock generation; provider-side replay), the broker as the integration point that enables deploy independence and compatibility tracking, the contrast with schema-only validation (OpenAPI captures surface; contracts capture behavior), the contrast with integration and e2e testing (contracts verify the interface; integration and e2e verify implementation and journeys), and the tool ecosystem (Pact, Spring Cloud Contract, Specmatic, bi-directional patterns).
+
+## Philosophy
+
+Contract testing decouples deploy schedules between services. Before contract testing, two services that depended on each other had to be tested together — usually with brittle cross-service e2e tests in a shared staging environment, which serialized deploys and produced flaky signal. With contract testing, each side is verified independently against a shared contract; deploys can happen on independent schedules as long as the contract is satisfied.
+
+The contract is *consumer-driven*: it captures what the consumer actually does, not what the provider offers. This narrowing — three endpoints out of fifty, twelve fields out of a hundred — is what makes contract testing focused and what distinguishes it from full schema validation. The provider can change anything the consumers don't rely on; the provider cannot break anything any consumer's contract requires.
+
+The discipline is in the broker. A contract-test setup without a broker is "contracts as committed fixtures" — much of the maintenance cost, little of the deploy-independence benefit. A contract-test setup with a broker (Pact Broker, PactFlow) provides versioned contract storage, compatibility tracking, and deploy-gating; the strategic value of the technique is realized at this layer.
+
+## The Two-Phase Verification
+
+```
+┌─────────────────────────┐         ┌─────────────────────────┐
+│   Consumer's CI         │         │   Provider's CI         │
+│                         │         │                         │
+│ 1. Run consumer tests   │         │ 4. Fetch contracts      │
+│    against generated    │         │    from broker          │
+│    mock provider        │         │                         │
+│                         │         │ 5. Replay each contract │
+│ 2. If pass: contract    │         │    against real         │
+│    is correct           │         │    provider             │
+│                         │         │                         │
+│ 3. Publish contract     │         │ 6. If pass: provider    │
+│    to broker            │ ──────▶ │    satisfies contract   │
+│                         │         │                         │
+│                         │ ◀────── │ 7. Mark contract version│
+│                         │  broker │    as verified          │
+└─────────────────────────┘         └─────────────────────────┘
+```
+
+When both sides have passed independently, the broker records the compatibility. Deploy gating uses this record: don't deploy the provider unless its current version is marked compatible with the production consumer's contract.
+
+## Schema vs Contract — A Practical Comparison
+
+| Property | OpenAPI / JSON Schema | Consumer-driven contract |
+|---|---|---|
+| Captures | Surface (endpoints, types, shapes) | Behavior (specific interactions the consumer performs) |
+| Driven by | Provider | Consumer |
+| Coverage | Everything the provider offers | Only what consumers use |
+| Catches breaking field value change | If schema constrains values; usually not | Yes — the contract has specific values |
+| Catches semantic / error-shape change | No | Yes if consumer relies on the error |
+| Verifies through real implementation | No (validates response against schema only) | Yes (provider runs the contract against itself) |
+| Used for | API description, code generation, validation | Test gate between consumer and provider |
+| Should you have both? | Yes | Yes |
+
+## When Contract Testing Replaces What
+
+| Pre-contract-testing approach | Contract-testing replacement | When replacement is right |
+|---|---|---|
+| Cross-service e2e test for service boundary | Contract test | Almost always — cheaper, more reliable, doesn't require both services running |
+| Schema validation alone | Contract test + schema | Always — schema is necessary but not sufficient |
+| Coordinated deploy schedules | Independent deploys + broker gating | Almost always — the deploy-independence is the strategic value |
+| Manual API change reviews | Contract verification on provider CI | Always — the verification is automated |
+| "We'll catch it in staging" | Contract test on PR | Always — catching at PR time is much cheaper |
+
+## Broker-Enabled Deploy Gating
+
+| State | Can deploy? |
+|---|---|
+| Provider version has been verified against current production consumer contract | Yes |
+| Provider version has not yet been verified against current production consumer contract | No — run verification first |
+| Provider version fails verification against production consumer contract | No — fix or coordinate with consumer |
+| Consumer version's contract has not been verified against current production provider | No — run provider verification |
+
+The broker's compatibility matrix is the deploy gate. Modern setups (PactFlow, Pact Broker `can-i-deploy` API) automate this; the deploy pipeline calls the broker and gets a yes/no answer.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Contracts are *consumer-driven* — written from consumer-side tests against real consumer code, not generated from provider specs.
+- [ ] Contracts and OpenAPI/JSON-Schema coexist; the schema describes surface, the contract verifies behavior. Neither replaces the other.
+- [ ] Both phases of verification run automatically: consumer-side on every consumer PR, provider-side on every provider PR (plus scheduled cron for drift detection).
+- [ ] A broker is in use for any setup with more than 1-2 consumers per provider. The broker provides compatibility tracking and deploy gating.
+- [ ] Deploy gating is wired: provider deploys are blocked if the version isn't verified against the production consumer's contract.
+- [ ] Contract testing is *complementing* integration testing, not replacing it. The team still has integration tests for in-service behavior.
+- [ ] Cross-service e2e tests have been reduced to the most-critical journeys; most cross-service e2e has migrated to contract tests.
+- [ ] Message-bus and event-driven boundaries use contract testing where the consumer-provider pattern applies (Pact supports async message contracts).
+- [ ] Contract evolution is handled: deprecating a field requires checking that no consumer's contract requires it; introducing a new field doesn't break existing contracts.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Testing the implementation behind a service interface | `integration-test-design` | integration tests verify in-service behavior; contracts verify the interface |
+| Testing a user journey across the whole stack including UI | `e2e-test-design` | e2e tests verify the user experience; contracts verify the service boundary |
+| Validating responses against an OpenAPI schema | OpenAPI/JSON-Schema validation tooling | schema validation captures surface; this skill captures behavior |
+| Testing a single unit in isolation | `testing-strategy` + `test-doubles-design` | unit scope is below this skill's level |
+| Designing the API surface itself | `api-design` | api-design owns the contract design; this skill owns the verification |
+| Designing the event surface | `event-contract-design` | event-contract-design owns the asynchronous contract design; this skill verifies it |
+| Choosing the test-level ratio | `testing-strategy` | strategy owns ratios; this skill owns the contract-testing technique |
+
+## Key Sources
+
+- Fowler, M. (2006). ["Consumer-Driven Contracts: A Service Evolution Pattern"](https://martinfowler.com/articles/consumerDrivenContracts.html). The foundational essay defining consumer-driven contracts as a pattern for service evolution.
+- Pact Foundation. ["Pact — Documentation"](https://docs.pact.io). The canonical reference for the most-adopted consumer-driven contract testing tool; multi-language clients; broker ecosystem.
+- PactFlow. ["The Pact Broker"](https://docs.pactflow.io/docs/pact-broker/). Reference for the contract broker pattern, compatibility tracking, and deploy gating.
+- Robinson, I. (2006). ["Consumer-Driven Contracts: Three Levels of Confidence"](https://www.ianrobinson.net/). Practitioner essay on the levels of compatibility consumer-driven contracts provide.
+- Specmatic. ["Specmatic — Bi-directional Contract Testing"](https://specmatic.io/). Reference for the alternative bi-directional approach that compares OpenAPI specs against consumer contracts.
+- Spring Cloud. ["Spring Cloud Contract — Reference Documentation"](https://docs.spring.io/spring-cloud-contract/docs/). The JVM-ecosystem contract testing tool; works with REST and messaging.
+- Newman, S. (2015, 2nd ed. 2021). *Building Microservices*. O'Reilly. Chapter on testing strategies for microservices, with contract testing as the recommended cross-service approach.
+- Richardson, C. (2018). *Microservices Patterns*. Manning. Pattern chapters covering contract testing as part of microservices integration patterns.
+- Cervera, A., et al. (2015). ["Consumer-driven Contracts for Microservices: A Survey"](https://www.researchgate.net/publication/277024057). Academic survey of CDC patterns and tool support.