# System Deep Loop

> Routes research and review modes through registry-selected packets.

- Skill: `michelkerkmeester/system-deep-loop` (Agent Skill, multi-file: 867 files)
- Install (CLI): `npx get-skill add michelkerkmeester/system-deep-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michelkerkmeester/system-deep-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: MichelKerkmeester (https://skillmd.com/u/michelkerkmeester)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/michelkerkmeester/system-deep-loop

---


<!-- Keywords: system-deep-loop, deep-loop, deep-research, deep-review, autoresearch, iterative-research, review-loop, deep-review-wave, release-readiness, severity-findings, P0-P1-P2, benchmark-harness, convergence-detection, externalized-state, iteration-files, coverage-graph, mode-registry, workflowmode, runtimeloop-type, backendkind -->

# System Deep Loop

One skill has two active workflow families and one nested runtime layer.
`system-deep-loop` is the public, advisor-routable home for active deep-loop personas.
`runtime/` is the frozen, MCP-free infrastructure layer it consumes.
This hub holds NO per-mode convergence, state or synthesis logic.
Each active mode keeps its own contract in its packet. The hub only routes by `workflowMode` through `mode-registry.json`.

**Version authority.** This file's `version` frontmatter is the hub's release version and matches the newest entry under `changelog/`; `description.json`, `mode-registry.json` and `hub-router.json` carry the same value, so every hub-root JSON routing file states the same release; `ROUTER.md` keeps its own document version.

Use `@context` for one-shot retrieval, `/deep:research` for iterative investigation with a bounded context snapshot, `/deep:review` for iterative audit with a bounded review snapshot, or `/speckit:plan` for implementation planning.

---

## 1. WHEN TO USE

Use this skill (through the hub) for any active deep-loop workflow. Invoke it as `Skill(system-deep-loop)` (optionally with a mode hint such as `research: <request>`); the hub classifies the request, resolves a `workflowMode`, and loads the matching nested mode packet. Active `/deep:*` commands and native agent types remain as complementary surfaces over the same packets.

| Mode | Use it for | Packet | Command | Agent |
|------|-----------|--------|---------|-------|
| **research** | Outward, web + code iterative investigation → `research/research.md` | `system-deep-loop/deep-research/` | `/deep:research` | `deep-research` |
| **review** | Iterative review loop → P0/P1/P2 findings + verdict | `system-deep-loop/deep-review/` | `/deep:review` | `deep-review` |

A planning council is not a mode of this hub. It runs as the standalone `@ai-council` agent, reached through `/speckit:ai-council`.

### When NOT to Use
- A single quick read/edit (no loop) — use the relevant code or doc skill directly.
- Backend/runtime support (executor, coverage-graph, scoring, fan-out) — that is `runtime/`, consumed here, not invoked as a user workflow (formerly the separate deep-loop-runtime skill).

---

## 2. SMART ROUTING

Routing is **registry-driven at runtime and authored in `hub-router.json`** in two stages.
Stage 1 (hub → mode) selects a mode: `hub-router.json` `vocabularyClasses` is the one authored vocabulary, and its `routerSignals` keys are `research` and `review`.
The `mode-registry.json` aliases, each packet's `Keyword triggers:` line where one exists and the root `ROUTER.md` intents are checked against it.
Stage 2 (mode → leaves) lives in the root [`ROUTER.md`](./ROUTER.md), which maps the request's deep-loop intent to the packet-local leaf resources that mode loads.
The advisor routes every deep-loop query to the single identity `system-deep-loop`.
Resolve the mode with `node .skilled/bin/compiled-route.cjs --hub system-deep-loop --prompt "<task>"`.
Compiled routing is the default. `route` loads its `targets`, `clarify` and `defer` ask, `reject` refuses.
An unclear deep-loop intent asks for disambiguation, because `routerPolicy.defaultMode` is `null`.
The `routerPolicy.defaultResource` list is only a defer-time suggestion, never a silent default.
Run the compiled-routing directive in [`ROUTER.md`](./ROUTER.md) before selecting hub resources.

---

## 3. HOW IT WORKS

### Terms

- **`workflowMode`**: the public active mode key, `research` or `review`.
- **`runtimeLoopType`**: the graph-backed convergence key that `runtime/scripts/convergence.cjs` consumes, validated against `research|review`, explicitly `null` for a custom backend and never inferred from `workflowMode`.
- **`backendKind`**: `runtime-loop-type` for both modes, which run on the `runtime/` convergence backend.
- **mode packet**: one of the two nested folders that owns its mode's convergence, state and artifact contract.
- **`runtime/`**: the frozen, MCP-free layer every mode consumes, holding the executor config, atomic state, coverage graph, Bayesian scoring, fan-out and the seat-dispatch file the divergent pivot uses.
- **`mode-registry.json`**: the registry that owns each mode's discriminator and its authoritative `packet` path.
- **`hub-router.json`**: stage one's signals, vocabulary classes and tie-break order.
- **`vocabularyClasses`**: the authored deep-loop vocabulary that stage one scores.
- **`UNKNOWN_FALLBACK`**: the load level the router returns, with its disambiguation checklist, when no mode resolves or the registry has no entry for the mode.
- **leaf**: a canonical `(workflowMode, leafResourceId)` pair from `leaf-manifest.json`.
- **`defer`**: the outcome that asks for disambiguation, which this hub reaches because `routerPolicy.defaultMode` is `null`.
- **advisor projection map**: one of the hardcoded advisor maps that a drift-guard test keeps equal to the registry projection.

### Layout
```
system-deep-loop/
  SKILL.md               # this routing hub (no per-mode logic)
  ROUTER.md              # stage-two surface router (deep-loop intent -> leaf sets)
  mode-registry.json     # the three-tier discriminator + advisorRouting (single source of truth)
  graph-metadata.json    # the ONE advisor identity for the whole skill
  deep-research/   deep-review/   # active mode packets
  shared/synthesis/      # workflows-shared synthesis (e.g. emitResourceMap)
