@rune-kit/rune 2.2.1 → 2.2.3

package/skills/ba/SKILL.md

@@ -233,6 +233,16 @@ US-1: As a [persona], I want to [action] so that [benefit]
 ## Risks
 - [risk]: [mitigation strategy]
 
+## Decision Classification
+
+| Category | Meaning | Example |
+|----------|---------|---------|
+| **Decisions** (locked) | User confirmed — agent MUST follow | "Use PostgreSQL, not MongoDB" |
+| **Discretion** (agent decides) | User trusts agent judgment | "Pick the best validation library" |
+| **Deferred** (out of scope) | Explicitly NOT this task | "Mobile app — future phase" |
+
+Plan gates on Decision compliance — Discretion items don't need approval.
+
 ## Next Step
 → Hand off to rune:plan for implementation planning
 ```

package/skills/completion-gate/SKILL.md

@@ -4,7 +4,7 @@ description: "Validates agent claims against evidence trail. Catches 'done' with
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.1.0"
+  version: "1.2.0"
   layer: L3
   model: haiku
   group: validation
@@ -58,6 +58,21 @@ CLAIM PATTERNS:
 
 Extract each claim as: `{ claim: string, source_skill: string }`
 
+### Step 1b — Stub Detection (Existence Theater Check)
+
+Before checking claims, scan all files created/modified in this workflow for stubs:
+
+```
+Grep for stub patterns in new/modified files:
+- "Placeholder" | "TODO" | "Not implemented" | "NotImplementedError"
+- Functions with body: only `return null` / `return {}` / `pass` / `throw`
+- Components returning only a single div with no logic
+```
+
+If ANY stub detected:
+- Add synthetic claim: "implemented [filename]" → CONTRADICTED (file is a stub)
+- This catches agents that create files but don't implement them
+
 ### Step 2 — Match Evidence
 
 For each claim, look for corresponding evidence in the conversation context:
@@ -108,6 +123,23 @@ IF no evidence found:
 UNCONFIRMED — 1 claim lacks evidence, 1 contradicted. Cannot proceed to commit.
 ```
 
+### Step 5 — Evidence Quality Gate
+
+Before emitting verdict, verify evidence quality:
+
+1. **IDENTIFY** — list every claim the agent made (Step 1 output)
+2. **RUN** — confirm verification commands were actually executed (not just planned)
+3. **READ** — read every line of command output (not just exit code)
+4. **VERIFY** — match each claim to a specific evidence quote (file:line or output snippet)
+5. **CLAIM** — only mark CONFIRMED if evidence quote directly supports the claim
+
+| Evidence Quality | Verdict |
+|-----------------|---------|
+| Exit code 0 only, no output read | INSUFFICIENT — re-run and read output |
+| Output read but no quote matched to claim | UNCONFIRMED — cite specific evidence |
+| Quote matches claim exactly | CONFIRMED |
+| Quote contradicts claim | CONTRADICTED |
+
 ## Verdict Rules
 
 ```
@@ -137,6 +169,7 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Evidence from a DIFFERENT test run (stale) | HIGH | Check that evidence timestamp/context matches current changes |
 | Agent pre-generates evidence by running commands proactively | LOW | This is actually GOOD behavior — we want agents to provide evidence |
 | Completion-gate itself claims "all confirmed" without evidence | CRITICAL | Gate report MUST include the evidence table — no table = report is invalid |
+| Existence Theater — agent creates files but they're stubs | HIGH | Step 1b stub detection: grep for Placeholder/TODO/NotImplementedError in new files |
 
 ## Done When
 

package/skills/context-engine/SKILL.md

@@ -117,6 +117,19 @@ Block further tool calls until compaction is acknowledged.
 
 Emit the context health report to the calling skill.
 
+### Step 6b — Context Percentage Advisory
+
+In addition to tool-call counting, monitor context window percentage when available:
+
+| Remaining | Level | Action |
+|-----------|-------|--------|
+| >35% | SAFE | Continue normally |
+| 25-35% | WARNING | Advise: "Context at ~[X]%. Consider /compact at next phase boundary" |
+| <25% | CRITICAL | Save state via session-bridge → recommend immediate /compact |
+
+Debounce: emit advisory max once per 5 tool calls to avoid noise.
+Tool-call thresholds (Steps 1-2) remain the primary signal. Percentage advisory is supplementary — use when CLI status bar data is available.
+
 ## Context Health Levels
 
 ```

