Deepen

---
name: deepen
description: "Review and widen an existing knowledge-bundle topic via deep web research + training data: scan a domain for undercooked subjects, research the chosen ones in mandatory-counter-evidence lanes, and land gate-clean corrections, techniques and dated field applications. Runs interactively (finding-level triage), in batch (worker-per-subject under Director diff-review), or as a long-running loop with a saturation ledger. Use when a bundle's subjects should rise above the repo they were forged from, or stay current as the field moves."
category: ai-native
memory: project
version: 1.5.0
tags: knowledge, rkb, research, saturation, loop
---

# Deepen

The forge (`/forge`) creates a bundle from a repository's ceiling;
`/deepen` raises subjects *above* any repository - **improve** (date-stamp or correct
stale claims), **widen** (convergence-earned techniques, dated field applications),
**validate** (benchmarks where a claim hinges on a measurement). Validated across four
bundles: interactive, 3-wide and 8-wide batch, and a 3-round loop on a fresh domain.

**A URL is `/intake`'s input, not this skill's.** When the session starts from a link
somebody sent rather than from a subject we chose, route it to `/intake` - it owns the
ingest instrument, the source ledger, the source-class reading and the corroboration
table, and it dispatches `/deepen` for anything subject-sized that survives. Two runs on
2026-08-23 went through here instead and produced good findings; they also skipped the
untriaged table and the decline ledger, which is the memory that makes run N+1 cheap.

## Invocation

```
/deepen <domain>                      # one interactive pass: scan the bundle, shortlist, triage each finding
/deepen <domain>/<subject>            # one named subject - the caller already ranked it, so start at step 2
/deepen <domain> --batch [--width N]  # worker-per-subject under Director diff-review (ceiling ~8)
/deepen <domain> --loop <N>           # up to N cycles against the saturation ledger; idles on a clock or an event
/deepen <domain> --scan               # step 1 only: the scored shortlist and the gap thesis, land nothing
/deepen status [<domain>]             # read the saturation ledger and subject notes, touch nothing
/deepen reflect                       # update LESSONS.md and this method from recent passes
```

**The subject form is an address, not a slug.** `<domain>/<subject>` is the id
`index.json` and the librarian's notes already spell
(`librarian/subjects/<domain>/<subject>.md`); the file it names is resolved
through `index.json`, never built from the slug, because a bundle is nested and
step 1's own rule is resolve-never-construct.

**There is no bare form, on purpose.** With no domain this skill would have to
sweep every bundle, which is `/librarian`'s job - and the librarian dispatches
*here*, scoped, which is the direction the lane is built to run in.

**A caller that names one subject inherits the saturation law, it does not
escape it.** `--loop` idles by design; a single directed run is not exempt from
the anti-pattern below - re-running a saturated subject still needs a clock or
an event to point at, and "a dispatcher chose it" is only an event when the
dispatcher can say which clause it measured. A run that finds the subject
settled reports `idled` and that is a result.

> **Written 2026-09-26, and the omission is the finding.** This file described
> three modes in its own frontmatter for five weeks and documented no command
> for any of them. Nothing broke for a human, who types what the prose implies.
> It broke for a program: a dispatcher reading this lane cannot tell "runs bare"
> from "documents nothing", so the honest reading of a missing block is
> *unknown*, and unknown is not permission - 103 ranked subjects sat
> undispatchable behind an absent heading, not behind a policy. `/forge` is
> still in that state.

## The cycle

1. **Scan** - score every subject: deterministic signals first (technique/application
   counts, body mass, stack diversity, missing dated applications), then **demand**
   (registered consumer apps' use-cases x the bundle index - a coverage hole is
   forged, not deepened around; a consumer deviation outranks any scan), then
   staleness - now a computed input, not a hand scan: `node scripts/check-currency.mjs
   --json` returns expired, at-risk and stack-drift per application, plus which
   bundles have no reporting installation at all (`witness: unknown` is NOT
   `current`). Spot-check the index against one real file before trusting any score.
   **Volatile facts are a computed input too:** `node scripts/check-currency.mjs
   --volatile` ranks documents by the platform-set quantities they state (windows,
   multipliers, prices, thresholds) scaled by time since `verified_on`; `--subject
   <slug>` lists that subject's facts by line. The clock above exists only on
   applications and measures age, not whether a fact moved: on 2026-10-14 an unexpired
   application still said a cache-read price of "~0.1x" that one vendor had since split
   by model, and a golden path said "63 days" for a window a platform sets at 90. A
   locator, never a verdict: a high score means read the numbers against sources.
   Judgment gap-thesis pass on the shortlist only.
