iopsystems/skills-mcp/define-scope

Define scope

You are defining a scope in the knowledge-iop vault. Scopes are the vault's stable reference frames — the named areas the vault cares about for years. A service (billing), a domain (observability), a surface (public-api), a cross-cutting concern (reliability).

Before defining — check you actually want a scope

1. Invoke vault-search with type: scope and keywords from the

proposed name. Check for existing scopes that overlap.

1. Check the four gotchas below; if any applies, redirect:

Scopes should accumulate slowly. If the vault gains a new scope every week, something is miscategorized.

Frontmatter shape

---
id:              <short-slug>                # e.g. "billing", "public-api"
type:            scope
status:          active
established:     <YYYY-MM-DD>
retired:         null
owners:          [<person>, ...]
repos:           [<repo-ref>, ...]           # the grounding hook
services:        [<service-name>, ...]       # optional
upstream_deps:   [<dep>, ...]                # optional; external deps
related_scopes:  [<scope-id>, ...]           # flat — no hierarchy
tags:            [<tag>, ...]
author:          <person>
created:         <YYYY-MM-DD>
---

id: is a plain slug, not dated — scopes don't carry creation dates in their id because they're meant to outlast any given moment. Choose carefully; renaming is expensive.

repos: is the grounding hook — the scope exists in part because real code lives in real repos. If you can't name repos, ask whether this is truly a scope or just a conversation topic.

Filename

Write to scopes/<id>.md.

Body — the living description

A scope's body is a living description that gets amended (not superseded) as the scope evolves. Cover:

1. What this scope is. One paragraph that a newcomer could use

to decide whether a question or artifact belongs here.

1. What it contains. Systems, services, repos, docs — the

concrete territory.

1. What it doesn't. Adjacent things that might confuse. Name

them and link to their scopes.

1. Interfaces. How this scope relates to others — upstream

dependencies, downstream consumers, handoffs.

1. Ownership and health. Who owns what. Where to find runbooks

or oncall info (or note their absence).

1. Norms. Anything specific about how work happens in this

scope that a visitor should know (review norms, deploy cadence, SLA expectations).

Scopes are flat. auth is not a sub-scope of security. Use related_scopes: to note the adjacency, but don't encode a tree.

Drafting workflow

1. Search; confirm no existing scope covers this.
2. Ask the user to name owners and repos. Push back on empty owner

lists — an unowned scope is a smell.

1. Propose frontmatter + body as a diff.
2. Write on approval.
3. Commit: `git add scopes/<id>.md && git commit -m "Scope:

<id>"`.

Amending a scope

Scope bodies are living. When the scope grows, shrinks, or shifts:

1. Edit the file directly.
2. Commit with a clear message: `git commit -m "Scope <id>:

<what changed>"`.

Do not supersede a scope unless its identity genuinely changed (e.g. a rename from one slug to another).

Retiring a scope

When a scope is no longer relevant:

1. Update frontmatter: status: retired, retired: <today>.
2. Add a closing paragraph at the bottom of the body: when, why,

what took its place (if anything).

1. Commit.

Retired scopes stay in the vault. Grep still finds them. History is honest.

Do not

• Do not nest scopes. The flat list is the point.
• Do not create a scope you don't plan to maintain. Unowned

scopes rot fastest.

• Do not supersede a scope to rename it casually. Think about

whether the old id is load-bearing for references elsewhere first.