iopsystems Open arc
You are opening a new arc in the knowledge-iop vault. An arc is a narrative unit of change — it opens, progresses through briefs and inquiries, and closes (or is abandoned). Spans weeks to quarters. Operates within one or more scopes.
Before opening — check the alternatives
- Invoke
vault-searchwithtype: arc,status: opento see what's already in flight. An arc should be a distinguishable narrative, not overlap another open arc. - Check the alternatives:
| If the thing you're about to open is... | Do this instead |
|---|---|
| A permanent reference frame | define-scope |
| A single brief with no follow-on | Just frame-problem + propose-design |
| A sub-effort of an existing open arc | Extend that arc; don't spawn |
| A decision that's already obvious | record-decision |
Arcs without multiple expected artifacts are overhead. If the answer to "what will this arc contain?" is one brief, skip the arc.
Frontmatter shape
---
id: <short-slug> # e.g. "vault-bootstrap", "billing-refactor"
type: arc
status: open
opened: <YYYY-MM-DD>
closed: null
leads: [<person>, ...]
scopes: [<scope-id>, ...] # one or more; required
tags: [<tag>, ...]
author: <person>
created: <YYYY-MM-DD>
---
id: is a plain slug. Unlike briefs, arcs aren't dated in their id
— the opened: field handles timing.
scopes: is required. An arc that doesn't touch any scope is
either improperly scoped or needs a new scope opened first.
Filename
Write to arcs/<id>.md.
Body — the charter
The body of an arc is a charter — amendable over the arc's life, but not superseded. Cover:
- The situation. What's going on that warrants opening this arc.
- The tension. What's not working, or what opportunity is newly available. The arc exists because of a gap between current and intended state.
- Direction of resolution. Where you expect this to go. Not a promise — a trajectory. If you're wrong, amend the charter.
- Expected artifacts. Roughly what will land here — briefs, inquiries, decisions. Gives the arc shape without committing.
- Closing conditions. What has to be true to close this arc
as
closed(vsabandoned). Be concrete. "Reasonable progress" isn't a closing condition; "X service is live and Y decision is recorded" is. - Scopes touched. One paragraph each if the arc crosses several scopes, explaining how.
Arcs aren't roadmaps. Don't include a Gantt chart or commit dates; the vault isn't a project tracker.
Drafting workflow
- Search for overlapping open arcs. Confirm the alternatives don't apply.
- Ask the user for leads, scopes, and closing conditions. Push back on "we'll know when we get there" — vague closes are how arcs drift into permanence.
- If any named scope doesn't exist in the vault, chain to
define-scopefirst. - Propose frontmatter + body as a diff.
- Write on approval.
- Commit:
git add arcs/<id>.md && git commit -m "Open arc: <id>".
Amending a charter
An arc's charter is amendable as the narrative unfolds:
- Edit the file. No supersession.
- Commit:
git commit -m "Arc <id>: <what changed>".
If amendments start pushing the arc away from its original trajectory and closing conditions, consider whether the arc should be closed and a successor opened — that's visible in history, which is the point.
Sub-arcs are not a thing
Per SCHEMA.md: "Sub-arcs are not a thing. If an arc grows too large, close it and spawn successors with explicit handoff."
Closure with handoff: write a decision or session note explaining what closes, what opens, and why.
Do not
- Do not open an arc without closing conditions. Unbounded arcs become permanent, which defeats the point.
- Do not open an arc in scopes that don't exist yet. Open the scopes first.
- Do not open an arc as a container for a single brief. The brief alone is enough.