2. **Research** - 3-6 lanes per subject. **Counter-evidence is non-optional** and the
   highest-value lane per token in every measured run: actively refute the subject's
   strongest claims; a claim verified-and-left-untouched is a first-class result.
   One **training-data-only** lane runs blind to search results - its job is proving
   convergence (a claim two independent lanes reach earns technique-level placement).
   **That convergence does not confirm a volatile fact.** A price, window, threshold or
   default that a vendor sets is exactly what training data holds an old copy of: in a
   2026-10-14 control pass the blind lane agreed with every figure the web lane refuted,
   and a "2-3 weeks" geo-test convention was left standing as "training memory agrees,
   not re-sourced" while the platform's own page said 3-10. A directed run starts from
   `check-currency.mjs --volatile --subject <slug>`, and a volatile fact is
   confirmed-untouched only when a page you opened says so.
   **Read the current file before drafting any correction** - golden paths often
   hedge better than techniques, and phantom fixes against a summary are the
   dominant failure mode.
3. **Apply** - in-session, gate-clean, atomic commits per subject. Product-named
   knowledge lands only in applications. Every application carries `verified_on:`
   (the date YOU resolved its citations - a fact, gate-required) and, where you read
   a real tree, `verified_against: <stack>@<major>` - that is the only field that
   makes a runtime bump computable, and only something that opened the tree may write
   it. Add `refresh_by:` ONLY to override the derived clock for a subject that moves
   faster or slower than its stack (vendor landscapes ~3 months, regulatory <=12,
   standards ~6); the default window is derived per stack in `check-currency.mjs`, so
   a routine application needs no clock of its own. Corrections keep `status: forged`;
   nothing self-promotes. **A correction that re-checks a citation must move
   `verified_on` - otherwise the corpus ages while the work says it did not.**
