@rune-kit/rune 2.15.0 → 2.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -83,7 +83,19 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
83
83
 
84
84
  ---
85
85
 
86
- ## What's New (v2.15.0 — Second Opinion + Cross-Provider + Routing Clarity)
86
+ ## What's New (v2.16.0 — Skill Enrichment + Triage Workflow + Output Modes)
87
+
88
+ - **`debug` v1.2.0 — Step 0: Build Feedback Loop** — 10-rank ladder (failing test → curl → CLI snapshot → headless browser → trace replay → throwaway harness → fuzz → bisection → differential → HITL script). Codifies "the loop is the speed limit" — a fast deterministic pass/fail signal turns debugging into mechanical bisection. Skip if repro is already < 5s and deterministic; > 10 min loop construction triggers 3-Fix Escalation (architecture is the problem).
89
+ - **`plan` v1.6.0 — Vertical Slice Mode** — tracer-bullet task decomposition. Each task = end-to-end path through schema + API + UI + test, demoable on its own. AFK / HITL classification. Stops "horizontal layer" planning that blocks on the slowest layer.
90
+ - **`context-engine` v1.2.0 — Caveman Output Mode** — auto-activates on context ORANGE / RED (or `/caveman`). Strips filler / articles / hedging / pleasantries while preserving full technical accuracy (~75% output reduction). Auto-clarity exceptions for security warnings, destructive-action confirmations, multi-step sequences, root-cause diagnosis.
91
+ - **`ba` v0.13.0 — Synthesis Mode + Out-of-Scope WRITE** — when prior conversation has rich context (pasted spec, > 1000 words, continuation session), extract Requirements Document with source citations and confirm instead of re-interviewing. Step 1.6 closes the `.out-of-scope/` write loop: explicit mid-elicitation rejections produce a durable `.out-of-scope/<slug>.md` record so future sessions don't re-litigate.
92
+ - **`context-pack` v0.3.0 — Agent Brief Variant** — durable handoff format for AFK agents (issue tracker queues, autopilot multi-session work). Behavioral over procedural; type names over file:line. Survives codebase drift between handoff and execution.
93
+ - **`review-intake` v1.3.0 — Issue Triage Mode** — new mode for issue tracker items (PR Review remains default). State machine: needs-triage → needs-info / ready-for-agent / ready-for-human / wontfix. Repro-first HARD-GATE for bugs (calls `debug` Step 0 if multi-component). Vague issues route to `ba` Synthesis Mode for grilling. AGENT-BRIEF emission for `ready-for-agent`.
94
+ - **5 new mesh signals** — `output.density.set`, `triage.classified`, `agent.brief.ready`, `outofscope.recorded` + `EXTERNAL_TRIGGER_SIGNALS` whitelist concept (symmetric to `INTENTIONAL_BROADCAST_SIGNALS`).
95
+ - **Validator cleanups** — `validate-skills.js` Done-When regex relaxed (scope-aware, supports mode-based subsections); 9 pre-existing validation errors cleaned. `validate-signals.js` gained `EXTERNAL_TRIGGER_SIGNALS` set.
96
+ - **Provenance** — second graft pass from [`mattpocock/skills`](https://github.com/mattpocock/skills) (MIT). Round 1 had silently grafted 7 patterns (improve-architecture, CONTEXT.md, design-it-twice, zoom-out, oracle-mode, grill, out-of-scope); Round 2 + 2b documented + extended.
97
+
98
+ ### Previous (v2.15.0 — Second Opinion + Cross-Provider + Routing Clarity)
87
99
 
88
100
  - **`adversary` v0.2.0 — Mode: oracle** — when `agent.stuck` fires from `debug` (3 disproved hypotheses) or `fix` (2+ failed attempts), oracle-mode dispatches a stateless second-model pass with explicit "no prior context" framing. Bundle format is regex-validated (`[SYSTEM]` invariant role-priming + `[USER]` template + `### File N`), token-capped (100k bundle, 4k per file, 12 files max), citation-required reply contract. Secrets auto-redacted. Breaks the confirmation-bias loop that scout's zoom-out (structural pivot) cannot.
89
101
  - **`session-bridge` v0.8.0 — Detach Mode** — async escalation primitive. Heavy-model second-opinion calls (1-10 min wall time) no longer block the primary agent. `.rune/oracle-pending/<sessionId>.json` is the rendezvous file; idempotent dispatch (bundleHash-keyed); 10min default timeout; 24h orphan cleanup on session start. `cook` Phase 4 and `team` Phase 3 reattach via filesystem poll between adjacent tasks.
@@ -12,10 +12,12 @@
12
12
 
13
13
  import assert from 'node:assert';
14
14
  import { readdirSync, readFileSync, statSync } from 'node:fs';
15
- import { join, resolve } from 'node:path';
15
+ import { dirname, join, resolve } from 'node:path';
16
16
  import { describe, test } from 'node:test';
17
+ import { fileURLToPath } from 'node:url';
17
18
 
18
- const SKILLS_DIR = resolve(import.meta.dirname, '../..', 'skills');
19
+ const __dirname = dirname(fileURLToPath(import.meta.url));
20
+ const SKILLS_DIR = resolve(__dirname, '../..', 'skills');
19
21
 
20
22
  function listSkills() {
21
23
  return readdirSync(SKILLS_DIR).filter((name) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rune-kit/rune",
3
- "version": "2.15.0",
3
+ "version": "2.16.0",
4
4
  "description": "63-skill mesh for AI coding assistants — runtime auto-discipline via native hooks (Claude/Cursor/Windsurf/Antigravity), 5-layer architecture, 215+ connections, multi-platform compiler.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -16,6 +16,7 @@
16
16
  "format": "biome format --write .",
17
17
  "ci": "biome check . && node --test compiler/__tests__/*.test.js scripts/__tests__/*.test.js && node compiler/bin/rune.js doctor",
18
18
  "version-check": "node scripts/version-sync-check.js",
19
+ "version-bump": "node scripts/bump-version.js",
19
20
  "prepublishOnly": "node scripts/version-sync-check.js"
20
21
  },
21
22
  "keywords": [
@@ -3,12 +3,12 @@ name: ba
3
3
  description: "Business Analyst agent. Use when starting a new feature requiring requirements elicitation BEFORE plan or cook. Asks probing questions, identifies hidden requirements, maps stakeholders, defines scope boundaries, and produces a structured Requirements Document that plan and cook consume."
4
4
  metadata:
5
5
  author: runedev
6
- version: "0.11.0"
6
+ version: "0.13.0"
7
7
  layer: L2
8
8
  model: opus
9
9
  group: creation
10
- tools: "Read, Glob, Grep"
11
- emit: outofscope.match
10
+ tools: "Read, Write, Glob, Grep"
11
+ emit: outofscope.match, outofscope.recorded
12
12
  ---
13
13
 
14
14
  # ba
@@ -73,7 +73,26 @@ If Refactor → light version (Step 1 + Step 4 only). Skip Steps 2, 2.5, 3, 5, 6
73
73
 
74
74
  If existing codebase → invoke `rune:scout` for context before proceeding.
75
75
 
76
- ### Step 1.5Out-of-Scope Match Check
76
+ ### Step 1.4Synthesis Trigger Check
77
+ <MUST-READ path="references/synthesis-mode.md" trigger="when prior conversation already contains rich requirement context (pasted spec, > 1000 words discussion, continuation session, filled issue template)"/>
78
+
79
+ Before proceeding to elicitation, check whether the requirements are **already in context**. Re-asking what the user already told you is the second-most expensive bug.
80
+
81
+ Activate **Synthesis Mode** instead of standard elicitation if ANY of:
82
+
83
+ | Signal | Threshold |
84
+ |--------|-----------|
85
+ | User pasted a spec / PRD / brief | > 200 words describing the feature |
86
+ | Conversation has > 1000 words on this feature | Sufficient context already gathered |
87
+ | User said "synthesize" / "I already explained" / "just write the spec" | Explicit synthesis request |
88
+ | Continuation — `.rune/features/<name>/requirements.md` exists with prior answers | Re-elicitation would duplicate |
89
+ | Issue tracker has filled-in template (problem, story, acceptance criteria) | Source already structured |
90
+
91
+ In Synthesis Mode: extract answers from existing context, draft the Requirements Document with **source citations** for every section, then **confirm** rather than re-interview. Ask follow-ups ONLY on the 1-2 dimensions with genuine gaps. Skip steps 2, 2.5 if all 5 dimensions are filled or partial-but-acceptable.
92
+
93
+ Workflow detail + anti-patterns: [references/synthesis-mode.md](references/synthesis-mode.md).
94
+
95
+ ### Step 1.5 — Out-of-Scope Match Check (READ)
77
96
 
78
97
  Before any elicitation, check whether the request matches a concept previously rejected.
79
98
 
@@ -99,6 +118,50 @@ If verdict is exact-match AND user accepts the prior rejection → end the BA se
99
118
 
100
119
  Format reference: [references/out-of-scope-format.md](references/out-of-scope-format.md).
101
120
 
121
+ ### Step 1.6 — Mid-Elicitation Reject WRITE Path
122
+
123
+ If the user **explicitly rejects** the feature at any point during elicitation (Steps 2-3) — common phrases: "scrap it", "actually nah, don't build this", "we won't do this", "kill the feature", "drop it" — STOP elicitation and **write a `.out-of-scope/<slug>.md` record** before ending the session.
124
+
125
+ Without this WRITE path, oral rejections vanish — the next session re-asks the same questions and the user has to re-reject. Step 1.5 (READ) only catches matches against existing files; Step 1.6 (WRITE) is what produces those files in the first place.
126
+
127
+ <HARD-GATE>
128
+ Mid-elicitation rejection MUST produce a `.out-of-scope/<slug>.md` file before session end.
129
+ A rejection without a written record is a rejection that didn't happen.
130
+ </HARD-GATE>
131
+
132
+ **Procedure**:
133
+
134
+ 1. **Confirm rejection is durable, not deferral**. Ask one clarifier:
135
+ > "Just to record this correctly: is this **out of scope** (project doesn't want this), or **deferred** (not now but maybe later)? Out-of-scope gets recorded so we don't re-litigate; deferred goes to backlog instead."
136
+
137
+ - If **deferred** → route to backlog (no `.out-of-scope/` write), end session with a one-line note
138
+ - If **out-of-scope** → continue to step 2
139
+
140
+ 2. **Capture the durable reason**. Ask:
141
+ > "What's the reason this is out of scope? (project scope, technical constraint, strategic decision — not a temporary circumstance)"
142
+
143
+ If the user gives a temporary reason ("we're busy"), reframe: "That's a deferral — should I route to backlog instead?"
144
+
145
+ 3. **Generate slug** (kebab-case, ≤40 chars, recognizable without opening the file).
146
+
147
+ 4. **Lexical-similarity check**: `Glob` `.out-of-scope/*.md`, parse each frontmatter's `concept` + `aliases`, compute overlap. If any existing concept has ≥0.7 overlap → APPEND to that file's `prior_requests` list and mark `rejected_by: ba` for this round. Do NOT create a duplicate.
148
+
149
+ 5. **Write the file** using the format in [`references/out-of-scope-format.md`](references/out-of-scope-format.md):
150
+ - YAML frontmatter (`concept`, `aliases`, `decision: rejected`, `rejected_at`, `rejected_by: ba`, `prior_requests`, optional `revisit_if`)
151
+ - Markdown body: concept name, "Why out of scope" (substantive reasoning from step 2), "What would change our mind" (if user volunteered signals)
152
+
153
+ 6. **Emit `outofscope.recorded`** signal carrying `{slug, rejected_by: ba, prior_requests_count}` so downstream skills know a new rejection landed.
154
+
155
+ 7. **End BA session** with one-line summary:
156
+ > "Recorded as out of scope in `.out-of-scope/<slug>.md`. Future similar requests will surface this. Override anytime by editing the file."
157
+
158
+ **When NOT to write**:
159
+
160
+ - User merely defers ("not now") → backlog, not `.out-of-scope/`
161
+ - User rejects a single requirement within a larger feature → adjust requirements doc Boundaries section, don't write a whole rejection file (the feature is still in scope)
162
+ - Bug rejections (already fixed, not reproducible) → not BA's job; route to incident or close the issue
163
+ - The match was already exact (≥0.8) and Step 1.5 surfaced it — user accepting the prior rejection just appends to `prior_requests` of the existing file (handled in Step 1.5 path)
164
+
102
165
  ### Step 2.0 — Explore-First Pre-Check (HARD-GATE)
103
166
 
104
167
  Before emitting ANY of the 5 elicitation questions, run the 4-item pre-check on each intended question:
@@ -663,6 +726,11 @@ Known failure modes for this skill. Check these before declaring done.
663
726
  | User asserts behavior; agent records user's version without grep verification | HIGH | Step 2.6 HARD-GATE: every "the system does X" assertion gets grep'd; conflicts surface to user before recording |
664
727
  | Silently re-defining an existing CONTEXT.md term | HIGH | Step 7.5 conflict gate: ≥0.7 overlap → user chooses merge/rename/keep-distinct |
665
728
  | Auto-creating an empty CONTEXT.md when no terms emerged | LOW | Lazy creation rule: only write when there's a non-trivial term to record |
729
+ | Mid-elicitation rejection ("scrap it") that ends the session without writing `.out-of-scope/` | CRITICAL | Step 1.6 HARD-GATE: explicit rejection MUST produce `.out-of-scope/<slug>.md` before session end — oral rejections vanish, force re-litigation next session |
730
+ | Writing `.out-of-scope/` for a deferral instead of routing to backlog | MEDIUM | Step 1.6 procedure step 1: confirm "out of scope" vs "deferred" — temporary reasons go to backlog, not the rejection KB |
731
+ | Running 5-question elicitation when conversation already contains rich context | HIGH | Step 1.4: synthesis-trigger check fires before Step 2 — pasted spec / >1000 words / continuation / explicit "synthesize" → switch to Synthesis Mode (extract + cite + confirm), don't re-interview |
732
+ | Synthesizing requirements without source citations | HIGH | Synthesis Mode requires citing source for every dimension (user message N, pasted doc, continuation file). User cannot verify interpretation without citations |
733
+ | Auto-handoff to plan after synthesis without explicit user "go"/"locked" confirmation | HIGH | Synthesis is interpretation, not transcription. Without explicit confirmation, drift becomes a downstream bug |
666
734
  | Asking inferable questions ("what stack are you using?") without first checking package.json | HIGH | Step 2.0 HARD-GATE — every question requires prior tool-call evidence (Read/Glob/Grep) or explicit unavailability declaration |
667
735
  | Re-asking a question already answered earlier in the conversation | MEDIUM | Step 2.0 check 4 — cache and reuse, never re-ask |
668
736
 
@@ -0,0 +1,105 @@
1
+ # Synthesis Mode (Chat → Requirements Without Re-Interview)
2
+
3
+ When the conversation already contains rich context — user described the feature in detail, pasted a spec, or worked through requirements iteratively — running the 5 Questions again wastes attention and breaks rapport. Synthesis mode extracts the Requirements Document from existing context, then **confirms** rather than re-interviewing.
4
+
5
+ > Re-asking what the user already told you is the second-most expensive bug after wrong requirements. The first is wrong requirements shipped correctly.
6
+
7
+ ## When to use synthesis (skip the 5 Questions)
8
+
9
+ Trigger synthesis instead of elicitation if ANY of:
10
+
11
+ | Signal | Threshold |
12
+ |--------|-----------|
13
+ | User pasted a spec / PRD / brief | Any document > 200 words describing the feature |
14
+ | Conversation has > 1000 words discussing this feature | Sufficient context already gathered |
15
+ | User said "I already explained — just write the spec" / "synthesize" / "build the requirements" | Explicit synthesis request |
16
+ | Session is a continuation — prior session captured most answers in `.rune/features/<name>/requirements.md` | Re-elicitation would duplicate |
17
+ | Issue tracker / external ticket has filled-in template (problem, user story, acceptance criteria) | Source already structured |
18
+
19
+ If NONE match → fall back to standard elicitation (Step 2 — 5 Questions).
20
+
21
+ ## Synthesis workflow
22
+
23
+ ### Step S1 — Sweep context
24
+
25
+ Pull from in this order:
26
+ 1. The current conversation (every message from user, in order)
27
+ 2. Pasted documents (spec, PRD, ticket body)
28
+ 3. `.rune/features/<feature>/requirements.md` if continuation
29
+ 4. Codebase signals (only if needed for inference — `package.json`, `README.md`)
30
+
31
+ ### Step S2 — Extract answers to the 5 dimensions
32
+
33
+ Map existing context onto the same 5 dimensions used in elicitation:
34
+
35
+ | Dimension | Where to look |
36
+ |-----------|---------------|
37
+ | **WHO** (user, technical level, surrounding workflow) | "users who...", personas, role mentions |
38
+ | **WHAT** (specific outcome, definition of done) | Acceptance criteria, "should", "must", success metrics |
39
+ | **WHY** (problem, consequence of not building) | "because", "to avoid", problem statement, motivation |
40
+ | **BOUNDARIES** (out of scope) | "not", "won't", "later", "v2", "future" |
41
+ | **CONSTRAINTS** (tech, perf, security, deadline) | Tech stack mentions, perf targets, deadlines, integrations |
42
+
43
+ For each dimension, mark **filled** | **partial** | **gap**.
44
+
45
+ ### Step S3 — Identify ONLY the gaps
46
+
47
+ If all 5 dimensions are **filled** or **partial-but-acceptable** → skip directly to Step S4. No questions.
48
+
49
+ If 1-2 dimensions are **gap** → ask ONLY those questions, single round, multiple-choice format. Never ask all 5 over again.
50
+
51
+ If 3+ dimensions are **gap** → synthesis context wasn't actually rich; fall back to standard elicitation (Step 2).
52
+
53
+ ### Step S4 — Draft Requirements Document
54
+
55
+ Use the standard Requirements Document format (same as elicitation output). For every dimension, cite the source:
56
+
57
+ ```markdown
58
+ ### Who
59
+ [Synthesized statement]
60
+
61
+ > _Source: user message at [timestamp/turn], "..."_
62
+ ```
63
+
64
+ Citations are mandatory in synthesis mode — they let the user verify nothing was misread or invented.
65
+
66
+ ### Step S5 — Confirm, don't re-elicit
67
+
68
+ Present the Requirements Document with this exact framing:
69
+
70
+ > "I synthesized requirements from our conversation. **Read each section** — if anything is wrong or missing, tell me which line. If it's correct, say 'go' and I'll lock it for plan."
71
+
72
+ Wait for explicit confirmation. Do NOT auto-proceed to plan handoff.
73
+
74
+ User responses:
75
+ - `"go"` / `"locked"` / `"correct"` → emit Requirements Document, hand off to plan
76
+ - `"section X is wrong"` → revise that section only, re-confirm
77
+ - `"add Y"` / `"actually..."` → treat as additional gap; ask multiple-choice if specific, otherwise add to Open Questions
78
+
79
+ ## Anti-patterns
80
+
81
+ | Anti-pattern | Why it fails |
82
+ |--------------|--------------|
83
+ | Running 5 Questions after user pasted a 500-word spec | Burns trust — user already gave you the answers |
84
+ | Synthesizing without citations | User can't verify; one misread becomes a downstream bug |
85
+ | Auto-proceeding to plan after synthesis without confirmation | Synthesis is interpretation, not transcription. Confirmation prevents drift. |
86
+ | Asking all 5 questions even when 4 dimensions are filled | Defeats the purpose. Ask 1, not 5. |
87
+ | Treating "looks fine" as confirmation | Need explicit "go" or "locked" — vague approval = ambiguous handoff |
88
+
89
+ ## Integration with Step 1 (Intake & Classify)
90
+
91
+ After classifying requirement type, branch:
92
+
93
+ ```
94
+ Feature Request | Greenfield | Integration:
95
+ → Check synthesis triggers
96
+ → All filled (S2): synthesize + confirm (S4-S5)
97
+ → Partial (1-2 gaps): synthesize + targeted questions (S3-S5)
98
+ → Mostly empty (3+ gaps): fall back to standard elicitation (Step 2)
99
+ Bug Fix:
100
+ → Skip BA entirely
101
+ Refactor:
102
+ → Light BA (synthesis usually fits)
103
+ ```
104
+
105
+ Synthesis mode is **opt-in via context detection**, not via user flag — the trigger is "rich context exists", not "user asked for it". The user shouldn't have to know which mode is active.
@@ -4,12 +4,12 @@ description: "Context window management. Auto-triggered when context is filling
4
4
  user-invocable: false
5
5
  metadata:
6
6
  author: runedev
7
- version: "1.1.0"
7
+ version: "1.2.0"
8
8
  layer: L3
9
9
  model: haiku
10
10
  group: state
11
11
  tools: "Read, Glob, Grep"
12
- emit: context.preview
12
+ emit: context.preview, output.density.set
13
13
  ---
14
14
 
15
15
  # context-engine
@@ -103,9 +103,11 @@ Emit recommendation to the calling orchestrator:
103
103
 
104
104
  Identify the next safe boundary (end of current loop iteration, end of current file being processed) and flag it.
105
105
 
106
+ **Auto-activate Caveman Output Mode** (see `references/caveman-mode.md`) — emit `output.density.set` with `mode=caveman, scope=session, source=context-orange`. Reduces output token cost ~75% with no information loss; persists until /compact returns context to GREEN. Manual override (`/caveman` or "stop caveman") always wins.
107
+
106
108
  ### Step 5 — If RED
107
109
 
108
- Immediately trigger state save via `rune:session-bridge` (Save Mode) before any compaction occurs.
110
+ Immediately trigger state save via `rune:session-bridge` (Save Mode) before any compaction occurs. If caveman mode was not already active from ORANGE, emit `output.density.set` with `mode=caveman, scope=session, source=context-red` now.
109
111
 
110
112
  Pass to session-bridge:
111
113
  - Current task and phase description
@@ -377,6 +379,33 @@ When Context Budget Warning fires, append to Context Health report:
377
379
  - **Recommendation**: Disable [server] to save ~[N]k tokens
378
380
  ```
379
381
 
382
+ ## Output Density Mode (Caveman)
383
+ <MUST-READ path="references/caveman-mode.md" trigger="when context reaches ORANGE/RED OR user says 'caveman'/'be brief'/'less tokens'"/>
384
+
385
+ Caveman is a terse output mode that strips filler, articles, hedging, and pleasantries while preserving full technical accuracy. ~75% output token reduction with no information loss when applied per the rules in `references/caveman-mode.md`.
386
+
387
+ ### Activation triggers
388
+
389
+ | Trigger | Source | Persistence |
390
+ |---------|--------|-------------|
391
+ | Context health = ORANGE or RED | Auto from Step 4-5 above | Until `/compact` returns to GREEN |
392
+ | User says "caveman" / "/caveman" / "be brief" / "less tokens" | Explicit user signal | Until "stop caveman" / "normal mode" |
393
+ | Per-workstream override (e.g., `team` worker exceeds output budget) | Per-workstream scope | Scoped to that workstream only |
394
+
395
+ Auto-activation emits `output.density.set` signal carrying `{mode: caveman, scope, source}`. Orchestrators (cook, team, rescue) honor the signal for the duration of their session.
396
+
397
+ ### Auto-clarity exceptions (revert ONE response, then resume)
398
+
399
+ - Security warnings (data loss, credential exposure)
400
+ - Confirmations of irreversible actions (`rm -rf`, force-push, drop table, prod deploy)
401
+ - Multi-step sequences where fragment ordering risks misreading
402
+ - User says "explain" / "clarify" / repeats the same question
403
+ - Root-cause diagnosis where cause-and-effect chains need grammatical structure
404
+
405
+ ### Anti-pattern
406
+
407
+ Caveman in the FIRST response of a task. The user can't calibrate severity from a single output yet — verbose first response is fine. Caveman starts on response 2+.
408
+
380
409
  ## Mode: preview (v1.1.0)
381
410
 
382
411
  Pre-flight cost check for expensive escalations. Caller (`adversary` oracle-mode, `team` workstream spawn, `review` multi-file, `audit` cross-pack) MUST emit `context.preview` BEFORE building the bundle, so context-engine can estimate token cost and gate the dispatch against a per-caller threshold.
@@ -477,6 +506,10 @@ Known failure modes for this skill. Check these before declaring done.
477
506
  | Mid-loop compaction without flushing state first | HIGH | session-bridge + neural-memory MUST run before compaction — losing unsaved decisions is worse than hitting context limit |
478
507
  | (preview) Caller bundles before requesting preview | HIGH | Constraint 4 enforces order; reject preview-after-build calls with explicit error |
479
508
  | (preview) Estimated tokens off by 2x for non-English content | LOW | Document calibration in `references/preview-gate.md`; safe both directions (block-too-eager or block-too-late but hard cap at dispatch saves us) |
509
+ | Caveman activated in first response of a task | MEDIUM | First response = user calibration baseline. Verbose first; caveman from response 2+ (see `references/caveman-mode.md`) |
510
+ | Caveman compresses code blocks or error messages | CRITICAL | Caveman strips filler ONLY. Code, errors, paths, technical terms stay verbatim. Compression of those = wrong fix |
511
+ | Caveman drift back to verbose mid-session | MEDIUM | Once activated, persists every response until explicit deactivation. Drift defeats the token savings |
512
+ | Caveman during destructive-action confirmation | HIGH | Auto-clarity exception: revert ONE response for security/irreversible-action confirmations, then resume |
480
513
 
481
514
  ## Done When
482
515
 
@@ -0,0 +1,107 @@
1
+ # Caveman Output Mode
2
+
3
+ A terse output mode that strips filler, articles, and pleasantries while preserving full technical accuracy. Reduces output token cost by ~75% with no information loss when applied correctly.
4
+
5
+ > "All technical substance stays. Only fluff dies."
6
+
7
+ ## When to activate
8
+
9
+ | Trigger | Source | Persistence |
10
+ |---------|--------|-------------|
11
+ | User says "caveman", "caveman mode", "be brief", "less tokens" | Explicit user signal | Until user says "stop caveman" / "normal mode" |
12
+ | Context health = ORANGE or RED | Auto from `context-engine` Step 4-5 | Until context returns to GREEN after compaction |
13
+ | Output budget exceeded for a workstream (e.g., team parallel worker) | Per-workstream override | Scoped to that workstream |
14
+
15
+ Once active, **every response stays in caveman mode** until explicit deactivation. No drift back to verbose mid-session.
16
+
17
+ ## What dies
18
+
19
+ - Articles: `a`, `an`, `the`
20
+ - Filler: `just`, `really`, `basically`, `actually`, `simply`, `essentially`, `you can see that`
21
+ - Pleasantries: `Sure!`, `Certainly`, `Of course`, `Happy to help`, `Great question`, `Let me`
22
+ - Hedging: `I think`, `it seems`, `probably`, `might want to consider`
23
+ - Connective bloat: `In order to`, `with regard to`, `at this point in time`
24
+ - Restating the user's question
25
+
26
+ ## What stays (untouched)
27
+
28
+ - Code blocks — exact, unmodified
29
+ - Error messages — quoted verbatim
30
+ - Technical terms — full names, no abbreviation if ambiguous
31
+ - File paths and identifiers
32
+ - Numbers, units, version strings
33
+
34
+ ## Techniques allowed
35
+
36
+ | Technique | Example |
37
+ |-----------|---------|
38
+ | Sentence fragments | `Fixed.` instead of `I have fixed it.` |
39
+ | Short synonyms | `big` not `extensive`, `use` not `utilize` |
40
+ | Common abbreviations | `DB`, `auth`, `config`, `req`/`res`, `fn`, `impl`, `repo`, `env` |
41
+ | Arrow notation for causality | `null input → crash at line 42 → fix: validate before parse` |
42
+ | Skeleton pattern | `[thing] [action] [reason]. [next step].` |
43
+ | Bullet over paragraph | List 3 things instead of writing a paragraph about them |
44
+
45
+ ## Auto-clarity exceptions (revert temporarily)
46
+
47
+ Drop caveman for ONE response, then resume. Triggers:
48
+
49
+ | Situation | Why revert |
50
+ |-----------|------------|
51
+ | Security warning (data loss, credential exposure, destructive command) | Fragments risk underweighting severity |
52
+ | Confirming an irreversible action (`rm -rf`, force-push, drop table, deploy to prod) | User must understand what they're approving |
53
+ | Multi-step sequence where order matters | Fragment ordering can be misread |
54
+ | User says "explain" / "clarify" / repeats the same question | They want more, not less |
55
+ | Diagnosis of a hard bug — root cause needs grammatical structure to be unambiguous | Cause-and-effect chains break in fragments |
56
+
57
+ ## Token savings (calibration)
58
+
59
+ | Mode | Sample output for "explain X" | Tokens |
60
+ |------|-------------------------------|--------|
61
+ | Verbose | `Sure! So basically, the X function is responsible for handling the case where...` | ~80 |
62
+ | Caveman | `X handles [case]. Fails on [edge]. Fix: [action].` | ~20 |
63
+
64
+ Expect 60-80% reduction on conversational responses. Code/docs/error messages are unaffected (they were already pure information).
65
+
66
+ ## Examples
67
+
68
+ ### Verbose
69
+ > Sure! So I've taken a look at the auth middleware and it seems like the issue might be that the token validation function is being called before the token is actually parsed. Basically what's happening is that we're trying to validate something that doesn't exist yet, which is causing the null reference error you're seeing.
70
+
71
+ ### Caveman
72
+ > Auth middleware: `validate(token)` called before parse → null ref. Fix: parse first, then validate.
73
+
74
+ ### Verbose
75
+ > Great question! Let me explain how this works. The retry logic is implemented using exponential backoff, which means that each retry waits longer than the previous one.
76
+
77
+ ### Caveman
78
+ > Retry uses exponential backoff. Each attempt waits longer than last.
79
+
80
+ ### Caveman with security exception
81
+ > Caveman normally — but for this one: **Warning**: `git push --force` will overwrite the remote `main` branch. This destroys any commits other developers have pushed in the meantime. Confirm explicitly before I run it.
82
+ >
83
+ > [next response resumes caveman]
84
+
85
+ ## Integration with context-engine
86
+
87
+ Auto-activation flow (Step 4 ORANGE / Step 5 RED):
88
+
89
+ ```
90
+ 1. context-engine detects ORANGE/RED
91
+ 2. Emit advisory: "Context [X]%. Activating caveman output mode."
92
+ 3. Set session flag: caveman_active = true
93
+ 4. All subsequent responses honor caveman rules
94
+ 5. On /compact + return to GREEN: emit "Caveman mode released" — back to normal
95
+ ```
96
+
97
+ Manual override always wins: if user says "/caveman" while GREEN, activate; if user says "stop caveman" while RED, respect it (but emit warning that context is critical).
98
+
99
+ ## Anti-patterns
100
+
101
+ | Anti-pattern | Why it fails |
102
+ |--------------|--------------|
103
+ | Compressing code or error messages | Information loss → wrong fix |
104
+ | Using rare abbreviations the user might not know | Saves tokens, costs comprehension |
105
+ | Caveman during security/destructive confirmation | User skips reading because format signals "low importance" |
106
+ | Drifting back to verbose after a few turns | Mode must persist — drift defeats the purpose |
107
+ | Caveman in the FIRST response of a task | User can't calibrate severity from the first output yet — verbose first response is fine |
@@ -4,7 +4,7 @@ description: "Creates structured handoff briefings between agents. Use when dele
4
4
  user-invocable: false
5
5
  metadata:
6
6
  author: runedev
7
- version: "0.2.0"
7
+ version: "0.3.0"
8
8
  layer: L3
9
9
  model: haiku
10
10
  group: state
@@ -134,6 +134,24 @@ When a parent agent delegates work to a subagent, critical context gets lost —
134
134
 
135
135
  Full template + worked examples: [references/brief-template.md](references/brief-template.md).
136
136
 
137
+ ## Variant: Agent Brief (Async / Durable Handoff)
138
+ <MUST-READ path="references/agent-brief.md" trigger="when handing off to an AFK agent, an issue tracker queue, autopilot, or any receiver that may execute hours/days later"/>
139
+
140
+ The standard packet (above) is for **immediate** sub-agent dispatch in the same session. When the handoff target is async — issue tracker, scheduled cron agent, `rune:autopilot` (Pro) for multi-session work, or any receiver that may execute hours or days later — switch to the **agent brief** variant.
141
+
142
+ Agent brief adds two durability principles on top of the standard packet:
143
+
144
+ 1. **Durability over precision** — describe interfaces, types, and behavioral contracts. NEVER reference line numbers in narrative. File paths only in `### Files Touched` (locator-only, may rename).
145
+ 2. **Behavioral, not procedural** — describe WHAT the system should do, not HOW to implement it. The async agent will explore the codebase fresh.
146
+
147
+ Additional BLOCK-tier checks for agent briefs (on top of the standard smell tests):
148
+ - `**Category:**` line present (`bug` / `enhancement` / `refactor`)
149
+ - Both `**Current behavior:**` and `**Desired behavior:**` sections present
150
+ - Acceptance criteria are independently testable (each pass/fail alone)
151
+ - `**Key interfaces:**` names types/functions, not file paths
152
+
153
+ Full template + worked examples: [references/agent-brief.md](references/agent-brief.md).
154
+
137
155
  ## Returns
138
156
 
139
157
  | Field | Type | Description |
@@ -169,6 +187,9 @@ Full template + worked examples: [references/brief-template.md](references/brief
169
187
  | Missing Type Surface section for non-trivial task | HIGH | Mandatory for tasks >= 300 tokens; the durable spine is what survives file moves |
170
188
  | Missing Out of scope section | HIGH | Always required (even "(none)"); completion-gate rejects briefs without it |
171
189
  | Acceptance Criteria using shape verbs ("is defined", "has property") | MEDIUM | Rewrite to behavior verbs from the whitelist |
190
+ | Async handoff (issue tracker / autopilot / scheduled run) emitted as standard packet | HIGH | Switch to agent-brief variant (`references/agent-brief.md`) — standard packet rots when receiver runs hours/days later. Brief adds durability rules: behavioral not procedural, no line numbers in narrative |
191
+ | Agent brief with file:line references in narrative ("change `auth.ts:42`") | CRITICAL | Brief BLOCK gate — line numbers go stale on first edit. Reference type names, function signatures, contracts instead. File paths only in `### Files Touched` |
192
+ | Agent brief without `**Current behavior:**` AND `**Desired behavior:**` split | HIGH | Brief BLOCK gate — without the delta explicit, async agent cannot verify when work is done |
172
193
 
173
194
  ## Self-Validation
174
195
 
@@ -0,0 +1,194 @@
1
+ # Agent Brief (Durable Handoff Variant)
2
+
3
+ A context-pack variant designed for **async handoff to AFK agents** — one-shot agents that pick up work hours or days later, without the live conversation context. The standard context-pack is for immediate sub-agent dispatch; the agent brief is for the handoff that may sit in a queue (issue tracker, task board, scheduled run).
4
+
5
+ > The standard packet is a system prompt. The agent brief is a contract. Both must survive without the originating conversation; the brief must also survive code drift.
6
+
7
+ ## When to use agent-brief vs standard packet
8
+
9
+ | Variant | Use when |
10
+ |---------|----------|
11
+ | **Standard packet** (`Output Format` in SKILL.md) | Immediate dispatch — sub-agent runs in the same session, < 1 hour delay, codebase will not drift |
12
+ | **Agent brief** (this file) | Async dispatch — task posted to issue tracker, scheduled run, or external worker. May sit for days. Codebase may rename/move files in the meantime. |
13
+
14
+ Both share the same compression discipline. Agent brief adds **durability rules** to survive drift.
15
+
16
+ ## The two extra principles
17
+
18
+ ### 1. Durability over precision
19
+
20
+ The brief may execute days later. Files renamed, moved, refactored. Write so the brief stays useful.
21
+
22
+ | Do | Don't |
23
+ |----|-------|
24
+ | Describe interfaces, types, behavioral contracts | Reference file paths in narrative ("change `src/auth/login.ts`") |
25
+ | Name specific types, function signatures, config shapes the agent should look for | Reference line numbers ("on line 42") |
26
+ | Describe what to find ("the function that validates JWT tokens") | Assume current implementation structure stays the same |
27
+
28
+ File paths can appear in `### Files Touched` (locator-only, may rename). They cannot appear in narrative.
29
+
30
+ ### 2. Behavioral, not procedural
31
+
32
+ Describe **what** the system should do, not **how** to implement it. The agent will explore the codebase fresh and make implementation decisions.
33
+
34
+ | Behavioral (good) | Procedural (bad) |
35
+ |-------------------|------------------|
36
+ | `SkillConfig` should accept an optional `schedule: CronExpression` field | Open `src/types/skill.ts` and add a `schedule` field on line 42 |
37
+ | When user runs `/triage` with no args, show a summary of issues needing attention | Add a switch statement in the main handler |
38
+ | Truncated descriptions end at last word boundary before 1024 chars and append `...` | Modify the `truncate()` function to check word boundaries |
39
+
40
+ ## Template
41
+
42
+ ```markdown
43
+ ## Agent Brief
44
+
45
+ **Category:** bug | enhancement | refactor
46
+ **Summary:** one-line description of what needs to happen
47
+
48
+ **Current behavior:**
49
+ What happens now. For bugs: the broken behavior. For enhancements: the status quo.
50
+
51
+ **Desired behavior:**
52
+ What should happen after the work is complete. Be specific about edge cases and error conditions.
53
+
54
+ **Key interfaces:**
55
+ - `TypeName` — what needs to change and why
56
+ - `functionName(input: T): Result<O, E>` — current contract vs desired contract
57
+ - Config shape — any new options needed
58
+
59
+ **Acceptance criteria:**
60
+ - [ ] Specific, independently testable criterion 1
61
+ - [ ] Specific, independently testable criterion 2
62
+ - [ ] Specific, independently testable criterion 3
63
+
64
+ **Out of scope:**
65
+ - Thing that should NOT be changed
66
+ - Adjacent feature that might seem related but is separate
67
+ - (or "(none)" if explicitly empty)
68
+
69
+ **Files Touched (locator hints, may rename):**
70
+ - `path/to/file.ts` (`TypeName`, `functionName`) — behavioral hint
71
+ ```
72
+
73
+ ## Worked example — bug
74
+
75
+ ```markdown
76
+ ## Agent Brief
77
+
78
+ **Category:** bug
79
+ **Summary:** Skill description truncation drops mid-word, producing broken output
80
+
81
+ **Current behavior:**
82
+ When a skill description exceeds 1024 characters, it is truncated at exactly 1024
83
+ characters regardless of word boundaries. Output ends mid-word
84
+ (e.g. "Use when the user wants to confi").
85
+
86
+ **Desired behavior:**
87
+ Truncation should break at the last word boundary before 1024 characters and
88
+ append "..." to indicate truncation. Total length including "..." must not
89
+ exceed 1024 chars.
90
+
91
+ **Key interfaces:**
92
+ - The `SkillMetadata` type's `description` field — no type change, but the
93
+ validation/processing logic that populates it needs to respect word boundaries
94
+ - Any function that reads SKILL.md frontmatter and extracts the description
95
+
96
+ **Acceptance criteria:**
97
+ - [ ] Descriptions under 1024 chars are unchanged
98
+ - [ ] Descriptions over 1024 chars are truncated at the last word boundary before 1024 chars
99
+ - [ ] Truncated descriptions end with "..."
100
+ - [ ] Total length including "..." does not exceed 1024 chars
101
+
102
+ **Out of scope:**
103
+ - Changing the 1024 char limit itself
104
+ - Multi-line description support
105
+
106
+ **Files Touched:**
107
+ - `compiler/parser.js` (`extractDescription`) — likely truncation site
108
+ - `compiler/__tests__/skill-description-quality.test.js` — add coverage
109
+ ```
110
+
111
+ ## Worked example — enhancement
112
+
113
+ ```markdown
114
+ ## Agent Brief
115
+
116
+ **Category:** enhancement
117
+ **Summary:** Add `.out-of-scope/` directory support for tracking rejected feature requests
118
+
119
+ **Current behavior:**
120
+ Rejected feature requests are closed with a `wontfix` label and a comment.
121
+ No persistent record of decision or reasoning. Future similar requests require
122
+ the maintainer to recall or search prior discussion.
123
+
124
+ **Desired behavior:**
125
+ Rejected feature requests are documented in `.out-of-scope/<concept>.md` files
126
+ capturing decision, reasoning, and links to all issues that requested the
127
+ feature. New issues are matched against these files during triage.
128
+
129
+ **Key interfaces:**
130
+ - Markdown file format in `.out-of-scope/` — each file has a `# Concept Name`
131
+ heading, `**Decision:**` line, `**Reason:**` line, `**Prior requests:**` list
132
+ - The triage workflow reads all `.out-of-scope/*.md` files early and matches
133
+ incoming issues by concept similarity
134
+
135
+ **Acceptance criteria:**
136
+ - [ ] Closing a feature as wontfix creates/updates a file in `.out-of-scope/`
137
+ - [ ] File includes the decision, reasoning, link to the closed issue
138
+ - [ ] If a matching `.out-of-scope/` file already exists, the new issue is appended
139
+ to its "Prior requests" list rather than creating a duplicate
140
+ - [ ] During triage, existing `.out-of-scope/` files are checked and surfaced
141
+ when a new issue matches a prior rejection
142
+
143
+ **Out of scope:**
144
+ - Automated matching (human confirms the match)
145
+ - Reopening previously rejected features
146
+ - Bug reports (only enhancement rejections go to `.out-of-scope/`)
147
+ ```
148
+
149
+ ## Anti-pattern (what makes a brief rot)
150
+
151
+ ```markdown
152
+ ## Agent Brief
153
+
154
+ **Summary:** Fix the triage bug
155
+
156
+ **What to do:**
157
+ The triage thing is broken. Look at the main file and fix it.
158
+ The function around line 150 has the issue.
159
+
160
+ **Files to change:**
161
+ - src/triage/handler.ts (line 150)
162
+ - src/types.ts (line 42)
163
+ ```
164
+
165
+ Rots because:
166
+ - No category
167
+ - Vague summary ("the triage thing")
168
+ - Line numbers in narrative — go stale on first edit
169
+ - File paths in narrative without behavioral hint
170
+ - No acceptance criteria
171
+ - No scope boundaries
172
+ - No current vs desired behavior split
173
+
174
+ ## Smell test additions for agent-brief
175
+
176
+ In addition to the BLOCK-tier smell tests in `context-pack/SKILL.md`, agent briefs MUST also pass:
177
+
178
+ | Check | Tier | Reason |
179
+ |-------|------|--------|
180
+ | Has `**Category:**` line with `bug`, `enhancement`, or `refactor` | BLOCK | Agent uses category for routing decisions |
181
+ | Has `**Current behavior:**` AND `**Desired behavior:**` sections | BLOCK | Without both, agent can't verify the delta |
182
+ | Acceptance criteria are independently testable (each can pass/fail alone) | BLOCK | Bundled criteria hide partial completion |
183
+ | `**Key interfaces:**` names actual types/functions, not file paths | BLOCK | The whole point of the brief — drift survival |
184
+ | `**Out of scope:**` present (even `(none)`) | BLOCK | Prevents gold-plating |
185
+
186
+ ## Integration
187
+
188
+ Use agent-brief when delegating to:
189
+ - An issue tracker (GitHub issue, Linear, Jira) for an AFK agent to pick up
190
+ - `rune:autopilot` (Pro) for autonomous multi-session work
191
+ - A scheduled cron agent (`/schedule` for one-time follow-up)
192
+ - Any handoff where the receiver may not see the originating conversation
193
+
194
+ Use the standard packet for in-session subagent dispatch (cook → fix, team → workstream).
@@ -217,7 +217,7 @@ Auto-trigger: no `.rune/` dir (first run) OR build just failed with env-looking
217
217
 
218
218
  1. Create TodoWrite with all applicable phases for this task
219
219
  2. Mark Phase 1 as `in_progress`
220
- 3. **BA gate**: Feature Request / Integration / Greenfield → invoke `rune:ba`. Task > 50 words or business terms (users, revenue, workflow) → invoke `rune:ba`. Bug Fix / simple Refactor → skip. BA produces `.rune/features/<name>/requirements.md` for Phase 2.
220
+ 3. **BA gate**: Feature Request / Integration / Greenfield → invoke `rune:ba`. Task > 50 words or business terms (users, revenue, workflow) → invoke `rune:ba`. Bug Fix / simple Refactor → skip. BA produces `.rune/features/<name>/requirements.md` for Phase 2. **Synthesis-mode auto-trigger**: if user pasted a spec > 200 words, conversation has > 1000 words on this feature, `.rune/features/<name>/requirements.md` already exists (continuation), or user said "synthesize"/"just write the spec" → BA Step 1.4 activates Synthesis Mode (extract + cite sources + confirm), skipping the 5-question elicitation. Cook does NOT need to choose mode — BA detects automatically.
221
221
  4. **Decision enforcement**: `Glob` for `.rune/decisions.md`; if exists, `Read` + extract constraints for Phase 2. Plan MUST NOT contradict active decisions without explicit user override.
222
222
  4b. **Contract enforcement**: If `.rune/contract.md` was loaded in Phase 0.6, list applicable contract sections for this task (e.g., `contract.security` for auth work, `contract.data` for database changes). These rules constrain Phase 2 planning and Phase 4 implementation.
223
223
 
@@ -766,7 +766,7 @@ Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical c
766
766
  | 5 | `scope-guard` | L3 | Verify changed files match approved plan scope (flag out-of-scope files before commit) |
767
767
  | 5 | `perf` | L2 | Performance regression check (optional) |
768
768
  | 5 | `audit` | L2 | Project health audit when scope warrants |
769
- | 5 | `review-intake` | L2 | Structured review intake for complex PRs |
769
+ | 5 | `review-intake` | L2 | Structured review intake for complex PRs OR Issue Triage Mode for issue tracker items (state machine: needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix). When external feedback source is an issue (not PR comment), review-intake auto-detects and runs Issue Triage Mode — emits `triage.classified` + `agent.brief.ready` (for AFK pickup) |
770
770
  | 5 | `sast` | L3 | Static analysis security testing |
771
771
  | 5d | `completion-gate` | L3 | Validate agent claims against evidence trail |
772
772
  | 5 | `constraint-check` | L3 | Audit HARD-GATE compliance across workflow |
@@ -3,7 +3,7 @@ name: debug
3
3
  description: "Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh."
4
4
  metadata:
5
5
  author: runedev
6
- version: "1.1.0"
6
+ version: "1.2.0"
7
7
  layer: L2
8
8
  model: sonnet
9
9
  group: development
@@ -63,6 +63,17 @@ If root cause cannot be identified after 3 hypothesis cycles:
63
63
 
64
64
  ## Execution
65
65
 
66
+ ### Step 0: Build a Feedback Loop (the actual skill)
67
+ <MUST-READ path="references/feedback-loop-ladder.md" trigger="when current repro is not a single command returning pass/fail in <5s, or when bug is intermittent/multi-component"/>
68
+
69
+ **The loop is the speed limit.** A fast, deterministic, agent-runnable pass/fail signal turns debugging into mechanical bisection. Without one, hypotheses just consume noise.
70
+
71
+ Skip Step 0 only if the existing repro is already one command, deterministic, and runs in < 5s.
72
+
73
+ Otherwise, before Step 1: pick the highest viable rung from `references/feedback-loop-ladder.md` (10-rank ladder: failing test → curl → CLI snapshot → headless browser → trace replay → throwaway harness → fuzz → bisection → differential → HITL script). Construct it. Verify it currently FAILS (proves it measures the bug, not noise). Only then proceed.
74
+
75
+ If loop construction takes > 10 minutes, that itself is the diagnosis: the bug surface is too large or the system too coupled. Trigger the 3-Fix Escalation Rule (Step 6) — architecture is the problem, not the bug.
76
+
66
77
  ### Step 1: Reproduce
67
78
 
68
79
  Understand and confirm the error described in the request.
@@ -349,6 +360,7 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
349
360
  7. MUST NOT say "I know what's wrong" without citing file:line evidence
350
361
  8. For deep stack errors: MUST use backward tracing (Step 2) — never fix at the crash site
351
362
  9. For multi-component systems: MUST instrument boundaries before hypothesizing
363
+ 10. MUST run Step 0 (Build Feedback Loop) before forming hypotheses on non-trivial bugs — skipping the loop = guessing
352
364
 
353
365
  ## Output Format
354
366
 
@@ -415,7 +427,7 @@ Append to Debug Report when invoked standalone. Suppress when called as sub-skil
415
427
  ```yaml
416
428
  chain_metadata:
417
429
  skill: "rune:debug"
418
- version: "1.1.0"
430
+ version: "1.2.0"
419
431
  status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
420
432
  domain: "[area debugged]"
421
433
  files_changed: [] # debug never changes files
@@ -449,6 +461,8 @@ chain_metadata:
449
461
  | Debug report recommends touching 5+ unrelated files | HIGH | Symptom of fixing at crash sites instead of source. Backward trace (Step 2) to find origin. If truly 5+ files → likely architectural issue → escalate via 3-Fix Rule |
450
462
  | Re-investigating known error patterns from scratch | MEDIUM | Step 2d: match error against Known Error Pattern Catalog first — skip hypothesis cycling for recognized patterns |
451
463
  | Same error fingerprint across cycles treated as different errors | MEDIUM | Step 2d: normalize line numbers, paths, variable names before comparison — same fingerprint = same error |
464
+ | Forming hypotheses with a slow / non-deterministic / manual repro | CRITICAL | Step 0: build a fast deterministic pass/fail signal first — see `references/feedback-loop-ladder.md` 10-rank ladder. Hypothesis testing on a slow loop wastes 10x the cycles |
465
+ | Skipping loop construction "to save time" on non-trivial bugs | HIGH | The loop IS the time-saver. 10 min on the loop saves hours of cycling. If construction takes > 10 min, escalate via 3-Fix Rule — bug is architectural |
452
466
 
453
467
  ## Done When
454
468
 
@@ -0,0 +1,62 @@
1
+ # Feedback Loop Ladder
2
+
3
+ **The loop is the skill.** A fast, deterministic, agent-runnable pass/fail signal converts debugging into a mechanical bisection problem. Without one, no amount of file-reading will save you.
4
+
5
+ > "The rate of feedback is your speed limit." Spend disproportionate effort on the loop itself — bisection, hypothesis testing, and instrumentation all just consume that signal.
6
+
7
+ ## When to invest in a better loop
8
+
9
+ Run the ladder before Step 3 (Form Hypotheses) when ANY of these are true:
10
+
11
+ | Signal | Threshold |
12
+ |--------|-----------|
13
+ | Repro is "click around in browser, then check" | Always — slowest possible loop |
14
+ | Cycle 1 hypotheses ruled out, no faster signal exists | Required before cycle 2 |
15
+ | Reproduction is intermittent (flaky) | Required — non-deterministic loop wastes cycles |
16
+ | Bug spans 3+ components and you can't isolate where it fails | Build component-boundary instrumentation FIRST |
17
+ | Manual repro takes > 30 seconds | Auto-script it before forming hypotheses |
18
+
19
+ **Skip if:** repro is already a single command returning exit code 0/1 in < 5s. The loop is already optimal.
20
+
21
+ ## The ladder (try in order — stop at first viable rung)
22
+
23
+ | # | Loop | Speed | Determinism | When |
24
+ |---|------|-------|-------------|------|
25
+ | 1 | **Failing test at the bug's seam** (unit, integration, e2e) | Fast | Hard pass/fail | Default — bug already has a test infrastructure |
26
+ | 2 | **curl / HTTP script** against running dev server | Fast | Snapshot-diffable | API or backend bugs |
27
+ | 3 | **CLI invocation with fixture input**, diff stdout vs known-good snapshot | Fast | Snapshot-diffable | CLI tools, parsers, formatters |
28
+ | 4 | **Headless browser script** (Playwright / `rune:browser-pilot`) — drives UI, asserts on DOM/console/network | Medium | Reliable | UI bugs, JS errors, network failures |
29
+ | 5 | **Replay a captured trace** — save real network request / payload / event log to disk; replay through code path in isolation | Fast | Deterministic | Bugs reproducible only with specific data |
30
+ | 6 | **Throwaway harness** — minimal subset of system (one service, mocked deps), exercise bug code path with single function call | Fast | Isolated | Bug deep inside framework or service stack |
31
+ | 7 | **Property / fuzz loop** — 1000 random inputs, look for failure mode | Slow | Probabilistic | "Sometimes wrong output", race conditions, edge cases |
32
+ | 8 | **Bisection harness** — automate "boot at state X, check, repeat" so `git bisect run` works | Medium | Hard pass/fail | Bug appeared between two known commits / dataset versions |
33
+ | 9 | **Differential loop** — same input through old vs new (or two configs), diff outputs | Medium | Diff-based | Regression vs reference implementation |
34
+ | 10 | **HITL bash script** — last resort. Drive the human with a structured script | Slow | Human-error-prone | All else fails — at least the loop has structure |
35
+
36
+ ## What "good loop" looks like
37
+
38
+ - One command, one second to run, one bit of output (pass / fail)
39
+ - Deterministic — same input → same output, every time
40
+ - Captures the bug, not a proxy ("test passes when bug present" is a broken loop)
41
+ - Cleanup-safe — re-runnable without manual reset
42
+
43
+ ## Anti-patterns
44
+
45
+ | Anti-pattern | Why it fails |
46
+ |--------------|--------------|
47
+ | "I'll just print and check the console" | Stateless, manual, slow — degrades to staring at logs |
48
+ | "Let me read the code one more time" | Reading is not a loop. Loop = pass/fail signal. |
49
+ | "It works on my machine, not in CI" | Build a loop in the CI environment FIRST |
50
+ | Skipping loop construction because "it's complicated" | The loop is the skill. Skipping it = guessing for the next 5 cycles |
51
+
52
+ ## Integration with Step 0
53
+
54
+ Add Step 0 (before Reproduce) when invoked on a non-trivial bug:
55
+
56
+ ```
57
+ 0. Build feedback loop — pick the highest rung from the ladder that you can construct
58
+ in < 10 minutes. Make it deterministic. Verify it currently FAILS (proves it's
59
+ measuring the bug, not noise). Only then proceed to Step 1.
60
+ ```
61
+
62
+ If loop construction takes > 10 minutes, that itself is the diagnosis: the bug surface is too large or the system is too coupled. Escalate via 3-Fix Rule (architecture is the problem, not the bug).
@@ -3,7 +3,7 @@ name: plan
3
3
  description: "Create structured implementation plans from requirements. Produces master plan + phase files for enterprise-scale project management. Master plan = overview (<80 lines). Phase files = execution detail (<150 lines each). Each session handles 1 phase. Uses opus for deep reasoning."
4
4
  metadata:
5
5
  author: runedev
6
- version: "1.5.0"
6
+ version: "1.6.0"
7
7
  layer: L2
8
8
  model: opus
9
9
  group: creation
@@ -149,9 +149,12 @@ If ANY "Master + Phase Files" criterion is true → produce master plan + phase
149
149
 
150
150
  ### Step 3 — Decompose into Phases
151
151
  <MUST-READ path="references/wave-planning.md" trigger="when writing wave-structured task lists inside any phase"/>
152
+ <MUST-READ path="references/vertical-slice.md" trigger="when decomposing a feature into tasks/issues — ALWAYS prefer vertical (end-to-end) slices over horizontal (single-layer) ones"/>
152
153
 
153
154
  Group work into phases. Each phase: completable in one session, clear "done when", produces testable output, independent enough to run without other phases loaded.
154
155
 
156
+ **Vertical slices over horizontal layers**: each task within a phase MUST be a tracer-bullet slice (schema + API + UI + test, end-to-end), NOT a single-layer chunk. Horizontal slicing ("all models → all APIs → all UI") looks organized but blocks on the slowest layer. See `references/vertical-slice.md` for slice rules, AFK vs HITL classification, and the per-task slice template.
157
+
155
158
  <HARD-GATE>
156
159
  Each phase MUST be completable by ANY coder model (including Haiku) with ONLY the phase file loaded.
157
160
  If the coder would need to read the master plan or other phase files to execute → the phase file is missing detail.
@@ -163,7 +166,7 @@ Phase decomposition rules:
163
166
  - **Dependencies before consumers**: create what's imported before the importer
164
167
  - **Test alongside**: each phase includes its own test tasks
165
168
  - **Max 5-7 tasks per phase**: if more, split the phase
166
- - **Vertical slices over horizontal layers**: prefer "auth end-to-end" over "all models → all APIs → all UI"
169
+ - **Vertical slices over horizontal layers**: prefer "auth end-to-end" over "all models → all APIs → all UI" (see `references/vertical-slice.md` for tracer-bullet template, AFK/HITL labels, granularity rules)
167
170
 
168
171
  Tasks within each phase MUST be organized into waves (parallel-safe groupings). See `references/wave-planning.md`.
169
172
 
@@ -346,7 +349,7 @@ Append to plan output when invoked standalone. Suppress when called as sub-skill
346
349
  ```yaml
347
350
  chain_metadata:
348
351
  skill: "rune:plan"
349
- version: "1.5.0"
352
+ version: "1.6.0"
350
353
  status: "[DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED]"
351
354
  domain: "[area planned]"
352
355
  files_changed:
@@ -385,7 +388,9 @@ chain_metadata:
385
388
  | Phase with zero test tasks | CRITICAL | HARD-GATE rejects it |
386
389
  | 10+ phases overwhelming the master plan | MEDIUM | Max 8 phases — split into sub-projects if more |
387
390
  | Task without File path or Verify command | HIGH | Every task MUST have File + Test + Verify + Commit fields — no vague "implement the feature" tasks |
388
- | Horizontal layer planning (all models → all APIs → all UI) | HIGH | Vertical slices parallelize better. Use wave-based grouping: independent tasks in same wave, dependent tasks in later waves |
391
+ | Horizontal layer planning (all models → all APIs → all UI) | HIGH | Vertical slices parallelize better. Use wave-based grouping AND vertical-slice template (`references/vertical-slice.md`): each task = end-to-end path through schema/API/UI/test, demoable on its own |
392
+ | Slice not demoable on its own ("just the migration", "just the UI shell") | HIGH | Per `references/vertical-slice.md` — every slice produces a verifiable outcome. Layer-only fragments block downstream slices and hide partial completion |
393
+ | HITL slices marked liberally to enable "review" friction | MEDIUM | HITL is for hard blockers (OAuth setup, design decision, paid third-party access), not soft preferences. Default to AFK; use post-merge review for soft signals |
389
394
  | Tasks without `depends_on` in Wave 2+ | MEDIUM | Implicit dependencies break parallel dispatch. Every Wave 2+ task MUST declare `depends_on` |
390
395
  | Plan ignores locked Decisions from BA | CRITICAL | Decision Compliance section cross-checks requirements.md — locked decisions are non-negotiable |
391
396
  | Complex feature missing Workflow Registry — components planned but never wired | HIGH | Step 4.5: 4-view registry catches orphaned components, unphased workflows, and missing state transitions before phase files are written |
@@ -0,0 +1,79 @@
1
+ # Vertical Slice (Tracer-Bullet) Decomposition
2
+
3
+ **Each slice is a thin path through ALL layers** — schema, API, UI, tests — that produces a demoable, verifiable outcome on its own. Prefer many thin slices over few thick ones.
4
+
5
+ > Horizontal layers ("all models → all APIs → all UI") look organized but block on the slowest layer. Vertical slices ship in parallel and verify continuously.
6
+
7
+ ## Slice rules
8
+
9
+ 1. **End-to-end, not end-of-end** — every slice touches every layer it needs (schema migration + handler + UI + test). A slice that only adds a database column is not a slice; it's a fragment.
10
+ 2. **Demoable on its own** — when the slice is merged, you can demo it (or run a single command to verify). If demoing requires "and now switch to the other PR", the slices were drawn wrong.
11
+ 3. **Narrow but complete** — one user story, one happy path, minimal error handling. Edge cases are *separate slices*, not bigger versions of the same slice.
12
+ 4. **Independently grabbable** — any developer or agent should be able to pick up Slice N without reading Slice N+1. Dependencies declared explicitly, not implicit.
13
+
14
+ ## Slice types
15
+
16
+ | Type | Definition | When |
17
+ |------|------------|------|
18
+ | **AFK** | Can be implemented and merged without human interaction. Spec is concrete enough that an agent (or the weakest model) executes it correctly. | Default — prefer wherever possible |
19
+ | **HITL** | Requires human input mid-execution: architectural decisions, design review, copy approval, third-party access (OAuth setup, DNS, payment provider). | Only when AFK is genuinely impossible |
20
+
21
+ **Bias toward AFK.** A slice marked HITL is friction — every HITL slice blocks the parallel queue. Before marking HITL, ask: can the human input be done ONCE upfront and then the slice is AFK?
22
+
23
+ ## Slice template (per task in a phase file)
24
+
25
+ ```markdown
26
+ ### Slice: [verb-led title]
27
+ - **Type**: AFK | HITL
28
+ - **Story**: As a [persona], I want to [action] so that [benefit]
29
+ - **Path through layers**:
30
+ - Schema: [migration / type addition]
31
+ - API: [endpoint or function signature]
32
+ - UI: [component or surface]
33
+ - Test: [verification approach]
34
+ - **Demoable**: [exact command or click-path that shows it works]
35
+ - **Blocked by**: [slice IDs] | None — can start immediately
36
+ - **Out of scope** (explicit): [what this slice does NOT cover]
37
+ ```
38
+
39
+ ## Granularity
40
+
41
+ Right-sized slice:
42
+ - Fits in one phase file (under the Amateur-Proof 200-line cap)
43
+ - Completable in one session by Sonnet/Haiku
44
+ - Touches 3-7 files total across all layers
45
+ - Has exactly ONE acceptance criterion that proves the path works end-to-end
46
+
47
+ If a slice has 5+ acceptance criteria → split it. If a slice touches 10+ files → split it. If two slices share 3+ files → merge or sequence them (file overlap = race condition in parallel execution).
48
+
49
+ ## Decomposition checklist
50
+
51
+ Before approving a slice breakdown, verify:
52
+
53
+ - [ ] Every slice can be demoed independently
54
+ - [ ] No slice requires another in-flight slice to be merged first (declared deps OK; in-flight overlap NOT OK)
55
+ - [ ] AFK / HITL labels are accurate — HITL slices have a specific blocking input named
56
+ - [ ] Slice count matches granularity rule (3-7 slices for a typical feature; if 1 or 2, slice is too thick; if 15+, too thin)
57
+ - [ ] First slice is the **smallest valuable end-to-end path** — proves the architecture works before scaling
58
+
59
+ ## Anti-patterns
60
+
61
+ | Anti-pattern | Why it fails |
62
+ |--------------|--------------|
63
+ | Layer-1 slice ("just the database changes") | Not demoable, not verifiable, blocks every downstream slice |
64
+ | Slice with "and the admin UI for it" appended | Hidden second slice — split |
65
+ | 10 acceptance criteria on one slice | Granularity miss — slice is actually a feature |
66
+ | Slice marked HITL because "I might want to review the design" | HITL is for hard blockers, not soft preferences. Use AFK + post-merge review. |
67
+ | First slice is the most complex one ("let's build the hardest part first") | Wrong order. First slice proves architecture; complexity comes later when foundation is verified. |
68
+
69
+ ## Integration with phase planning
70
+
71
+ Vertical slices map cleanly to phase wave structure:
72
+
73
+ ```
74
+ Phase 1, Wave 1: Slice A (foundation slice — proves architecture end-to-end)
75
+ Phase 1, Wave 2: Slice B, C (parallel — depend on A's contract, not on each other)
76
+ Phase 2, Wave 1: Slice D, E (next layer of slices)
77
+ ```
78
+
79
+ Each slice = one task in a wave. Use `touches[]` / `provides[]` / `requires[]` metadata (see Change Stacking in `plan/SKILL.md`) to detect file overlap between slices in the same wave.
@@ -1,13 +1,14 @@
1
1
  ---
2
2
  name: review-intake
3
- description: "Use when receiving code review feedback, PR comments, or external suggestions before implementing any changes. Prevents blind implementation, enforces verification-first discipline."
3
+ description: "Use when receiving external input that needs structured intake before action — PR review feedback, code review comments, OR issue tracker items (bug reports, feature requests). PR Review Mode (default) verifies suggestions before implementing. Issue Triage Mode classifies issues into a state machine (ready-for-agent / ready-for-human / needs-info / wontfix) and emits AGENT-BRIEFs for AFK execution. Prevents blind implementation, enforces verification-first discipline."
4
4
  metadata:
5
5
  author: runedev
6
- version: "1.2.0"
6
+ version: "1.3.0"
7
7
  layer: L2
8
8
  model: sonnet
9
9
  group: quality
10
- tools: "Read, Write, Edit, Glob, Grep"
10
+ tools: "Read, Write, Edit, Bash, Glob, Grep"
11
+ emit: triage.classified, agent.brief.ready
11
12
  listen: outofscope.match
12
13
  ---
13
14
 
@@ -17,11 +18,23 @@ metadata:
17
18
 
18
19
  The counterpart to `review`. While `review` finds issues in code, `review-intake` handles the response when someone finds issues in YOUR code. Enforces a verification-first discipline: understand fully, verify against codebase reality, then act. Prevents the common failure mode of blindly implementing suggestions that break things or don't apply.
19
20
 
21
+ ## Modes
22
+
23
+ | Mode | When | Workflow |
24
+ |------|------|----------|
25
+ | **PR Review Mode** (default) | Input is PR comments / code review feedback / external suggestions | Phases 1-6 below — absorb, comprehend, verify, evaluate, respond, implement |
26
+ | **Issue Triage Mode** | Input is issue tracker item (`gh-42`, URL, pasted issue body), or user says "triage" / "process the inbox" | See `references/issue-triage.md` — state machine (needs-triage → ready-for-agent / ready-for-human / needs-info / wontfix) + repro-first for bugs + AGENT-BRIEF emission |
27
+
28
+ Both modes share Phase 4.5 (Rejection KB Write) — `wontfix-enhancement` from Issue Triage and OUT OF SCOPE from PR Review both write `.out-of-scope/<slug>.md`.
29
+
20
30
  ## Triggers
21
31
 
22
- - `/rune review-intake` — manual invocation when processing feedback
23
- - Auto-trigger: when `cook` or `fix` receives PR review comments
24
- - Auto-trigger: when user pastes review feedback into session
32
+ - `/rune review-intake` — manual invocation, PR Review Mode by default
33
+ - `/rune review-intake <issue-ref>` Issue Triage Mode (issue number, URL, or path)
34
+ - `/rune review-intake --inbox` Issue Triage Mode batch sweep (unlabeled + needs-triage + needs-info-with-activity)
35
+ - Auto-trigger: when `cook` or `fix` receives PR review comments → PR Review Mode
36
+ - Auto-trigger: when user pastes review feedback into session → PR Review Mode
37
+ - Auto-trigger: when user pastes an issue body or references a ticket → Issue Triage Mode
25
38
 
26
39
  ## Calls (outbound)
27
40
 
@@ -36,7 +49,10 @@ The counterpart to `review`. While `review` finds issues in code, `review-intake
36
49
  - `cook` (L1): Phase 5 quality gate when external review arrives
37
50
  - `review` (L2): when self-review surfaces issues to address
38
51
 
39
- ## Workflow
52
+ ## Workflow (PR Review Mode)
53
+
54
+ For Issue Triage Mode, see [references/issue-triage.md](references/issue-triage.md). Both modes converge at Phase 4.5 for rejection KB writes.
55
+ <MUST-READ path="references/issue-triage.md" trigger="when input is an issue tracker item, batch inbox sweep, or user explicitly says 'triage' / 'process the inbox'"/>
40
56
 
41
57
  ### Phase 1 — ABSORB
42
58
 
@@ -245,6 +261,10 @@ How to push back:
245
261
  | OUT OF SCOPE verdict with no `.out-of-scope/` file written | HIGH | Phase 4.5 HARD-GATE — oral-only rejections force re-litigation in future sessions |
246
262
  | Writing a deferral ("busy this quarter") to `.out-of-scope/` | MEDIUM | Deferrals belong in backlog, not the rejection KB. KB entries must cite durable reasons (scope, tech constraint, strategy) |
247
263
  | Creating duplicate `.out-of-scope/` files for the same concept | MEDIUM | Lexical-similarity gate (≥0.7 overlap) — append to existing file's `prior_requests` instead of duplicating |
264
+ | Marking issue `ready-for-agent` without confirmed repro (bugs) | CRITICAL | Issue Triage Mode Step T4 HARD-GATE: bugs MUST attempt reproduction before `ready-for-agent` label. Confirmed repro = strong agent-brief; failed repro = `needs-info` |
265
+ | Auto-applying `wontfix` to an issue without maintainer confirmation | HIGH | Triage recommends, maintainer decides. State changes (label + comment + close) confirmed via Step T3 before Step T6 acts |
266
+ | Posting triage comments without the AI-disclaimer line | MEDIUM | Issue Triage Mode requires `> *This was generated by AI during triage.*` disclaimer prefix on every comment — trust degrades when reporter discovers AI authorship after the fact |
267
+ | Writing `.out-of-scope/` for a `wontfix-bug` (not enhancement) | MEDIUM | Format spec: only enhancement rejections produce KB files. Bug rejections (already fixed, not reproducible, not a bug) get a comment, not a file |
248
268
 
249
269
  ## Done When
250
270
 
@@ -0,0 +1,202 @@
1
+ # Issue Triage Mode
2
+
3
+ A second mode for `review-intake`. The default mode (PR comments) processes inbound review feedback. **Issue Triage Mode** processes inbound issue tracker items (GitHub Issues, Linear tickets, bug reports, feature requests) and routes them through a state machine.
4
+
5
+ > The standard PR mode answers "should I implement this suggestion?". Issue Triage Mode answers "what state is this issue in, and who should pick it up next?".
6
+
7
+ ## When to use Issue Triage Mode
8
+
9
+ Activate when input is an **issue** (not a PR review). Triggers:
10
+
11
+ | Signal | Threshold |
12
+ |--------|-----------|
13
+ | User passes an issue reference (`/rune review-intake gh-42`, URL, or path) | Always |
14
+ | User says "triage", "intake this issue", "process the inbox" | Explicit |
15
+ | User pastes an issue body + comments rather than PR review feedback | Auto-detect — issue has reporter, not reviewer |
16
+ | Batch mode: `/rune review-intake --inbox` queries unlabeled + needs-triage issues | Inbox sweep |
17
+
18
+ Skip if input is PR review comments → use default PR Review Mode.
19
+
20
+ ## State machine
21
+
22
+ Two dimensions per issue:
23
+
24
+ | Category (1 of) | State (1 of) |
25
+ |-----------------|--------------|
26
+ | `bug` | `needs-triage` (unlabeled, never evaluated) |
27
+ | `enhancement` | `needs-info` (waiting on reporter for more detail) |
28
+ | | `ready-for-agent` (fully specified, AFK agent can execute) |
29
+ | | `ready-for-human` (specified but needs human judgment — design decision, OAuth setup, copy approval) |
30
+ | | `wontfix` (explicit decision not to action) |
31
+
32
+ Every triaged issue carries exactly one category and one state. Conflicts → flag and ask the maintainer before acting.
33
+
34
+ State transitions (typical):
35
+
36
+ ```
37
+ unlabeled → needs-triage → needs-info → needs-triage (after reporter replies)
38
+ → ready-for-agent
39
+ → ready-for-human
40
+ → wontfix
41
+ ```
42
+
43
+ Maintainer can override at any time (quick state override below).
44
+
45
+ ## Workflow
46
+
47
+ ### Step T1 — Inbox view (if batch mode)
48
+
49
+ Query the issue tracker for three buckets, oldest first:
50
+
51
+ 1. **Unlabeled** — never triaged
52
+ 2. **`needs-triage`** — evaluation in progress
53
+ 3. **`needs-info` with reporter activity since last triage notes** — needs re-evaluation
54
+
55
+ Show counts + one-line summary per issue. Maintainer picks one.
56
+
57
+ ### Step T2 — Gather context (per-issue)
58
+
59
+ Read the full issue: body, comments, labels, reporter, dates. Parse any prior triage notes so you don't re-ask resolved questions.
60
+
61
+ Then scan:
62
+ - `CONTEXT.md` — apply project glossary terms in your understanding
63
+ - `docs/adr/` — respect Architecture Decision Records in the affected area
64
+ - `.out-of-scope/*.md` — check for prior rejection that resembles this issue
65
+
66
+ If the issue matches a prior `.out-of-scope/` entry (≥0.7 lexical overlap), surface it: *"This matches a prior rejection (`<slug>`). Recommend `wontfix` unless circumstances changed."* Wait for maintainer direction.
67
+
68
+ ### Step T3 — Recommend
69
+
70
+ Tell the maintainer your category + state recommendation with reasoning. Include a brief codebase summary relevant to the issue. Wait for direction. Do not act unilaterally.
71
+
72
+ ### Step T4 — Reproduce (bugs only — HARD-GATE)
73
+
74
+ <HARD-GATE>
75
+ Bugs MUST attempt reproduction before being marked `ready-for-agent`. A confirmed repro is what makes the agent-brief strong; without it, the agent will guess.
76
+ </HARD-GATE>
77
+
78
+ Process:
79
+ 1. Read the reporter's repro steps
80
+ 2. Trace the relevant code via `rune:scout` / `rune:debug`
81
+ 3. If the repro is a HTTP request / CLI invocation / browser flow → run it
82
+ 4. Report outcome:
83
+ - **Confirmed repro** with code path → strong `ready-for-agent` signal
84
+ - **Failed repro** → likely `needs-info` (ask for env, version, exact steps)
85
+ - **Insufficient detail** → `needs-info` with specific questions
86
+
87
+ If the bug is multi-component or intermittent, route to `rune:debug` Step 0 (build a feedback loop) instead of guessing.
88
+
89
+ ### Step T5 — Grill (if vague)
90
+
91
+ If the issue lacks specifics for both bug and enhancement paths, run a grilling pass via `rune:ba` synthesis-mode (Step 1.4):
92
+ - Synthesis-mode reads the issue body + comments as the "rich context"
93
+ - Asks targeted follow-ups ONLY on dimensions with genuine gaps
94
+ - Produces a Requirements Document the agent-brief can cite
95
+
96
+ ### Step T6 — Apply outcome
97
+
98
+ Match state to action:
99
+
100
+ | State | Action |
101
+ |-------|--------|
102
+ | `ready-for-agent` | Post AGENT-BRIEF comment on issue (use `rune:context-pack` agent-brief variant — see `context-pack/references/agent-brief.md`). Apply `ready-for-agent` label. |
103
+ | `ready-for-human` | Post AGENT-BRIEF + explicit "why this can't be delegated" reason (judgment call, external access, design decision, manual testing). Apply `ready-for-human` label. |
104
+ | `needs-info` | Post triage notes (template below). Apply `needs-info` label. |
105
+ | `wontfix` (bug) | Post a polite explanation comment, then close. **No `.out-of-scope/` write** — bug rejections (already fixed, not reproducible, not a bug) get a comment, not a KB file. |
106
+ | `wontfix` (enhancement) | Trigger Phase 4.5 (existing) — write `.out-of-scope/<slug>.md`, link from a comment, then close. |
107
+ | `needs-triage` | Apply the role. Optional comment if there's partial progress. |
108
+
109
+ Every comment posted by triage MUST start with the disclaimer:
110
+
111
+ ```
112
+ > *This was generated by AI during triage.*
113
+ ```
114
+
115
+ ### Step T7 — Quick state override
116
+
117
+ If the maintainer says "move #42 to ready-for-agent", trust them and apply the state directly. Confirm what you're about to do (label changes, comment, close), then act. Skip grilling. If moving to `ready-for-agent` without a grilling session, ask whether they want to write an agent-brief.
118
+
119
+ ## Templates
120
+
121
+ ### Needs-info comment
122
+
123
+ ```markdown
124
+ > *This was generated by AI during triage.*
125
+
126
+ ## Triage Notes
127
+
128
+ **What we've established so far:**
129
+ - [point 1]
130
+ - [point 2]
131
+
132
+ **What we still need from you (@reporter):**
133
+ - [specific, actionable question 1]
134
+ - [specific, actionable question 2]
135
+ ```
136
+
137
+ Capture everything resolved during grilling under "established so far" so the work isn't lost. Questions must be specific and actionable, not "please provide more info".
138
+
139
+ ### Ready-for-agent comment
140
+
141
+ ```markdown
142
+ > *This was generated by AI during triage.*
143
+
144
+ (AGENT-BRIEF block — see `context-pack/references/agent-brief.md`)
145
+ ```
146
+
147
+ ### Wontfix-bug comment
148
+
149
+ ```markdown
150
+ > *This was generated by AI during triage.*
151
+
152
+ Closing as wontfix:
153
+ - [Reason: already fixed in #X / not reproducible / not a bug — explain briefly]
154
+ - [If "not reproducible": link the failed repro evidence]
155
+ - [If user disagrees: reopen and provide new details]
156
+ ```
157
+
158
+ ### Wontfix-enhancement comment (links to .out-of-scope/)
159
+
160
+ ```markdown
161
+ > *This was generated by AI during triage.*
162
+
163
+ Closing as wontfix. Recorded in `.out-of-scope/<slug>.md` for future reference.
164
+
165
+ [1-line summary of the durable reason — full reasoning lives in the file]
166
+ ```
167
+
168
+ ## Resuming a previous triage session
169
+
170
+ If prior triage notes exist on the issue, read them, check whether the reporter has answered any outstanding questions, and present an updated picture before continuing. Don't re-ask resolved questions.
171
+
172
+ ## State machine output (per issue triaged)
173
+
174
+ ```yaml
175
+ issue: <id>
176
+ category: bug | enhancement
177
+ state: needs-triage | needs-info | ready-for-agent | ready-for-human | wontfix
178
+ repro: confirmed | failed | insufficient-info | n/a # bugs only
179
+ agent_brief_posted: true | false
180
+ out_of_scope_written: <slug>.md | null
181
+ ```
182
+
183
+ This payload travels alongside the existing Verdicts table when emit `triage.classified` fires.
184
+
185
+ ## Anti-patterns
186
+
187
+ | Anti-pattern | Why it fails |
188
+ |--------------|--------------|
189
+ | Marking `ready-for-agent` without confirmed repro (bugs) | Agent guesses, fixes wrong thing, bug returns |
190
+ | Auto-applying `wontfix` without maintainer confirmation | Triage recommends; only maintainer decides |
191
+ | Re-asking questions already answered in prior triage notes | Wastes reporter trust; read existing notes first |
192
+ | Writing `.out-of-scope/` for bug rejections | Per format spec, only enhancement rejections produce KB files |
193
+ | Posting triage comments without the AI-generated disclaimer | Reporter assumes human voice; trust degrades when caught |
194
+ | Quick state override without confirmation summary | "Move to ready-for-agent" can mean "label only" or "label + brief" — confirm before acting |
195
+
196
+ ## Integration with Phase 4.5 (existing)
197
+
198
+ Phase 4.5 (Rejection KB Write) already exists in `review-intake/SKILL.md` for OUT OF SCOPE verdicts in PR Mode. In Issue Triage Mode, `wontfix-enhancement` outcome triggers the **same** Phase 4.5 — no duplicate logic. The slug, lexical-similarity check, and write procedure are identical.
199
+
200
+ ## Required external tools
201
+
202
+ - `gh` CLI (GitHub Issues) OR Linear MCP — without an issue-tracker integration, Issue Triage Mode falls back to local-only mode: maintainer pastes the issue body, triage produces classification + draft comments, maintainer copies the comments back to the tracker manually.
@@ -93,6 +93,8 @@ Use `Edit` for all code changes. Rules:
93
93
  - Never change more than 5 files total in this session
94
94
  - If a change reveals a hidden bug, stop and call `rune:debug` before continuing
95
95
 
96
+ **Multi-layer refactors**: when the deepening or extraction touches 2+ layers within the module (e.g., types + logic + interface), decompose into **vertical-slice tracer-bullet edits** rather than horizontal layer passes. Each slice = one end-to-end edit chain that produces a verifiable outcome (one Edit per layer, immediately tested). See `plan/references/vertical-slice.md` for slice rules and granularity. Horizontal "all-types-then-all-logic-then-all-interface" passes are forbidden inside surgeon — they break the "test after each Edit" discipline (Step 4) by leaving intermediate states untestable.
97
+
96
98
  For **Strangler Fig**: Create the new module file first, then update one consumer at a time.
97
99
 
98
100
  For **Branch by Abstraction**: Create the interface first (commit), wrap legacy (commit), build new impl (commit), switch (commit). Four commits minimum.
@@ -286,6 +286,8 @@ Mark todo[1] `completed`.
286
286
 
287
287
  Mark todo[2] `in_progress`.
288
288
 
289
+ **3a-pre0. Output density honoring.** During Phase 2 dispatch, any worker that hits context ORANGE / RED has emitted `output.density.set` with `mode=caveman, scope=workstream` (auto from `rune:context-engine`). Coordination output respects per-workstream density: when summarizing a caveman-active worker's report into the merge plan, preserve its terse format rather than re-expanding to verbose. If 3+ workers are caveman-active simultaneously, the team-level summary itself should adopt caveman until merge completes (announce to user once: "Team output in caveman mode — N workers under context pressure"). Reverts to normal after Phase 5.
290
+
289
291
  **3a-pre. Oracle reattach sweep.** Before merge coordination, glob `.rune/oracle-pending/*.json`. For any worker stream that emitted `oracle.dispatched` during Phase 2, invoke `session-bridge --reattach <sessionId>`. Worker streams with `status=pending` past their `timeoutAt` are unblocked via `oracle.failed` so coordination can proceed. Workers with `status=complete` consume the response before merge.
290
292
 
291
293
  **3a. Check for file conflicts.**