@reddb-io/red-skills-dev 2.75.2

package/skills/engineering/retake/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: retake
+description: Pick one issue back up — reconstruct where it stands (linked PRs, branches, worktrees, uncommitted or unpushed work, HITL state, active blocker), report that state, then execute the one right action — a plain requeue into `ready-for-agent`, an `--adopt-branch` landing through the no-agent gate, or a handoff to `/hitl`. Use when the user invokes `/retake #123`, asks to resume or recover an issue, wants to requeue a parked issue, or has hand-done work on a branch that needs to land.
+argument-hint: "#ISSUE [--apply] [--json] [--repo OWNER/REPO] [--pr-limit N]"
+---
+
+# /retake
+
+**Diagnose before you act — a requeue fired at an issue whose work already sits finished in a dirty worktree just spawns a second agent to redo it.**
+
+`/retake` is one skill with two halves. The **diagnosis** half reconstructs the
+issue's real state from GitHub and the local filesystem. The **action** half
+executes exactly one transition out of that state. Never skip the first half:
+the label claims `ready-for-human`, but the truth is in the worktree.
+
+<what-to-do>
+
+## 1. Diagnose — Reconstruct The State
+
+Resolve the `red-skills-dev` runtime through the shared contract in
+[`../_report-runtime/WRAPPER.md`](../_report-runtime/WRAPPER.md): use an
+installed shim on `PATH` first, otherwise use the ADR 0091 npm direct-run form
+`npx -y -p @reddb-io/red-skills@<version> red-skills-dev retake ...`. If the
+shim is missing, name that fallback instead of surfacing a bare
+command-not-found.
+
+```bash
+red-skills-dev retake 123
+```
+
+The runtime accepts `123` and `#123`; quote `'#123'` when a shell would read it
+as a comment. Add `--json` when another tool or agent consumes the state.
+
+The report answers six questions, in this order:
+
+1. **What does the tracker say?** Issue state, labels, the active
+   `## Current blocker` in the body, and whether those two agree. A `blocked:*`
+   label without a matching blocker section is a **label/body mismatch** — that
+   issue belongs to `/hitl`, not to you.
+2. **Is there a PR?** Linked PRs from recent PRs plus `#ISSUE` search hits, with
+   their check and review state.
+3. **Is there a branch?** Local and remote branches carrying the issue number.
+4. **Is there a worktree?** Matching local worktrees, each marked `clean` or
+   `dirty`.
+5. **Is the work already done locally?** A dirty worktree holds uncommitted
+   work; a branch ahead of its remote holds unpushed commits. Either one means
+   **the code exists and nobody knows** — say so loudly.
+6. **What is the blocker really?** `blocked:validation` and `blocked:spec` are
+   retryable. `blocked:sensitive-path` is a landing gate, not a retry gate.
+   Anything else is a pending human decision.
+
+## 2. Report — Say Where The Issue Stands
+
+Present the reconstruction before proposing anything. Use this form:
+
+```text
+Issue #123 — <title> [<labels>]
+Tracker:   <state>, blocker: <kind or none>, label/body: agree | mismatch
+PR:        #456 <checks> <reviews>   (or: none)
+Branch:    <name> (<n> ahead / <n> behind origin)   (or: none)
+Worktree:  <path> — clean | dirty (<n> uncommitted files)   (or: none)
+Verdict:   <one sentence: is the work done, partial, or unstarted?>
+Action:    <the single next command>
+```
+
+**The verdict is the point.** "Work is committed on `afk/123-foo`, pushed, PR
+#456 green" and "work is unstarted, only a label is parked" demand opposite
+actions from an identical set of labels.
+
+## 3. Act — Execute Exactly One Transition
+
+Pick by verdict, never by label alone:
+
+| Verdict | Action |
+| --- | --- |
+| Pending human decision, mixed `blocked:*` labels, or label/body mismatch | `/hitl #ISSUE` — stop here, do not requeue |
+| Parked `blocked:validation` / `blocked:spec`, work unstarted, guidance in hand | plain requeue (below) |
+| Work done on a branch — committed and pushed | adopt-branch landing (below) |
+| `blocked:sensitive-path`, and you have **reviewed** the protected diff | adopt-branch landing (a bare requeue refuses) |
+| Open PR with failing checks or changes requested | fix the PR branch first; neither command lands a red PR |
+| Dirty worktree | commit and push inside that worktree, then re-run `/retake` |
+
+### Plain requeue — put a parked issue back in the queue
+
+```bash
+red-skills-dev requeue 123 --guidance "Retry with the documented guidance; the gate flake is fixed."
+```
+
+One atomic transition: archive the active `## Current blocker` into
+`## Resolved blockers`, post the guidance as an auditable `directive` comment,
+drop `ready-for-human` and every `blocked:*` label, add `ready-for-agent`.
+
+### Adopt-branch landing — validate and land hand-done work
+
+```bash
+red-skills-dev requeue 123 --adopt-branch my-feature-branch --guidance "Manual implementation complete; run gate."
+```
+
+After the requeue transition, the branch routes through the **no-agent landing
+lane** (ADR 0055). The shared feedback gate validates it with no agent re-run;
+green lands it through `doLanding` and closes the issue; red parks it back to
+`ready-for-human` with `blocked:validation` plus the real failing checks; a
+branch with no commits versus base exits 0 with a note. An adopted branch and an
+AFK branch pass the same gate authority.
+
+`--guidance` is required in both modes — it records the human decision. Use
+`--dry-run` to print the planned transition without mutating, and `--json` for
+structured output.
+
+### `--apply` — safe local setup only
+
+`red-skills-dev retake 123 --apply` runs only the safe local `git` operations
+the diagnosis selected: create a missing manual worktree under
+`.red/tmp/worktrees/manual/<slug>`, recreate it from a matching branch, or fetch
+a PR head branch into a fresh worktree. It then prints the next `cd`, `requeue`,
+or `/go` command.
+
+- ✅ `--apply` is non-destructive by construction — local `git` setup, nothing else.
+- ❌ Do **not** expect `--apply` to merge, close issues, edit labels, run the requeue transition, or move the primary checkout's branch. It does none of them.
+- ❌ Do **not** flip labels by hand instead of running requeue. AFK preflight re-reads the active blocker and re-parks the issue, so a hand-flipped label is a silent no-op retry loop (#850).
+
+</what-to-do>
+
+<supporting-info>
+
+## Why a label flip alone fails
+
+A validation or spec failure parks an issue with three things at once:
+`ready-for-human`, a `blocked:*` label, and an active `## Current blocker` in
+the body. AFK preflight reads that blocker **before any work starts**, so an
+issue whose labels say `ready-for-agent` while its body still carries a blocker
+is re-parked immediately. The blocker must clear in the same transition that
+flips the labels. Producing that single transition is what the `requeue` command
+exists for.
+
+## Clearing a `blocked:sensitive-path` park (#1171)
+
+A sensitive-path park means the diff touches a protected path — a CI workflow, a
+lifecycle script, a git hook, `.red/` config. It gates **landing**, so it
+re-fires on every fresh attempt: bare requeue → `/hitl` → a new attempt
+reproduces the same protected diff → re-parks. An infinite loop.
+
+`--adopt-branch` breaks it. On a `blocked:sensitive-path` issue, requeue clears
+the blocker, drops `ready-for-human` and `blocked:sensitive-path`, and adopts the
+reviewed branch **with the sensitive-path landing guard bypassed for that land
+only**. An audit comment records who approved the diff and when — the bypass is
+never silent. The guard is never weakened for the autonomous path: every normal
+AFK or `/go` attempt still parks. The bypass is reachable only from this
+explicit human command, and a bare requeue of a sensitive-path park still
+refuses.
+
+## `/retake` vs `/hitl` — the decision boundary
+
+**Stay in `/retake`** when the decision is already made: the issue is
+`blocked:validation` or `blocked:spec` with no other `blocked:*` label, the label
+kind and the active blocker kind agree, and you hold the retry guidance. Or when
+you have a hand-done branch to adopt. Or when you have reviewed a protected diff
+and want to land it.
+
+**Hand to `/hitl`** when the pending human decision still has to be *extracted* —
+it interviews the maintainer, decides delegability, then clears the blocker and
+requeues. Hand over any issue carrying mixed `blocked:*` labels, a label/body
+mismatch, or a blocked kind outside `validation` / `spec` / `sensitive-path`
+(`blocked:decision`, `blocked:stalled`). Both paths end in the same safe state;
+`/retake` is the informed shortcut, `/hitl` is the interview.
+
+## Where the work lives
+
+Hand-done work belongs in the manual-worktree lane
+`.red/tmp/worktrees/manual/<slug>`, never on the primary checkout's branch. Use a
+lowercase kebab-case slug, usually the issue number plus a short task name. When
+the diagnosis finds no local state at all, the next action is a fresh worktree
+from `origin/main` — or, for a brand-new one-off demand that never was an issue,
+`/go "<demand>"` instead of this skill. After an adopted branch lands through the
+no-agent landing lane, its worktree is pruned automatically.
+
+## See also
+
+- `/hitl` — interactive decision extraction before requeueing
+- `/go` — dispatch an untracked one-off demand end-to-end
+- ADR 0055 — the no-agent landing lane (reconcile / doLanding)
+- ADR 0081 — command topology; retake is the manual adoption path
+
+</supporting-info>

package/skills/engineering/review-adrs/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: review-adrs
+description: Review the `.red/adr/` set for consistency issues, reconcile each finding with the maintainer through a one-question-at-a-time interview — reaching agreement before any write — then consolidate every agreement into a single actionable Spec on the issue tracker via `/to-spec`. Use when asked to "review the ADRs", after adding or reversing an ADR, or to turn ADR decision debt into scheduled work.
+---
+
+# Review ADRs (decision-record interview → actionable Spec)
+
+**Lint the decision record read-only, reconcile each finding through a one-question-at-a-time interview, and package every agreement into one Spec — never edit an ADR, the wiki, or the graph directly.**
+
+ADRs accumulate (30–40+ per repo) and **derive**: one reverses another, a path it
+cites moves, a decision was taken controversially and never reconciled, the wiki and
+Memory graph hold claims sourced from a decision that later changed. This is the
+"doctor of decisions" — sibling to `/red-doctor` (adoption) and `memory:doctor` (graph).
+Detection is read-only; **every resolution is reached through an interview** — one
+question per turn, `/start`-style — and the agreement is captured, not applied. The
+skill never edits an ADR, the wiki, or the graph: it consolidates every agreed fix
+into **one Spec** on the tracker, which `/to-tickets` + `/afk` execute afterwards.
+
+<what-to-do>
+
+**First detect read-only (Pass 1). Then run the Reconcile interview (Pass 2): walk the findings as a decision tree, ask ONE question per turn with a recommended resolution, wait for the reply, and record the agreed action. Grouping (Pass 3) and propagation (Pass 4) are further branches of that same interview. Then emit ONE Spec via `/to-spec` (Pass 5) holding every agreed action. The only artefact this skill writes is the Spec.**
+
+### Hard rules
+
+- ❌ Do **not** edit ADR bodies, renumber files, write the INDEX, supersede a Memory node, or re-ingest a wiki page directly. This skill ends in a **Spec on the tracker**, not in applied edits. Every agreed fix becomes a Spec work item, executed later by `/to-tickets` + `/afk` or a human.
+- ❌ Do **not** auto-resolve a finding or controversial decision. Surface it in the interview; the maintainer's answer is what gets recorded as the agreed action.
+- ❌ Do **not** stack questions. **One `Q##` per turn.** Wait for the reply, re-evaluate the tree, then ask the next. Do not preempt the next question, and do not summarise the user's answers back at them.
+- ✅ Before Pass 1, run `git fetch origin`, resolve `origin/HEAD` to the remote default branch, and lint from that Git ref (`origin/<default-branch>`). Read ADR/context files with Git plumbing such as `git ls-tree` / `git show`; do **not** inspect `.red/adr/` from the working tree. Use local `HEAD` only when no `origin` remote/ref exists, and state that fallback in the report.
+- ✅ Compose existing surfaces to detect: `/wiki lint` for wiki claims, Memory supersession/contradiction reads for graph claims. Do not reimplement them.
+- ✅ Compose `/to-spec` to publish — do not hand-roll the Spec format. Every interview agreement is a **Human Decision** in that Spec (load-bearing judgement the agent could not infer).
+- ✅ Honour ADR conventions in `start/ADR-FORMAT.md` (Status frontmatter, "superseded by ADR-NNNN", Related links).
+
+### Pass 1 — Lint (detect, read-only)
+
+Fetch first: `git fetch origin`. Resolve `origin/HEAD` to the remote default branch, set the lint ref to `origin/<default-branch>`, and read every `.red/adr/*.md` (and `.red/CONTEXT-MAP.md` / contexts if present) from that ref. Use `git ls-tree -r --name-only "$lint_ref" -- .red/adr .red/CONTEXT-MAP.md .red/contexts` to discover files and `git show "$lint_ref:$path"` to read them; path-existence checks for stale references must also query the same ref. Lint **against the fetched committed tree**, not a dirty or stale local working copy, so a lagging checkout is never mistaken for a real finding. If there is no `origin` remote/ref, fall back to local `HEAD` and say so before reporting findings. Report:
+
+- **Contradictions** — two ADRs whose decisions oppose on the same topic (e.g. "memory lives in `src/apps`" vs "memory moves to `red-memory`"). Flag pairs that should cross-reference but don't.
+- **Missing supersession** — a later ADR reverses/supersedes an earlier one, but the earlier still reads `Status: accepted` with no "superseded by ADR-NNNN" / Related note.
+- **Stale references** — an ADR cites a path / file / command that no longer exists (grep the body for paths, check existence; e.g. an ADR naming `src/domains/` or `src/apps/` after the tree became `apps/`). Flag the prose, not the decision.
+- **Numbering** — duplicate or gap-colliding ADR numbers (two files claiming the same NNNN, e.g. when parallel branches both grab the next number).
+- **Structural / controversial decisions** — a decision that is internally incoherent, was taken under unresolved disagreement, or was never actually implemented. These are the ones that **don't** get fixed by editing markdown — they need real work, and they are the spine of the Spec.
+
+This finding list **is the decision tree** the interview walks. Present it once, briefly, ordered by impact — then enter Pass 2.
+
+### Pass 2 — Reconcile (the interview — `/start`-style, the core of this skill)
+
+Walk the Pass-1 findings as a decision tree. **The loop:**
+
+1. **Pick the next unresolved finding**, highest-impact first: numbering collisions (they break references) → contradictions → missing supersession → stale references → structural/controversial decisions.
+2. **Ask ONE question** in the format below — branches for the finite resolution space, plus a recommended branch with a one-sentence reason.
+3. **Wait** for the reply. Do not stack, do not preempt.
+4. **Re-evaluate** when the answer cascades (e.g. renumbering an ADR also changes the INDEX entry and every cross-ref to it) — fold the cascade into the tree before the next question.
+5. **Record the agreed action** in the ledger (the agreement *is* the spec for a Spec item — do not apply it), then continue.
+6. **Stop** when the user says stop, or when every finding is resolved.
+
+**Question format template (identical discipline to `/start`):**
+
+> **Q##:** [the decision to reconcile]
+> **Branches:**
+>  (a) [resolution A — e.g. "renumber the locally-authored ADR to the next free number, fix its inbound refs"]
+>  (b) [resolution B — e.g. "renumber the other one"]
+>  (c) [defer — leave the finding open, no Spec item]
+> **Recommend:** (a), because [one-sentence reason].
+> *(answer, redirect, or push back — I'll wait)*
+
+Number questions `Q01`, `Q02`, … zero-padded to 2 digits, session-scoped (reset each invocation, never on a redirect). Prefer enumerated branches whenever the resolution space is finite; `(c) defer` is almost always a legitimate branch — a finding the maintainer wants to think about is simply left out of the Spec.
+
+### Pass 3 — Group → INDEX (one agreement within the interview)
+
+When the lint findings are reconciled (or the user wants the map first, to reason about them), raise a question on whether to (re)generate **`.red/adr/INDEX.md`** — the decision map (the ADR analogue of `CONTEXT-MAP.md`): ADRs clustered by theme (AFK lifecycle · memory architecture · bundle/fetch/version · branch-lock · MCP/transport · licensing · repo structure · …), each entry showing theme, status, and supersession edges, reflecting the numbering/supersession just agreed. May reuse Memory graph-community clustering when graph mode is available. The agreed clustering becomes a **Spec item** ("create/refresh `.red/adr/INDEX.md` as …"), not an inline write.
+
+### Pass 4 — Propagate to Wiki + Memory (further interview branches)
+
+A changed/superseded ADR leaves derived claims dangling. For each ADR touched in Pass 2/3, raise it as its own question:
+
+- **Wiki** — `/wiki lint` (contradictions / orphans / stale claims); find pages whose `REFERENCES` point at the changed ADR. Ask whether to re-ingest that ADR — if yes, it becomes a Spec item.
+- **Memory** — ADRs are first-class graph nodes (engineering semantic graph). Find nodes whose provenance cites the changed ADR. Ask whether to `memory_supersede` the obsolete claims (reversible hide-not-delete) — if yes, it becomes a Spec item.
+
+One question per target, one agreed action per item. Never silently propagate.
+
+### Pass 5 — Emit the Spec
+
+Hand the accumulated agreed actions to `/to-spec`:
+
+- **Problem Statement / Solution** — the decision debt found and the reconciliation plan.
+- **User Stories** — one per agreed action, phrased as the concrete edit/work: "rewrite ADR-0034 Status to `superseded by 0041` and add the Related link", "renumber the locally-authored ADR and fix its inbound refs", "create `.red/adr/INDEX.md` clustering the set", "re-ingest ADR-0041 into the wiki", "implement the reconciliation of the controversial X decision".
+- **Human Decisions** — every interview answer (`Q##` → agreed branch), in `/to-spec`'s Decision/Why/Alternatives shape. These are load-bearing: once `/to-tickets` slices the Spec they must not be mistaken for agent inference.
+
+Publish with `type:spec` + `needs-slicing` (never `ready-for-agent` — `/to-spec` handles the labels). Then in chat: a short receipt of each `Q##` and the action it produced, the link to the published Spec, what was **deferred** (left out), and the single highest-impact finding to reconcile first.
+
+### End-of-session doc-landing finalizer
+
+When the ADR review session ends, run the shared end-of-session doc-landing finalizer in [`/start`'s DOC-LANDING-FINALIZER.md](../start/DOC-LANDING-FINALIZER.md) before exiting.
+
+</what-to-do>
+
+<supporting-info>
+
+### Why this is an interview, not a flat list
+
+ADR reconciliation decisions are exactly the kind `/start` exists for: hard to reverse (renumbering breaks inbound refs; supersession hides graph claims), surprising without context, and the product of a real trade-off (which of two colliding ADRs renumbers? does the older one get a "partially superseded" note or a full one?). A flat approval list forces all of these at once and invites a rubber-stamp. Walking them one at a time — recommend, wait, re-evaluate — is how shared agreement is actually reached, and it lets one answer reshape the rest of the tree before the next question is asked. The agreements then become a coherent Spec instead of a scattered set of edits.
+
+### Why each finding kind exists (worked examples)
+
+- **Contradiction / missing supersession:** ADR 0034 placed memory under `src/apps`; ADR 0041 moves it out to the `red-memory` repo — 0034 should carry a "partially superseded by 0041" note. The interview asks: full or partial supersession, and worded how? → Spec item to rewrite 0034's Status + Related.
+- **Stale reference:** an ADR whose body says `src/domains/{dev,memory}` after the tree became `src/apps/` is out of date even though the *decision* still stands — the interview asks whether to fix the prose (yes) without touching the decision → Spec item.
+- **Numbering collision:** two PRs each grabbed "next = 0039" (one merged as `plugin-entrypoints-share-one-source`; a second authored locally had to renumber to 0041). The interview asks which file renumbers and confirms the inbound-ref fixups → Spec item.
+- **Structural / controversial:** a decision recorded under unresolved disagreement, or one whose implementation never landed — the interview confirms whether it's still the intent; if it needs real engineering to reconcile, it becomes the load-bearing slice of the Spec.
+
+### Composition map
+
+| Pass | Reuses |
+|---|---|
+| 1 Lint | filesystem reads against `origin/HEAD` + `start/ADR-FORMAT.md` conventions; Memory contradiction reads when graph mode is on |
+| 2 Reconcile | `/start` interview discipline (one `Q##` per turn, branches + recommend) |
+| 3 Group | Memory graph communities (optional) for clustering |
+| 4 Propagate | `/wiki lint` + `/wiki ingest`; `memory_supersede` / Memory provenance reads |
+| 5 Emit Spec | `/to-spec` (format, labels, Human Decisions capture) → later `/to-tickets` + `/afk` |
+
+### Boundaries
+
+- The skill **reaches agreement, then packages** — it never silently rewrites a decision, the wiki, or the graph, and never applies an ADR edit directly. Execution is a separate, scheduled step driven by the Spec.
+- Pairs with `/red-doctor` (adoption/process) and `memory:doctor` (graph health) — three doctors over different axes; this one owns **the decision record**, resolves through dialogue, and turns its debt into work.
+
+</supporting-info>

package/skills/engineering/start/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `.red/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `.red/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `.red/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/skills/engineering/start/CONTEXT-FORMAT.md

@@ -0,0 +1,77 @@
+# .red/CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A concise description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `.red/CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `.red/CONTEXT-MAP.md` at the repo root lists the contexts and how they relate. Each context's glossary lives under `.red/contexts/<name>/CONTEXT.md` — all still inside the single root `.red/`, never a nested `.red/` inside a source subtree:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./contexts/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./contexts/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./contexts/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `.red/CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `.red/CONTEXT.md` exists, single context
+- If neither exists, create a root `.red/CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.

package/skills/engineering/start/DOC-LANDING-FINALIZER.md

@@ -0,0 +1,9 @@
+# End-of-session doc-landing finalizer
+
+When a doc-writing session ends (the user stops or every reachable branch is resolved), run one end-of-session doc-landing finalizer before exiting:
+
+1. Detect modified or untracked docs in the primary checkout across the domain glossary (`.red/CONTEXT.md`, `.red/CONTEXT-MAP.md`, `.red/contexts/**`) and ADRs (`.red/adr/**`). A session with no doc changes skips the finalizer silently.
+2. If docs changed, do this first: Announce the file list and ADR numbers to the user, and accept a decline. A decline leaves the docs unlanded; the cascade gate remains the enforcement point.
+3. If accepted, land the docs through the standard docs-worktree lane: create one worktree under `.red/tmp/worktrees/docs/<slug>` from a freshly fetched `origin/{base}` (base resolved lock > pin > main), using the name pattern `docs-<YYYYMMDD>-<slug>` for the worktree slug, copy only the dirty doc files into that worktree, commit them as a `docs:`-typed change, push the branch, open a PR, merge it, and rely on the existing post-landing fast-forward to bring the local base up.
+4. Restate these safety prohibitions before landing: never commit in the primary checkout, never switch its branch, never stash, never reset.
+5. Land at most one batch PR per session.

package/skills/engineering/start/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: start
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (.red/CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+argument-hint: "[plan to grill: prose, URL, path, or empty]"
+---
+
+<what-to-do>
+
+**Run a relentless one-Q-at-a-time grilling session until every branch of the decision tree is resolved — shared understanding is the only exit condition.** Ask one question, include a recommendation with one-sentence reasoning, wait for the reply, re-evaluate, then move to the next branch.
+
+Walk down each branch of the design tree, resolving dependencies between decisions one at a time.
+
+**The loop:**
+
+1. Pick the next unresolved branch of the decision tree.
+2. Ask **one** question. Include your recommended answer with one-sentence reasoning.
+3. Wait for the user's reply. Do not stack questions, do not preempt the next one.
+4. When their answer changes the tree, re-evaluate before asking the next question.
+5. Stop when the user says stop, or when every reachable branch is resolved.
+
+## End-of-session doc-landing finalizer
+
+When the grilling session ends (the user stops or every reachable branch is resolved), run the shared end-of-session doc-landing finalizer in [DOC-LANDING-FINALIZER.md](./DOC-LANDING-FINALIZER.md) before exiting.
+
+## Boot behavior (turn 1 — first invocation only)
+
+The argument is optional. Treat it as the plan or context to grill.
+
+- **External reference** (URL or file path) → eager ingest via `/wiki ingest <ref>`. If `.red/wiki/` is not initialised, ask **once**: `Initialise /wiki to cache fetches across sessions? (y/N)`. On `y`, run `/wiki-init` then proceed. On `n`, fall back to plain `WebFetch`/`Read` into context and note in the receipt that the material is **not cached**.
+- **Inline document** (text pasted in the argument) → already in context, no fetch.
+- **Prose** (short description) → no fetch, the prose is the plan.
+- **Empty argument** → open with the literal Q01:
+
+  > **Q01:** What plan are we grilling?
+  > **Branches:** (a) paste it inline  (b) share a URL or file path  (c) describe it in a sentence
+  > **Recommend:** (a), because inline context lets us start grilling immediately.
+  > *(answer, redirect, or push back — I'll wait)*
+
+After successful ingestion, emit a **single-line receipt** then proceed to `Q01`:
+
+| Source | Receipt |
+|---|---|
+| URL | `Fetched <url> → wiki/raw/<slug>.md (<N> words).` |
+| File (md/txt) | `Read <path> → wiki/raw/<slug>.md.` |
+| File (PDF) | `Read <path> → wiki/raw/<slug>.txt (<N> pages).` |
+| Inline doc | `Got <N> words inline.` |
+| Prose | _(no receipt — proceed to Q01 immediately)_ |
+
+When wiki is **not cached** (user declined `/wiki-init`), append ` (not cached)` to the receipt.
+
+On ingestion **failure**, do not start `Q01`. Ask for an alternative:
+
+```
+Couldn't read <ref>: <reason>.
+Paste the content, point to another path, or say "skip" and we'll grill on what you describe.
+```
+
+**Hard rules — do not break these:**
+
+- ❌ Do **not** implement, write code, or run commands beyond read-only codebase exploration, except for the end-of-session doc-landing finalizer.
+- ❌ Do **not** summarise the user's answers back at them. They know what they said.
+- ❌ Do **not** propose a final plan, design doc, or Spec. This skill ends in shared understanding, not artefacts.
+- ❌ Do **not** ask more than one question per turn.
+- ❌ Do **not** fetch URLs the user only **mentions** in passing. A ref becomes a fetch only when the user explicitly asks ("look at this", "ingest X") or the next question requires its content.
+- ❌ Do **not** answer a decision yourself — an agent that answers its own questions has broken the interview.
+- ✅ **Do** look up facts in the codebase (what the code does, what names exist, how something is wired) instead of asking the human for information that is already readable in the code.
+- ✅ **Do** put every decision to the human and wait for the answer. Facts can be looked up; decisions belong to the human.
+- ✅ **Do** challenge contradictions immediately — between user statements, between user and code, between user and `.red/CONTEXT.md`.
+- ✅ **Do** update `.red/CONTEXT.md` inline the moment a term is resolved (one term → one edit → next question). This is a side effect of the interview, not a separate phase.
+- ✅ **Do** offer an ADR only when the three-condition test in `<supporting-info>` passes.
+- ✅ **Do** treat mid-grilling refs symmetrically to boot refs: when the user introduces a URL or file path at any turn, ingest via `/wiki ingest`, emit the same receipt line, then continue with the next question.
+
+**Question format template:**
+
+> **Q##:** [the question]
+> **Branches:** _(omit only when the question is genuinely open-ended)_
+>  (a) [answer option A]
+>  (b) [answer option B]
+>  [if more options, add more branches]
+> **Recommend:** (a), because [one-sentence reason].
+> *(answer, redirect, or push back — I'll wait)*
+
+Prefer enumerated branches whenever the decision space is finite — they give the user a stable handle ("ok (b) but with X tweak") and force the skill to make the choice space explicit instead of hand-waving. `Recommend:` references a branch letter when branches are listed, prose otherwise.
+
+Number every question `Q01`, `Q02`, … `Q10`, … zero-padded to 2 digits. Counter is **session-scoped** — reset on each `/start` invocation, never on user redirects.
+
+</what-to-do>
+
+<supporting-info>
+
+## Wiki integration
+
+External references (URL, PDF, md/txt) flow through the `/wiki` skill so every fetched source is cached at `.red/wiki/raw/<slug>.md` and reusable across sessions and other skills (`/diagnose`, `/afk`, `/tdd`).
+
+Behaviour summary (full contract in [`/wiki`](../../../../memory/skills/core/wiki/SKILL.md)):
+
+- URL → `WebFetch` → `.red/wiki/raw/<slug>.md` with YAML header (`url`, `fetched`, `title`).
+- Local PDF → `pdftotext` → `.red/wiki/raw/<slug>.txt`, original kept alongside.
+- Local md/txt → copied to `.red/wiki/raw/<slug>.md` if not already there.
+- Every ingest is logged at `.red/wiki/log.md`.
+
+When `.red/wiki/` is missing, `/start` prompts once to run `/wiki-init`. Decline path: plain `WebFetch`/`Read` into context, no caching, receipt marked `(not cached)`.
+
+## Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+### File structure
+
+Most repos have a single context:
+
+```
+/
+├── .red/
+│   ├── CONTEXT.md
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `.red/CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. Everything still lives under the single root `.red/` — the map lists the contexts and each one's glossary lives under `.red/contexts/<name>/`:
+
+```
+/
+├── .red/
+│   ├── CONTEXT-MAP.md                 ← lists the contexts and how they relate
+│   ├── contexts/
+│   │   ├── ordering/CONTEXT.md
+│   │   └── billing/CONTEXT.md
+│   └── adr/                           ← single root ADR sequence (all contexts)
+└── src/
+    ├── ordering/
+    └── billing/
+```
+
+Create files lazily — only when you have something to write. If no `.red/CONTEXT.md` exists, create one when the first term is resolved. If no `.red/adr/` exists, create it when the first ADR is needed.
+
+## Side-effect triggers during the interview
+
+These fire **as a consequence of grilling**. They never replace the interview loop — finish writing, then ask the next question.
+
+### Trigger: user introduces an external reference
+
+URL or file path appears in the user's message **with intent to ingest** ("look at this", "olha esse", "ingest …", or the next question clearly needs it). Hand off to `/wiki ingest <ref>`, emit the standard receipt line as a brief acknowledgement, then proceed to the next `Q##:`. Mid-grilling refs follow the same rules as boot refs — no extra opt-in once `/wiki` is initialised.
+
+### Trigger: term conflicts with the glossary
+
+When the user uses a term that conflicts with the existing language in `.red/CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Trigger: fuzzy or overloaded language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Trigger: domain relationship being asserted
+
+Stress-test with a specific scenario. Invent edge cases that force the user to be precise about the boundaries between concepts.
+
+### Trigger: user statement contradicts the code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Trigger: a term is resolved
+
+Update `.red/CONTEXT.md` right there. Don't batch. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`.red/CONTEXT.md` is a **glossary**. It is totally devoid of implementation details. Do not treat it as a spec, a scratch pad, or a repository for implementation decisions.
+
+### Trigger: a decision passes the ADR test
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+
+</supporting-info>