package/skills/cook/SKILL.md

@@ -556,6 +556,27 @@ cook instance → commit → push → create PR → wait CI
   IF 3 retries fail → escalate to user with CI logs
 ```
 
+### Formal Pause/Resume (`.continue-here.md`)
+
+When cook must pause mid-phase (context limit, user break, session end before phase completes):
+
+1. Create `.rune/.continue-here.md` with structured handoff:
+```markdown
+## Continue Here
+- **Phase**: [current phase number and name]
+- **Task**: [current task within phase — e.g., "Task 3 of 5"]
+- **Completed**: [list of tasks done this session]
+- **Remaining**: [list of tasks not yet started]
+- **Decisions**: [any decisions made this session]
+- **Blockers**: [if any — what's stuck and why]
+- **WIP Files**: [files modified but not yet committed]
+```
+2. Create a WIP commit: `wip: cook phase N paused at task M`
+3. Phase 0 (RESUME CHECK) detects `.continue-here.md` → resumes from exact task position
+4. After successful resume and phase completion → delete `.continue-here.md`
+
+This is more granular than Phase 0's plan-level resume — it resumes within a phase, not just between phases.
+
 ### Exit Conditions (Mandatory for Autonomous Runs)
 
 Every cook invocation inside `team` or autonomous workflows MUST have exit conditions:
@@ -592,6 +613,20 @@ When cook completes (whether standalone or invoked by `team`), it MUST return on
 
 **BLOCKED format**: Include the phase, the sub-skill that emitted BLOCKED, the specific blocker, and what was already attempted.
 
+## Deviation Rules
+
+When implementation diverges from plan:
+
+| Rule | Scope | Action | Example |
+|------|-------|--------|---------|
+| R1: Bug fix | Code doesn't work as planned | Auto-fix, continue | Test fails due to typo, missing import |
+| R2: Security fix | Vulnerability discovered | Auto-fix, continue | SQL injection, XSS, hardcoded secret |
+| R3: Blocking fix | Can't proceed without change | Auto-fix, continue | Missing dependency, wrong API signature |
+| R4: Architectural change | Different approach than planned | **ASK user first** | New database table, changed API contract, different library |
+
+R1-R3: security primitives and correctness fixes are NOT features — fix silently.
+R4: if you catch yourself thinking "this is a better way" — STOP and ask. The plan was approved for a reason.
+
 ## Error Recovery
 
 | Phase | If this fails... | Do this... |
@@ -605,6 +640,23 @@ When cook completes (whether standalone or invoked by `team`), it MUST return on
 | 5c REVIEW | Code quality issues | Fix CRITICAL/HIGH → re-review (max 2 loops) |
 | 6 VERIFY | Build/lint/type fails | Fix → re-run verification |
 
+### Repair Operators (before escalation)
+
+When a task fails during Phase 4 (IMPLEMENT):
+
+| Operator | When | Action |
+|----------|------|--------|
+| **RETRY** | Transient failure (network, timeout, flaky test) | Re-run same approach, max 2 attempts |
+| **DECOMPOSE** | Task too complex, partial progress | Split into 2-3 smaller tasks, continue |
+| **PRUNE** | Approach fundamentally wrong | Remove failed code, try different approach from plan |
+
+**Budget**: 2 repair attempts per task. After 2 failures → escalate:
+- Same error both times → `debug` for root cause
+- Different errors → `plan` to redesign the task
+- All approaches exhausted → `brainstorm(rescue)` for alternative category
+
+Do NOT ask user until repair budget is spent.
+
 ## Called By (inbound)
 
 - User: `/rune cook` direct invocation — primary entry point
@@ -641,6 +693,24 @@ When cook completes (whether standalone or invoked by `team`), it MUST return on
 - `worktree` (L3): Phase 4 — worktree isolation for parallel implementation
 - L4 extension packs: Phase 1.5 — domain-specific patterns when stack matches (see Phase 1.5 mapping table)
 
+## Analysis Paralysis Guard
+
+<HARD-GATE>
+5+ consecutive read-only tool calls (Read, Grep, Glob) without a single write action (Edit, Write, Bash) = STUCK.
+
+You MUST either:
+1. **Act** — write code, run a command, create a file
+2. **Report BLOCKED** — state the specific missing piece: "Cannot proceed because [X]"
+
+Stuck patterns (all banned):
+- Reading 10+ files to "fully understand" before acting
+- Grepping every variation of a string across the entire repo
+- Reading the same file twice in one investigation
+- "Let me check one more thing" — repeated after 5 reads
+
+A wrong first attempt that produces feedback beats perfect understanding that never ships.
+</HARD-GATE>
+
 ## Constraints
 
 1. MUST run scout before planning — no plan based on assumptions alone
@@ -699,6 +769,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Not escalating to sentinel:opus on security-sensitive tasks | MEDIUM | Auth, crypto, payment code → sentinel must run at opus, not sonnet |
 | Running Phase 5 checks sequentially instead of parallel | MEDIUM | Launch preflight+sentinel+review as parallel Task agents for speed |
 | Saying "done" without evidence trail | CRITICAL | completion-gate validates claims — UNCONFIRMED = BLOCK |
+| Analysis paralysis — 5+ reads without writing | HIGH | Analysis Paralysis Guard: act on incomplete info or report BLOCKED with specific missing piece |
 | Fast mode on security-relevant code | HIGH | Fast mode auto-excludes auth/crypto/payments — never fast-track security code |
 | Loading all phase files at once into context | HIGH | Phase File Gate: load ONLY the active phase file — one phase per session |
 | Resuming without checking master plan | MEDIUM | Phase 0 (RESUME CHECK) runs before Phase 1 — detects existing plans |

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 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.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.5.0"
   layer: L2
   model: sonnet
   group: development
@@ -89,6 +89,21 @@ When the error appears deep in execution (wrong directory, wrong path, wrong val
 
 Rule: NEVER fix where the error appears. Trace back to where invalid data originated.
 
+#### Instrumentation Tip: Use console.error, Not Loggers
+When adding diagnostic instrumentation, use `console.error()` (stderr) — NOT application loggers. Loggers are configured to suppress output based on log level or environment (e.g., `LOG_LEVEL=warn` silences `logger.debug`). `console.error` bypasses all logger configuration and writes directly to stderr. This is counterintuitive but critical — the one time you NEED debug output is exactly when loggers are configured to hide it.
+
+#### Defense-in-Depth (After Root Cause Found)
+When the root cause is invalid data flowing through multiple layers, recommend fixing at ALL layers — not just the source:
+
+| Layer | Purpose | Example |
+|-------|---------|---------|
+| Layer 1: Entry Point | Reject invalid input at API/CLI boundary | Validate not empty, exists, correct type |
+| Layer 2: Business Logic | Ensure data makes sense for the operation | Validate required params before processing |
+| Layer 3: Environment Guards | Prevent dangerous operations in specific contexts | Refuse destructive ops outside allowed dirs |
+| Layer 4: Debug Instrumentation | Capture context for forensics | Stack trace logging before dangerous operations |
+
+All four layers are necessary. During testing, each layer catches bugs the others miss — different code paths bypass single validation points. When recommending a fix via `rune:fix`, explicitly call out which layers need validation added.
+
 #### Multi-Component Instrumentation (for systems with 3+ layers)
 
 When the system has multiple components (CI → build → deploy, API → service → DB):
@@ -101,6 +116,49 @@ Before hypothesizing, add diagnostic logging at EACH component boundary:
 
 This reveals: "secrets reach workflow ✓, workflow reaches build ✗" — pinpoints the failing layer.
 
+### Step 2b: Instrument with Preserved Markers
+
+When adding diagnostic logging or instrumentation during investigation, mark ALL additions with region markers:
+
+```
+// #region agent-debug — [hypothesis being tested]
+console.log('[DEBUG] value at boundary:', data);
+// #endregion agent-debug
+```
+
+Language-appropriate equivalents:
+- Python: `# region agent-debug` / `# endregion agent-debug`
+- Rust: `// region agent-debug` / `// endregion agent-debug`
+
+**Why preserved markers matter:**
+- `rune:fix` will preserve these markers until the bug is fully resolved and tests pass
+- If the bug recurs, markers show exactly what was previously instrumented
+- Cleaning up debug traces before the fix is verified prevents learning from failure history
+- After fix is verified + tests pass → fix will clean up markers in a final pass
+
+<HARD-GATE>
+ALL diagnostic code added during debug MUST be wrapped in `#region agent-debug` markers.
+Unmarked instrumentation will be treated as stray code and removed prematurely.
+</HARD-GATE>
+
+### Step 2c: Check Debug Knowledge Base
+
+Before forming hypotheses, check `.rune/debug/knowledge-base.md`:
+- If file exists → search for matching symptoms/error messages
+- If match found → try known fix FIRST, skip hypothesis cycle
+- If no match → proceed to Step 3
+
+After successful root cause identification (Step 5), append entry:
+```
+### [date] — [symptom summary]
+- **Symptom**: [error message or behavior]
+- **Root Cause**: [what was actually wrong]
+- **Fix**: [what resolved it]
+- **Files**: [affected files]
+```
+
+This prevents re-debugging the same issue across sessions.
+
 ### Step 3: Form Hypotheses
 
 List exactly 2-3 possible root causes — no more, no fewer.
@@ -163,6 +221,16 @@ Produce structured output and hand off to rune:fix.
 - Call `rune:fix` with the full report if fix is needed
 - Do NOT apply any code changes — report only
 
+## Analysis Paralysis Guard
+
+<HARD-GATE>
+Debug is read-heavy by nature — but there are limits.
+
+After Step 4 (Test Hypotheses): if NO hypothesis is confirmed after 3 cycles of Steps 2-4, you MUST stop and escalate. Do NOT start cycle 4. Report all evidence gathered and escalate to problem-solver or sequential-thinking.
+
+Within any single step: 5+ consecutive Read/Grep calls without forming or testing a hypothesis = stuck. Stop reading, form a hypothesis from what you have, and test it. Incomplete hypotheses that get tested are better than perfect hypotheses that never form.
+</HARD-GATE>
+
 ## Red Flags — STOP and Return to Step 2
 
 If you catch yourself thinking any of these, you are GUESSING, not debugging:
@@ -174,6 +242,7 @@ If you catch yourself thinking any of these, you are GUESSING, not debugging:
 - "Here are the main problems: [lists fixes without investigation]"
 - Proposing solutions before tracing data flow
 - "One more fix attempt" (when already tried 2+)
+- "Let me read one more file before forming a hypothesis" (after 5+ reads)
 
 ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 
@@ -231,6 +300,7 @@ ALL of these mean: STOP. Return to Step 2 (Gather Evidence).
 | Same bug "fixed" 3+ times without questioning architecture | CRITICAL | 3-Fix Escalation Rule: classify failure → same blocker category = brainstorm(rescue), different bugs = plan redesign |
 | Escalating to plan when the APPROACH is wrong (not the module) | HIGH | If all 3 fixes hit the same category of blocker (API limit, platform gap), the approach needs pivoting via brainstorm(rescue), not re-planning |
 | Not tracking fix attempt number for recurring bugs | HIGH | Debug Report MUST include Fix Attempt counter — enables escalation gate |
+| Adding instrumentation without region markers | MEDIUM | All debug logging MUST use `#region agent-debug` — unmarked code gets cleaned up prematurely by fix |
 
 ## Done When
 

package/skills/design/SKILL.md

@@ -57,6 +57,17 @@ Load the design knowledge base before reasoning:
 
 > **Why two layers**: The baseline ships "good enough" universal design knowledge. Users who care about aesthetics create their own `design-dna.md` with curated palettes, font pairings, and style preferences. The design skill works well with either — it just works _better_ with a curated reference.
 
+### External Data Source
+
+Design intelligence data from [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) (MIT, 42.8k★).
+Located at `references/ui-pro-max-data/` — 161 palettes, 84 styles, 73 font pairings, 161 reasoning rules, 99 UX guidelines.
+
+When `references/ui-pro-max-data/` is available:
+- Step 2: query `styles.csv` for domain-matched visual styles (expands from 10 → 84)
+- Step 3: query `ui-reasoning.csv` for industry-specific design rules (161 rules)
+- Step 3: query `colors.csv` for palette alternatives (expands from 10 → 161)
+- Step 6 (Anti-AI): cross-check proposed style against reasoning DB — if flagged as "AI-generic", suggest 3 alternatives
+
 ### Step 1 — Discover
 
 Invoke `scout` to detect:

package/skills/fix/SKILL.md

@@ -3,7 +3,7 @@ name: fix
 description: Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L2
   model: sonnet
   group: development
@@ -112,6 +112,17 @@ Single validation at one point can be bypassed by different code paths, refactor
 
 Apply this when: the bug was caused by invalid data flowing through multiple layers. Skip for trivial one-liner fixes.
 
+### Step 5b: Preserve Debug Instrumentation
+
+If `rune:debug` left `#region agent-debug` markers in the code:
+
+1. **During fix**: DO NOT remove these markers — they capture the investigation trail
+2. **After fix verified** (tests pass, lint pass): scan for `#region agent-debug` markers
+3. **Remove markers and their contents** in a final cleanup pass ONLY after full verification
+4. If the fix is partial or tests still fail → KEEP all markers for the next debug cycle
+
+**Why:** Premature cleanup of debug instrumentation erases failure history. If the bug recurs after cleanup, the next debug session starts from zero. Keeping markers until verification means downstream skills can see what was already investigated.
+
 ### Step 6: Self-Review
 
 Verify correctness of the changes just made.
@@ -141,6 +152,19 @@ Produce a structured summary of all changes made.
 5. MUST follow project conventions found by scout — don't invent new patterns
 6. MUST NOT add unplanned features while fixing — fix only what was diagnosed
 7. MUST track fix attempt number — this feeds debug's 3-Fix Escalation classification
+8. MUST preserve `#region agent-debug` markers until fix is fully verified — cleanup only after tests pass
+
+## Scope Gate
+
+| Change Type | Action |
+|-------------|--------|
+| Bug fix (diagnosed cause) | Fix it |
+| Security fix (found during fix) | Fix it + flag to sentinel |
+| Blocking issue (can't complete fix without) | Fix it + document in report |
+| Unrelated improvement | **STOP — create separate task** |
+| Architectural change | **STOP — escalate to cook/plan** |
+
+If fix requires touching >3 files not in the diagnosis → re-diagnose. You're probably fixing a symptom.
 
 ## Mesh Gates
 
@@ -182,6 +206,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Not running tests after each individual change | MEDIUM | Constraint 3: never batch untested changes — run tests after each edit |
 | Fixing at crash site without tracing data origin | HIGH | Defense-in-depth: trace where bad data ORIGINATES, add validation at every layer it passes through |
 | Single-point validation (fix one spot, hope it holds) | MEDIUM | Step 5: add entry + business logic + environment + debug layers for data-flow bugs |
+| Removing debug instrumentation before fix is verified | MEDIUM | Step 5b: preserve `#region agent-debug` markers until all tests pass — premature cleanup erases failure history |
 
 ## Done When
 

package/skills/plan/SKILL.md

@@ -171,6 +171,11 @@ Save to `.rune/plan-<feature>.md`:
 - <decision 1 — chosen approach and why>
 - <decision 2>
 
+## Decision Compliance
+- Decisions (locked): [list from requirements.md — plan MUST honor these]
+- Discretion (agent): [list — agent chose X because Y]
+- Deferred: [list — explicitly excluded from this feature]
+
 ## Architecture
 <brief system diagram or component list — NOT implementation detail>
 
@@ -226,17 +231,27 @@ function validateInput(raw: unknown): TradeEntry[];  // throws ValidationError
 ```
 
 ## Tasks
+
+Each task MUST include: **File** (exact path), **Test** (test file or N/A), **Verify** (shell command), **Commit** (semantic message). Granularity: 2-5 min per task. If >10min, decompose.
+
 - [ ] Task 1 — Create calculateProfit function
-  - File: `src/foo/bar.ts`
-  - Create: `function calculateProfit(entries: TradeEntry[]): ProfitResult`
+  - File: `src/foo/bar.ts` (new)
+  - Test: `tests/foo/bar.test.ts` (new)
+  - Verify: `npm test -- --grep "calculateProfit"`
+  - Commit: `feat(trading): add calculateProfit with fee calculation`
   - Logic: sum entries by side, apply fees (0.1% per trade), return net P&L
   - Edge: empty array → return { netPnL: 0, totalFees: 0, winRate: 0 }
 - [ ] Task 2 — Add input validation
-  - File: `src/foo/baz.ts`
-  - Modify: add `validateInput()` before processing
+  - File: `src/foo/baz.ts` (modify)
+  - Test: `tests/foo/baz.test.ts` (new)
+  - Verify: `npm test -- --grep "validateInput"`
+  - Commit: `feat(trading): add input validation for trade entries`
   - Logic: check side is 'long'|'short', prices > 0, quantity > 0
-- [ ] Task 3 — Write tests
-  - File: `tests/foo/bar.test.ts`
+- [ ] Task 3 — Write integration tests
+  - File: `tests/foo/bar.test.ts` (modify)
+  - Test: N/A — this IS the test task
+  - Verify: `npm test -- --grep "trading" && npx tsc --noEmit`
+  - Commit: `test(trading): add integration tests for edge cases`
   - Cases: happy path, empty input, negative values, overflow
 
 ## Failure Scenarios
@@ -503,6 +518,8 @@ Max 200 lines. Self-contained — coder needs ONLY this file.
 | Plan without scout context — invented file paths | CRITICAL | Step 1: scout first, always |
 | Phase with zero test tasks | CRITICAL | HARD-GATE rejects it |
 | 10+ phases overwhelming the master plan | MEDIUM | Max 8 phases — split into sub-projects if more |
+| Task without File path or Verify command | HIGH | Every task MUST have File + Test + Verify + Commit fields — no vague "implement the feature" tasks |
+| Plan ignores locked Decisions from BA | CRITICAL | Decision Compliance section cross-checks requirements.md — locked decisions are non-negotiable |
 
 ## Done When
 

package/skills/review/SKILL.md

@@ -378,6 +378,8 @@ LOW       — style inconsistency, naming suggestion, minor refactor opportunity
 | Skipping UI anti-pattern checks for frontend changes | MEDIUM | Any .tsx/.jsx/.svelte/.vue in diff → MUST run UI/UX Anti-Pattern Checks section |
 | Skipping spec compliance check (Step 5.5 Stage 1) | HIGH | Code quality without spec check ships clean code that does the wrong thing — always load the plan/ticket before reviewing quality |
 | Treating purple/indigo accent as "just a color choice" | MEDIUM | It is a documented AI-generated UI signature — always flag for domain justification |
+| Suggesting "add X" without checking if X is used | MEDIUM | YAGNI pushback: grep codebase for the suggested feature → if uncalled anywhere → respond "Not called anywhere. Remove? (YAGNI)". Valid pushback, not laziness |
+| Adding abstractions "for future flexibility" | MEDIUM | Three similar lines > premature abstraction. Only abstract when there are 3+ concrete callers today |
 
 ## Done When
 

package/skills/skill-forge/SKILL.md

@@ -3,7 +3,7 @@ name: skill-forge
 description: Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship.
 metadata:
   author: runedev
-  version: "1.0.0"
+  version: "1.2.0"
   layer: L2
   model: opus
   group: creation
@@ -106,6 +106,33 @@ Follow `docs/SKILL-TEMPLATE.md` format. Required sections:
 | Cost Profile | YES | Token estimate |
 | Mesh Gates | L1/L2 only | Progression guards |
 
+#### SKILL.md Anatomy — WHY vs HOW Split
+
+A skill file answers WHY and WHEN — not HOW. Code examples, syntax references, and implementation patterns belong in separate files:
+
+```
+skills/[name]/
+├── SKILL.md          ← WHY: purpose, triggers, constraints, sharp edges (~150-300 lines)
+├── references/       ← HOW: code patterns, syntax tables, API examples
+│   ├── patterns.md   ← Implementation patterns with code blocks
+│   └── gotchas.md    ← Language/framework-specific pitfalls
+└── scripts/          ← WHAT: deterministic operations (shell, node)
+```
+
+**Rules:**
+1. SKILL.md MUST NOT contain code blocks longer than 10 lines — move to `references/`
+2. One excellent inline example (≤10 lines) is OK for clarity — more than that is a smell
+3. Format templates (Output Format section) are NOT code — they stay in SKILL.md
+4. Pressure test scenarios (Phase 2) are NOT code — they stay in SKILL.md
+5. If a skill has >3 code blocks → create `references/` and extract them
+
+**Why this matters:** Code blocks in SKILL.md inflate context tokens on EVERY invocation. References are loaded only when needed. A 500-line SKILL.md with 200 lines of code examples should be a 300-line SKILL.md + a 200-line references file.
+
+<HARD-GATE>
+Code blocks in SKILL.md > 10 lines = review failure.
+Extract to references/ or scripts/. No exceptions.
+</HARD-GATE>
+
 #### Frontmatter Rules
 
 ```yaml
@@ -119,11 +146,16 @@ metadata:
 ---
 ```
 
-**Description rules:**
+**Description rules (CSO Discipline):**
 - MUST start with "Use when..."
 - MUST describe triggering conditions, NOT workflow
 - MUST be third person
 - MUST NOT summarize what the skill does internally
+- AI reads description → decides whether to invoke → if description contains workflow summary, AI skips reading the full SKILL.md content (it thinks it already knows)
+- Test: if you can execute the skill from the description alone, the description leaks too much
+
+Bad: "Analyzes code quality through 6-step process: scan files, check patterns, run linters, compare metrics, generate report, suggest fixes"
+Good: "Use when code changes need quality review before commit. Symptoms: PR ready, refactor complete, pre-release check."
 
 ```yaml
 # BAD: Summarizes workflow — agent reads description, skips full content
@@ -182,6 +214,62 @@ Run additional pressure scenarios with varied pressures. For each new failure:
 
 Repeat until no new failures emerge in 2 consecutive test runs.
 
+#### Pressure Types for Test Scenarios
+
+Best tests combine 3+ pressures simultaneously:
+
+| Pressure | Example Scenario |
+|----------|------------------|
+| Time | "Emergency deployment, deadline in 30 min" |
+| Sunk cost | "Already wrote 200 lines, can't restart" |
+| Authority | "Senior dev says skip testing" |
+| Economic | "Customer churning, ship now or lose $50k MRR" |
+| Exhaustion | "50 tool calls deep, context filling up" |
+| Social | "Looking dogmatic by insisting on process" |
+| Pragmatic | "Being practical vs being pedantic" |
+
+#### Scenario Quality Requirements
+
+1. **Concrete A/B/C options** — force explicit choice (no "I'd ask the user" escape hatch)
+2. **Real constraints** — specific times, actual consequences, named files
+3. **Real file paths** — `/tmp/payment-system` not "a project"
+4. **"Make agent ACT"** — "What do you do?" not "What should you do?"
+5. **No easy outs** — every option has a cost
+
+#### Meta-Testing (When GREEN Isn't Working)
+
+If the agent keeps failing even WITH the skill loaded, ask: "How could that skill have been written differently to make the correct option crystal clear?"
+
+Three possible responses:
+1. "Skill was clear, I chose to ignore it" → foundational principle needed (stronger HARD-GATE)
+2. "Skill should have said X explicitly" → add that exact phrasing verbatim
+3. "I didn't see section Y" → reorganize for discoverability (move up, add header)
+
+#### Bulletproof Criteria
+
+A skill is bulletproof when:
+- Agent chooses correct option under maximum pressure (3+ pressures combined)
+- Agent CITES skill sections as justification for its choice
+- Agent ACKNOWLEDGES the temptation but follows the rule anyway
+
+#### Persuasion Principles for Skill Language
+
+Research (Meincke et al., 2025, 28,000 conversations) shows 33% → 72% compliance with these techniques:
+
+| Principle | Application | Use For |
+|-----------|-------------|---------|
+| Authority | "YOU MUST", imperative language | Eliminates decision fatigue, safety-critical rules |
+| Commitment | Explicit announcements + tracked choices | Creates accountability trail |
+| Scarcity | Time-bound requirements, "before proceeding" | Triggers immediate action |
+| Social Proof | "Every time", universal statements | Documents what prevents failures |
+| Unity | "We're building quality" language | Shared identity, quality goals |
+
+**Prohibited in skills:**
+- **Liking** ("Great job following the process!") → creates sycophancy
+- **Reciprocity** ("I helped you, now follow the rules") → feels manipulative
+
+**Ethical test**: Would this serve the user's genuine interests if they fully understood the technique?
+
 ### Phase 6 — INTEGRATE
 
 Wire the skill into the mesh:
@@ -302,10 +390,13 @@ Techniques:
 | Skill passes test but breaks mesh connections | MEDIUM | Phase 6 integration: verify output compatibility |
 | Editing skill without testing the edit | MEDIUM | Adapting section: same TDD cycle for edits |
 | Overly verbose skill burns context tokens | MEDIUM | Token efficiency guidelines: layer-based word targets |
+| Code blocks in SKILL.md bloat every invocation | HIGH | WHY vs HOW split: SKILL.md ≤10-line code blocks, extract rest to references/ |
+| Writing skill without TDD (no observed failures first) | CRITICAL | Skill TDD: RED (run scenario WITHOUT skill → document failures) → GREEN (write skill targeting failures) → REFACTOR (find bypasses → add blocks) |
+| Description leaks workflow → agent skips full content | HIGH | CSO Discipline: description = triggers only. Test: can you execute from description alone? If yes, it leaks too much |
 
 ## Done When
 
-- Baseline test documented with observed failures
+- Baseline test documented with observed failures (TDD RED phase)
 - SKILL.md follows template format completely
 - Skill passes pressure test (agent complies with skill loaded)
 - No new failures in 2 consecutive varied-pressure test runs