4. **Propagate** - a landing that stops at the registry is a wiki edit. Measured
   2026-09-02: every one of the fleet's 287 recorded verdicts was judged against a
   subject that had since moved, and nothing had told any project. Three
   obligations, none skippable, all after the commit:
   - **Regenerate the join.** `node scripts/build-knowledge-rules.mjs` (the always-on
     rule consumers read; CI gates it and this skill's old sequence omitted it), then
     `node scripts/build-registry-map.mjs`. The map now stamps every pair with the
     subject's own digest and marks judged pairs `stale: true` when the subject they
     were judged against changed; its impact table prints *which subjects moved under
     which projects' verdicts*. Commit each project's `.ai/registry-map.json` with a
     pathspec on its active branch (single-owner doctrine; never push).
   - **Read the impact table into the ledger.** For every subject you touched, the
     projects and contexts now carrying a stale verdict go into the subject note
     under "Impact" - slugs and counts only. That list is the project's `/conform
     --stale` queue and it is what makes run N+1's demand real instead of inferred.
   - **Apply what is new.** Every NEW technique and every golden-path rule that
     *flipped* (a condition added, an absolute refuted) owes one row in
     `librarian/applied.md`, by the `/intake` Phase 7.5 method and vocabulary:
     find the seam in a project the map already joins to the subject, choose the
     highest reachable mode (`code` / `experiment` / `simulation`), record `better` /
     `not-better` / `unmeasurable`, and write `applied:` + `ab_verdict:` on the
     application. A simulation with three real cases is the floor; `unapplied` with
     the return condition "when a project grows the seam" is the only other honest
     row. A `not-better` is the row worth most - the technique gains the condition
     it lacked. Budget: the effort of the landing, one project per finding; in
     batch mode the Director dispatches one apply worker per new technique after
     the diff review, under the intake Phase 8 rules for touching a project tree.
5. **Reflect** - decline-why (once, batched), a per-domain **saturation ledger**
   (depth rung L1 synthesis / L2 primary / L3 empirical; last-pass yield; clocks;
   demand; dry-streak), and banked leads with return conditions. Recompute scores
   fresh every cycle - carried-forward derived metrics drift silently.
6. **Report, for a program** - the ledger and the subject notes are written for a
   reader, and a dispatcher can read none of it: "landed two techniques", "went dry"
   and "refused" look identical from outside. Write one result through the helper
   that owns the rules (public-safe paths, a decline with its reason, unknown fields
   rejected, atomic placement):

   ```sh
   node scripts/lib/run-result.mjs write <draft.json>   # -> librarian/runs/<run-id>/result.json
   ```

   This skill fills `mode` (`interactive` / `batch` / `loop`), `domain`, the five
   `counts` - **`idled` is how loop mode says saturated**, which no other field can
   express - one `subjects[]` row per subject with its engine and an `outcome` from the
   same closed set as the counts (`landed` / `declined` / `idled` / `contended` /
   `dispatched`; a saturated subject is `idled`), `declined[]` carrying the decline-why
   this step already produces, `verdicts[]` for every `applied.md` row step 4 owed - at
   the mode it was measured at, `code` / `experiment` / `blind-ab` / `simulation` /
   `render` and nothing else - and `failure_signature` when a pass failed the same way
   twice. It writes **`pr: null`**: this skill commits and never opens one.
   In batch mode the **Director** writes one result for the whole batch - workers
   write nothing, the same single-writer rule that governs their folders.

## Batch mode (Director-reviewed)

One full-pipeline worker per top candidate, in parallel. Hard worker rules: own
subject folder only - **resolve its path, never construct one**, because a bundle may
be nested (`knowledge/<bundle>/<category>/[<subcategory>/]<subject>/`) and a worker
that guesses writes into a folder nobody reads. `index.json` carries each subject's
`file`; that is the address. Cross-subject findings return as **proposals**, including
home-ambiguous techniques - the Director places them); at most one new technique and
only on lane convergence; never touch shared files; never commit. **The Director
reviews actual diffs, never worker self-reports** - purity grep over upper layers, a
read of every new technique, corrections checked against the file's prior voice.
That review is the quality gate that replaces per-finding triage; it is not
delegable, and it is the batch-size ceiling (~8 per sitting). Workers never run
step 4; the Director runs it once over the whole batch, because the map
regeneration is one fleet-wide pass and the apply workers need a quiet tree.

### Cloud overflow

A seat limit kills every local worker at once, so the overflow is prepared before it is
needed. Before dispatching local workers, the Director writes each worker brief with
`cloud_ok: true` from `skills/cloud-dispatch/briefs/deepen-research.md` and queues it with
`queue.mjs --add`; it marks the item `--done` when that local worker returns. If the seat
hits its limit, the `StopFailure` hook ships the still-queued briefs to cloud sessions, and
their pull requests come back for the same Director diff review as a local worker's tree.
Explicit dispatch of a research worker straight to the cloud is also allowed when the
operator wants the work off the local seat. The method is `skills/cloud-dispatch/SKILL.md`.

## Loop mode

Cycle -> ledger -> repeat. A subject is **saturated** when: two consecutive passes
return counter-evidence all-confirmed with no earned technique (dry=2), the
structural floor passes, and every dated claim sits inside its clock. Saturation is
a state, not an end: when nothing clears threshold the loop **idles until the
earliest clock or an event** (consumer deviation, new registered app, a probe
contradicting the literature) and says so. Later rounds are **training-data-first by
design** - probes test standing claims; only round-1 surveys are web-heavy.

## Source-class memory (guarded)

Keep a per-domain ledger of source **classes** - never URL allowlists - tallied
post-hoc from worker citations against accepted vs declined findings ("regulation
text beats commentary"; "standards bodies' own docs are rich"; "listicles need a
second source"). Class priors feed landscape/current-practice lanes only; the
counter-evidence lane searches unconstrained, and the training-data lane never sees
priors - it is the calibration control (divergence from prior-guided lanes means the
priors are drifting). Negative caches are per-topic, never global. A class rule
graduates into this skill only after 3+ cross-domain observations, with its incident.

## Benchmarks

Only where a claim's value hinges on a measurement and a harness exists. Prefer
fixtures with **known ground truth** over fresh generations; run one agent making N
calls; n always visible; ask before real spend. Measured results live in
applications with their n - never laundered into upper layers as universal numbers.

## Anti-patterns (each earned by a measured incident)

- Reporting a content gap without verifying the instrument first.
- Padding a findings list - dry is a result; bank it.
- Editing upper layers with product names; the gate catches it, don't make it.
- Carrying forward last cycle's scores, or writing counts from memory instead of
  the regenerated index output.
- A benchmark that asserts data round-tripped rather than behavior observed.
- Re-running a saturated subject with no clock or event to point at - the loop's
  own law is that unmeasured is not pass.
- Ending a run at the registry commit. A landing nobody's map has seen and no
  project has tried is an edit to a wiki; the corpus was measured at 100% stale
  verdicts fleet-wide on 2026-09-02 because every run before that one did exactly this.