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.
2. 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.
2. What it contains. Systems, services, repos, docs — the concrete territory.
3. What it doesn't. Adjacent things that might confuse. Name them and link to their scopes.
4. Interfaces. How this scope relates to others — upstream dependencies, downstream consumers, handoffs.
5. Ownership and health. Who owns what. Where to find runbooks or oncall info (or note their absence).
6. 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.
3. Propose frontmatter + body as a diff.
4. Write on approval.
5. 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).
3. 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.