```

Always resolve a packet path through `mode-registry.json` instead of hardcoding it.
Each active mode packet keeps its own `SKILL.md`, `references/`, `scripts/`, `assets/`, `feature-catalog/` or `manual-testing-playbook/`, as applicable, with internal paths repointed.
Mode packets have **no per-packet `graph-metadata.json`**. Only this hub carries one, so the advisor discovers exactly one skill.

### Backend
All modes consume `runtime/`, a frozen, MCP-free layer.
It provides executor config, prompt-pack, validation, atomic state, coverage-graph, Bayesian scoring, fan-out and the seat-dispatch file the divergent pivot uses.

- The offline fan-out pair replay at `runtime/scripts/score-fanout-pairs.cjs` reads the merge's own decisions on near-line and cross-body pairs.
- It compares a backend's judgment with the operator's labels and makes no model call by default.
- Until the operator has labeled 40 pairs, 10 of them cross-body, it prints `stop: fewer than 40 labeled pairs`.
- It runs its `--jev` arm only with `--out <dir>` and past that backend's own gate.
- It leaves the merge unchanged.

---

## 4. RULES

### ✅ ALWAYS
- **ALWAYS** resolve a mode through `mode-registry.json` (read the `packet` key; never hardcode a router mapping or packet path in the hub).
- **ALWAYS** keep advisor projection maps hardcoded and drift-guarded against the registry; command mode routing is still hardcoded in the command files and does not resolve through `mode-registry.json`.
- **ALWAYS** keep each mode's convergence/state/artifact contract in its packet — the hub stays logic-free.
- **ALWAYS** keep exactly one `graph-metadata.json` (this hub's) so the advisor sees one skill identity, whether a mode is reached via `Skill(system-deep-loop)`, a `/deep:*` command, or an agent.
- **ALWAYS** keep the root `ROUTER.md` `RESOURCE_MAP` in sync with `leaf-manifest.json` — the leaf sets dual-read to canonical typed pairs at the one contract boundary.
- **ALWAYS** keep `Skill(system-deep-loop)` hub routing, the `/deep:*` commands, and the agent types as complementary surfaces over the same packets — never let one surface fork per-mode logic out of its packet.

### ⛔ NEVER
- **NEVER** infer `runtimeLoopType` from `workflowMode` — read it from the registry (explicit `null` is load-bearing).
- **NEVER** add a `graph-metadata.json` or a discoverable skill marker inside a mode packet or `shared/`.
- **NEVER** let a CLI lineage dispatch a nested executor for its own iteration, and prefer not to edit tracked files in a checkout with a live lineage (write containment reports them against that lineage; it no longer reverts them, and a lane that produced its artifacts still completes). Both rules live in `deep-research/references/protocol/loop-protocol.md` under "Executor Resolution".

### ⚠️ ESCALATE IF
- A new mode is needed beyond the two registered — extend `mode-registry.json` and open a packet, do not bolt logic onto the hub.
- A change would require the runtime to gain MCP tools — that contradicts the architecture; escalate.

---

## 5. REFERENCES

- Backend: `.skilled/skills/system-deep-loop/runtime/` (frozen, consumed by every mode; nested infrastructure, not a separate skill).
- Mode packets: `deep-research/SKILL.md`, `deep-review/SKILL.md` (per-mode detail).
- Commands: the active `/deep:*` commands under `.skilled/commands/deep/` (complementary surface).
- Registry: `mode-registry.json` (the routing contract — the authoritative `packet` paths).
- Surface router: `ROUTER.md` (deep-loop intent to packet-local leaf sets).

---

## 6. SUCCESS CRITERIA

- The hub resolves one primary active `workflowMode` for the request through `mode-registry.json` (never by array order).
- The selected mode packet owns the detailed convergence/state/artifact workflow; the hub stayed routing-only.
- `Skill(system-deep-loop[, hint])` reaches a mode, and the `/deep:*` commands and agent types still reach the same packets.
- Exactly one `graph-metadata.json` exists for the whole skill; no packet carries its own.

---

## 7. INTEGRATION POINTS

### Modes
- `research` — outward web + code iterative investigation (`research/research.md`).
- `review` — iterative review loop, P0/P1/P2 findings + verdict.

### Surfaces and Consumers
- `Skill(system-deep-loop)` is the invokable hub; active `/deep:*` commands and the agent types (`deep-research`, `deep-review`) are complementary surfaces over the same packets.
- `runtime/` is the frozen, MCP-free backend every mode consumes (nested infrastructure, not a separate skill).
- `/speckit:plan` consumes `@context` packages plus research/review outputs; spec-folder docs consume research/review output.

---

## 8. RELATED RESOURCES

- Pattern: `.skilled/skills/sk-doc/sk-create-skill/references/parent-skill/parent-skills-nested-packets.md` (parent-skill hub + nested packets, the one-graph-metadata invariant).
- Sibling example: `.skilled/skills/sk-prompt/` (the same invokable-hub + `mode-registry.json` Option E pattern).
- Registry: `mode-registry.json` (this hub's routing contract).

