continuous-improvement 3.9.2 → 3.12.3

package/commands/audit.md

@@ -0,0 +1,34 @@
+---
+name: audit
+description: Audit a window of recent commits for real defects, confirm each finding before fixing, verify every surface a fix touches, then report confirmed/dismissed/no-op with evidence. Enforces Law 4 (Verify Before Reporting).
+---
+
+# /audit — Confirm Recent Commits Before You Trust Them
+
+Run the audit-driven loop over recent work: a merged commit with green CI is a claim, not a proof.
+
+## What it does
+
+Takes a commit window, hunts for real defects one concern at a time, proves each finding against the actual code (false positives die before any edit), fixes on a branch with the smallest diff, verifies every surface the fix touches, and reports honestly. Backed by the `audit` skill.
+
+## The loop
+
+```
+1. Scope    git log to pick the window (e.g. HEAD~10..HEAD, or main since last release)
+2. Find     one pass per dimension: value/economy drift, concurrency, surface coverage, type/contract
+3. Confirm  read the actual lines; state in one sentence why it is real, or dismiss it
+4. Fix      one concern per commit; prefer a failing test first, then green
+5. Verify   exercise EVERY surface (backend, frontend, admin, cache, migration), not just the edited one
+6. Report   confirmed (with the proof), dismissed (with why), no-op (in scope, nothing to change)
+```
+
+## Default skeptical
+
+Findings are hypotheses. Default each to a false positive until the code proves the bug — defaulting to "real" is how plausible-but-wrong fixes ship. For a thorough audit, fan the find pass out across dimensions with parallel reviewers, then verify each survivor adversarially.
+
+## Pairs with
+
+- **`audit`** skill — the discipline this command runs.
+- **`code-review`** / **`security-review`** — the per-dimension passes.
+- **`reconcile`** — the safe branch→PR path once the audit produces a fix.
+- **`recall`** — check whether a finding was already hit and fixed before.

package/commands/companion-preference.md

@@ -0,0 +1,58 @@
+---
+name: companion-preference
+description: Inspect companion-preference hook telemetry — counts by CI skill, action breakdown, and companion-installed%.
+---
+
+# /companion-preference
+
+Read and aggregate the JSONL telemetry written by `hooks/companion-preference.mjs`. Reports per-skill totals, action breakdown (`observation`, `advisory`, `block`, `block-not-installed`), and the share of events where the companion plugin was installed at the time.
+
+The dataset is the evidence base for a future `companions-first` default-flip decision — once a 7-day shadow shows the `companions-first` path firing on a meaningful share of routed Skill calls, with companions installed in the majority of them, the flip is grounded.
+
+## Trigger phrases
+
+- `/companion-preference`
+- `/companion-preference status`
+- "show companion preference stats"
+- "what does the companion-preference hook see"
+
+## What happens
+
+1. Run `node bin/companion-preference-status.mjs` from the repo root with the operator's chosen window. Default `--days 7`. Pass `--all` for the entire file or `--days N` for a different window.
+2. Render the table the CLI emits to the user verbatim. Do not paraphrase the numbers — the JSONL is authoritative.
+3. If the CLI prints "no telemetry recorded yet," check three things in order: (a) `~/.claude/settings.json` has `continuous_improvement.companion_preference` set (otherwise the hook is a no-op and writes nothing); (b) the user has invoked at least one mapped CI skill (`tdd-workflow`, `verification-loop`, `context-budget`, `ralph`, `learn-eval`) since the hook landed; (c) the hook's PreToolUse registration is intact in `plugins/continuous-improvement/hooks/hooks.json`.
+4. Offer one decision-ready next step based on the totals — e.g., "ratio of `observation` rows with `companion_installed=true` suggests `companions-first` is safe to flip for X but not Y."
+
+## Subcommands
+
+### `/companion-preference status` (default)
+
+Same as `/companion-preference`.
+
+### `/companion-preference status --json`
+
+Emit the machine-readable JSON report. Useful when you want to pipe the output into another tool or write your own aggregator.
+
+```bash
+node bin/companion-preference-status.mjs --json --all
+```
+
+## CLI flags
+
+| Flag | Effect |
+|---|---|
+| `--days N` | Only count events from the last N days (default 7). |
+| `--all` | Ignore the window; count every row in the file. |
+| `--json` | Emit a machine-readable JSON report. |
+| `--path <file>` | Override the default JSONL path. Used by the test suite; rarely needed in practice. |
+| `-h`, `--help` | Print CLI help and exit. |
+
+## Path resolution
+
+By default the CLI reads `~/.claude/instincts/<project-hash>/companion-preference.jsonl`, where the hash is the same `sha256(projectRoot).slice(0, 12)` that the hook itself uses. The project root resolves via `CLAUDE_PROJECT_DIR` env var if set, else `git rev-parse --show-toplevel`, else the literal `"global"`. Hash and path scheme are reused verbatim from `hooks/companion-preference.mjs` to keep the read side aligned with the write side.
+
+## Companion skills
+
+- `hooks/companion-preference.mjs` — the writer that produces the JSONL this command reads.
+- `skills/superpowers.md` § "Companion-Preference Override" — the broader contract for the setting this command's dataset measures.
+- `commands/dashboard.md` — the broader continuous-improvement status surface; this command is the dispatcher-bias-specific narrower view.

package/commands/continuous-improvement.md

@@ -1,115 +1,115 @@
----
-name: continuous-improvement
-description: "Reflect on the current session, analyze observations for patterns, and show instinct status. Runs on-demand to save tokens."
----
-
-# /continuous-improvement
-
-Run this when you want to reflect and learn — not every session. Three steps in order.
-
-## Step 1: Reflect
-
-Generate a reflection for this session based on what happened:
-
-```
-## Reflection — [Date]
-- What worked:
-- What failed:
-- What I'd do differently:
-- Rule to add:
-- Iteration — Next best recommendations (ranked, top 3):
-  1. <primary — strongest next move>
-  2. <alternative — different angle>
-  3. <alternative — smaller/larger scope>
-```
-
-If there's a "Rule to add", create an instinct YAML file with 0.6 starting confidence in the project's instinct directory.
-
-The "Iteration — Next best recommendations" field is the Law 6 handoff. List the **top 3 ranked** core-development moves — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest; #2 and #3 are alternatives the user can pivot to. NOT git steps (commit, push, PR), NOT verification re-runs, NOT deploy actions — those belong in the end-of-run summary.
-
-Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.
-
-Rules: always exactly 3 distinct directions, not padding. If fewer real moves exist, fill remaining slots with `None — goal met from this angle.` If the goal is fully met across all angles, write `1. None — goal met, stop.` and omit #2 and #3.
-
-## Step 2: Analyze Observations
-
-Check `~/.claude/instincts/` for the current project (detect via git root → SHA-256 first 12 chars).
-
-Look at `~/.claude/instincts/<hash>/observations.jsonl`. If 20+ lines exist:
-
-1. Read the last 500 lines
-2. Read existing instinct `*.yaml` files (project + global)
-3. Detect patterns:
-   - User corrections → "don't do X" instincts
-   - Error→fix sequences → "when X fails, try Y"
-   - Repeated workflows (3+ times) → "for X, do A→B→C"
-   - Tool preferences → "use tool Y for task X"
-4. Create/update instinct YAML files
-5. Be conservative: only create instincts for 3+ observations of the same pattern
-
-If fewer than 20 observations, skip analysis and note the count.
-
-### Multi-Agent Analysis (500+ observations)
-
-When observation backlog is large, parallelize:
-- **Agent 1:** User corrections + error→fix patterns
-- **Agent 2:** Repeated workflows + tool preferences
-- **Agent 3:** Cross-reference existing instincts for updates
-
-Merge results and deduplicate before writing YAML files.
-
-## Step 3: Show Status
-
-Display all instincts for the current project + global:
-
-```
-=== continuous-improvement ===
-
-## Level: [CAPTURE | ANALYZE | SUGGEST | AUTO-APPLY]
-
-## Session Reflection
-- What worked: [from this session]
-- What failed: [from this session]
-- What I'd do differently: [from this session]
-- Rule to add: [captured as instinct]
-- Iteration — Next best recommendations (ranked, top 3):
-  1. [primary core-development move]
-  2. [alternative angle]
-  3. [alternative scope]
-
-## Learning
-  NEW  [instinct-id]        [domain]  [confidence]  (from reflection)
-   ↑   [instinct-id]        [domain]  [old]→[new]   (+N observations)
-
-## Instincts — [project-name] ([hash])
-  ● [0.85] instinct-id       domain   auto-apply
-  ◐ [0.60] instinct-id       domain   suggest
-  ○ [0.35] instinct-id       domain   silent
-
-## Instincts — global
-  ● [0.90] instinct-id       domain   auto-apply
-
-## Next
-- Keep working — hooks capture automatically
-- System auto-levels as instincts gain confidence
-```
-
-If no instincts or observations exist yet, explain this is expected — the system is in CAPTURE level and will create instincts after 20+ observations accumulate.
-
-## Subcommands
-
-### `/continuous-improvement weekly`
-
-Set up a weekly analysis schedule:
-1. Create a cron/loop schedule that runs `/continuous-improvement analyze` every 7 days
-2. Confirm the schedule to the user
-3. Show next scheduled run date
-
-### `/continuous-improvement always-on`
-
-Toggle always-on mode for the current project:
-1. Find project hash
-2. Create/update `~/.claude/instincts/<hash>/config.yaml` with `always_on: true|false`
-3. Confirm the change
-
-**Default is off** — observations accumulate silently, analysis only runs when you ask.
+---
+name: continuous-improvement
+description: "Reflect on the current session, analyze observations for patterns, and show instinct status. Runs on-demand to save tokens."
+---
+
+# /continuous-improvement
+
+Run this when you want to reflect and learn — not every session. Three steps in order.
+
+## Step 1: Reflect
+
+Generate a reflection for this session based on what happened:
+
+```
+## Reflection — [Date]
+- What worked:
+- What failed:
+- What I'd do differently:
+- Rule to add:
+- Iteration — Next best recommendations (ranked, top 3):
+  1. <primary — strongest next move>
+  2. <alternative — different angle>
+  3. <alternative — smaller/larger scope>
+```
+
+If there's a "Rule to add", create an instinct YAML file with 0.6 starting confidence in the project's instinct directory.
+
+The "Iteration — Next best recommendations" field is the Law 6 handoff. List the **top 3 ranked** core-development moves — what to build, fix, refactor, or investigate next so the feature/system advances. Item #1 is the strongest; #2 and #3 are alternatives the user can pivot to. NOT git steps (commit, push, PR), NOT verification re-runs, NOT deploy actions — those belong in the end-of-run summary.
+
+Format per item: `<verb> <object at path:line> (<why, one clause grounded in current context>)`.
+
+Rules: always exactly 3 distinct directions, not padding. If fewer real moves exist, fill remaining slots with `None — goal met from this angle.` If the goal is fully met across all angles, write `1. None — goal met, stop.` and omit #2 and #3.
+
+## Step 2: Analyze Observations
+
+Check `~/.claude/instincts/` for the current project (detect via git root → SHA-256 first 12 chars).
+
+Look at `~/.claude/instincts/<hash>/observations.jsonl`. If 20+ lines exist:
+
+1. Read the last 500 lines
+2. Read existing instinct `*.yaml` files (project + global)
+3. Detect patterns:
+   - User corrections → "don't do X" instincts
+   - Error→fix sequences → "when X fails, try Y"
+   - Repeated workflows (3+ times) → "for X, do A→B→C"
+   - Tool preferences → "use tool Y for task X"
+4. Create/update instinct YAML files
+5. Be conservative: only create instincts for 3+ observations of the same pattern
+
+If fewer than 20 observations, skip analysis and note the count.
+
+### Multi-Agent Analysis (500+ observations)
+
+When observation backlog is large, parallelize:
+- **Agent 1:** User corrections + error→fix patterns
+- **Agent 2:** Repeated workflows + tool preferences
+- **Agent 3:** Cross-reference existing instincts for updates
+
+Merge results and deduplicate before writing YAML files.
+
+## Step 3: Show Status
+
+Display all instincts for the current project + global:
+
+```
+=== continuous-improvement ===
+
+## Level: [CAPTURE | ANALYZE | SUGGEST | AUTO-APPLY]
+
+## Session Reflection
+- What worked: [from this session]
+- What failed: [from this session]
+- What I'd do differently: [from this session]
+- Rule to add: [captured as instinct]
+- Iteration — Next best recommendations (ranked, top 3):
+  1. [primary core-development move]
+  2. [alternative angle]
+  3. [alternative scope]
+
+## Learning
+  NEW  [instinct-id]        [domain]  [confidence]  (from reflection)
+   ↑   [instinct-id]        [domain]  [old]→[new]   (+N observations)
+
+## Instincts — [project-name] ([hash])
+  ● [0.85] instinct-id       domain   auto-apply
+  ◐ [0.60] instinct-id       domain   suggest
+  ○ [0.35] instinct-id       domain   silent
+
+## Instincts — global
+  ● [0.90] instinct-id       domain   auto-apply
+
+## Next
+- Keep working — hooks capture automatically
+- System auto-levels as instincts gain confidence
+```
+
+If no instincts or observations exist yet, explain this is expected — the system is in CAPTURE level and will create instincts after 20+ observations accumulate.
+
+## Subcommands
+
+### `/continuous-improvement weekly`
+
+Set up a weekly analysis schedule:
+1. Create a cron/loop schedule that runs `/continuous-improvement analyze` every 7 days
+2. Confirm the schedule to the user
+3. Show next scheduled run date
+
+### `/continuous-improvement always-on`
+
+Toggle always-on mode for the current project:
+1. Find project hash
+2. Create/update `~/.claude/instincts/<hash>/config.yaml` with `always_on: true|false`
+3. Confirm the change
+
+**Default is off** — observations accumulate silently, analysis only runs when you ask.

package/commands/dashboard.md

@@ -1,56 +1,56 @@
----
-name: dashboard
-description: Visual dashboard showing instinct health, observation stats, and learning progress
----
-
-# Instinct Dashboard
-
-Generate a visual dashboard for this project's continuous-improvement status.
-
-## Instructions
-
-1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars
-2. **Read observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
-3. **Read instincts:** Load all `*.yaml` files from project dir + `global/`
-4. **Read instinct packs:** Check if any packs from `instinct-packs/` have been loaded
-
-## Display Format
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║              continuous-improvement Dashboard                ║
-╠══════════════════════════════════════════════════════════════╣
-║                                                              ║
-║  Project: <name>              Level: <CAPTURE|ANALYZE|...>   ║
-║  Sessions: ~<obs/10>          Mode: <beginner|expert>        ║
-║                                                              ║
-║  ┌─ Observations ────────────────────────────────────────┐   ║
-║  │  Total: <n>    Unprocessed: <n>    Last: <date>       │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-║  ┌─ Instincts ───────────────────────────────────────────┐   ║
-║  │  Total: <n>                                           │   ║
-║  │  ████████░░ Auto-apply (0.7+): <n>                    │   ║
-║  │  █████░░░░░ Suggest (0.5-0.69): <n>                   │   ║
-║  │  ██░░░░░░░░ Silent (< 0.5): <n>                       │   ║
-║  │  Global: <n>    Project: <n>                          │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-║  ┌─ Top Instincts ───────────────────────────────────────┐   ║
-║  │  <list top 5 instincts by confidence with bars>       │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-║  ┌─ Health ──────────────────────────────────────────────┐   ║
-║  │  Stale (30+ days): <n>    Decaying: <n>               │   ║
-║  │  Recently reinforced: <n>                             │   ║
-║  └───────────────────────────────────────────────────────┘   ║
-║                                                              ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-## After Display
-
-- If stale instincts > 0: suggest reviewing them
-- If unprocessed observations > 20: suggest running analysis
-- If no instincts exist: explain the auto-leveling timeline
-- Show available instinct packs that haven't been loaded yet
+---
+name: dashboard
+description: Visual dashboard showing instinct health, observation stats, and learning progress
+---
+
+# Instinct Dashboard
+
+Generate a visual dashboard for this project's continuous-improvement status.
+
+## Instructions
+
+1. **Find project hash:** Run `git rev-parse --show-toplevel 2>/dev/null`, then SHA-256 first 12 chars
+2. **Read observations:** Count lines in `~/.claude/instincts/<hash>/observations.jsonl`
+3. **Read instincts:** Load all `*.yaml` files from project dir + `global/`
+4. **Read instinct packs:** Check if any packs from `instinct-packs/` have been loaded
+
+## Display Format
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║              continuous-improvement Dashboard                ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Project: <name>              Level: <CAPTURE|ANALYZE|...>   ║
+║  Sessions: ~<obs/10>          Mode: <beginner|expert>        ║
+║                                                              ║
+║  ┌─ Observations ────────────────────────────────────────┐   ║
+║  │  Total: <n>    Unprocessed: <n>    Last: <date>       │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Instincts ───────────────────────────────────────────┐   ║
+║  │  Total: <n>                                           │   ║
+║  │  ████████░░ Auto-apply (0.7+): <n>                    │   ║
+║  │  █████░░░░░ Suggest (0.5-0.69): <n>                   │   ║
+║  │  ██░░░░░░░░ Silent (< 0.5): <n>                       │   ║
+║  │  Global: <n>    Project: <n>                          │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Top Instincts ───────────────────────────────────────┐   ║
+║  │  <list top 5 instincts by confidence with bars>       │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+║  ┌─ Health ──────────────────────────────────────────────┐   ║
+║  │  Stale (30+ days): <n>    Decaying: <n>               │   ║
+║  │  Recently reinforced: <n>                             │   ║
+║  └───────────────────────────────────────────────────────┘   ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+## After Display
+
+- If stale instincts > 0: suggest reviewing them
+- If unprocessed observations > 20: suggest running analysis
+- If no instincts exist: explain the auto-leveling timeline
+- Show available instinct packs that haven't been loaded yet

package/commands/discipline.md

@@ -33,6 +33,20 @@ The Laws above are the *how*. These five principles are the *why*: code ships fr
 
 Code is a liability, not an asset. Speed without these five turns into someone else's incident at 3am — except the someone is you.
 
+## Goal-Driven Execution maps onto the Laws
+
+"Goal-Driven Execution" is the operator's global principle #4 — tie every change to a stated goal, refuse scope creep, stop when the goal is met. It is not a separate Law here; it is the spine of four existing Laws:
+
+| Sub-rule of Goal-Driven Execution | Lives in |
+|---|---|
+| Tie work to a stated goal; if none, ask | Law 2 — the `## Goal` in `task_plan.md` is the single source of truth |
+| Catch drift away from that goal mid-session | Law 2 — the `goal-monitor` skill / `/goal-check` scores recent activity against the goal |
+| Finish one thing; refuse "while I'm here" scope creep | Law 3 |
+| Commit messages lead with the outcome, not the mechanism | Law 4 — "done" is an observed outcome |
+| Iterate one change at a time toward the goal | Law 6 |
+
+The `goal-monitor` primitive (`/goal-check`, `ci_goal_check`) is the measurable arm of this principle: it reads the `## Goal` section and reports ON GOAL / DRIFT / NO DATA. Run it at phase boundaries to confirm the work and the plan still agree.
+
 ## The Loop
 
 ```

package/commands/distill.md

@@ -0,0 +1,39 @@
+---
+name: distill
+description: Distill repeated successful tool sequences from the observation log into reusable draft instincts, with an explicit propose-edit-promote ladder. Enforces Law 7 (Learn From Every Session).
+---
+
+# /distill — Trajectory Distillation
+
+Mine this project's observation log for tool sequences that recurred across multiple successful sessions, and turn the good ones into reusable instincts.
+
+## What it does
+
+Groups observations into trajectories, keeps the ones that ended in a passing verification, and finds tool-sequence n-grams that recurred across distinct sessions. Backed by the `ci_distill_candidates` / `ci_distill_propose` / `ci_distill_promote` MCP tools (expert mode) and the `skill-distillation` skill.
+
+## The ladder
+
+```
+ci_distill_candidates           # list patterns that qualify (read-only)
+ci_distill_propose id=<id>       # write a DRAFT (placeholder body) to drafts/<id>.yaml
+# ... edit the draft body to capture the real recipe ...
+ci_distill_promote id=<id>       # promote to a live instinct at 0.5 confidence (SUGGEST)
+```
+
+Drafts never affect behavior until promoted. The draft starts at 0.4 confidence in a `drafts/` subdirectory the instinct loader ignores; promotion writes a live instinct at 0.5 (SUGGEST tier).
+
+## Candidate criteria
+
+- The trajectory must have ended in success (`verify-exit-0` or `reflection-pass`).
+- The tool sequence must have recurred at least 3 times across at least 2 distinct sessions.
+- A pattern repeated only within one session is rejected — that is repetition, not a reusable skill.
+
+## Why the human edit step
+
+A tool sequence is evidence, not a recipe. `Read → Edit → Bash → Edit → Bash` is a TDD loop, but the value is in the preconditions and concrete steps. Editing the draft body before promotion is the guard against fabricating confident skills from coincidental call ordering.
+
+## Pairs with
+
+- **`skill-distillation`** skill — the discipline this command runs.
+- **`continuous-improvement`** (core SKILL.md, Law 7 — Learn From Every Session).
+- **`recall`** — before promoting, check whether an existing instinct already covers the pattern.

package/commands/goal-check.md

@@ -0,0 +1,53 @@
+---
+name: goal-check
+description: Check whether recent tool activity still relates to the stated goal in task_plan.md, reporting a drift score and the top off-goal tool calls. Enforces Law 2 (Plan Is Sacred).
+---
+
+# /goal-check — Goal Drift Check
+
+Score this session's recent tool activity against the stated goal and report whether the work is still ON GOAL or has DRIFTed.
+
+## What it does
+
+Reads the `## Goal` section of `task_plan.md` (plus optional `## Goal Keywords` and `## Goal Scope` sections), scores the most recent observations from `~/.claude/instincts/<project-hash>/observations.jsonl`, and reports a drift score with the top off-goal tool calls. Backed by the `ci_goal_check` MCP tool (expert mode) and the `goal-monitor` skill.
+
+## How to invoke
+
+```
+ci_goal_check                       # last 30 observations vs task_plan.md
+ci_goal_check limit=50              # widen the observation window
+ci_goal_check goal_file=docs/x.md   # score against a specific plan file
+```
+
+Goal source resolution order: `task_plan.md` in the project root, then `~/.claude/instincts/<project-hash>/goal.md`, then an explicit `goal_file`.
+
+## Output shape
+
+```
+## Goal Check
+
+**Goal source:** /home/me/repo/task_plan.md
+
+**Status:** DRIFT
+**Score:** 12% (1/8 matched, threshold 30%)
+**Reason:** Only 1/8 recent observations relate to the goal (threshold 0.3).
+**Goal keywords:** oauth, jwt, login, session
+
+**Top off-goal activity (most recent 5):**
+- [2026-05-28T12:01:00Z] Edit — src/marketing/landing.ts
+- ...
+
+_Drift detected. Either steer back to the goal, or update the `## Goal` section in your plan if the goal has legitimately changed._
+```
+
+## Acting on the result
+
+- **ON GOAL** — the plan and the work agree; proceed.
+- **DRIFT** — steer back to the goal, or update `## Goal` if it has legitimately changed. Keeping the plan and the work in disagreement is the Law 2 violation this command catches.
+- **NO DATA** — the observation window is still filling; keep working.
+
+## Pairs with
+
+- **`goal-monitor`** skill — the discipline this command runs.
+- **`continuous-improvement`** (core SKILL.md, Law 2 — Plan Is Sacred).
+- **`planning-with-files`** — creates the `task_plan.md` whose `## Goal` section this command reads.

package/commands/grill-me.md

@@ -0,0 +1,40 @@
+---
+name: grill-me
+description: "Interview the user relentlessly about a plan or design until shared understanding is reached. Ported from mattpocock/skills under MIT."
+---
+
+# /grill-me
+
+Stress-test the current plan or design by interviewing the user one question at a time, walking every branch of the decision tree, and recommending an answer for each.
+
+## Trigger phrases
+
+- `/grill-me`
+- "grill me"
+- "stress-test this plan"
+- "interview me about this"
+- "what am I missing?"
+
+## What happens
+
+1. Identify the current plan or design from the conversation — the high-level goal, the assumptions in play, the decisions already made.
+2. Walk the decision tree top-down. For each unresolved branch, ask exactly **one question** with a **recommended answer**.
+3. Before asking, check whether the codebase already answers the question (`grep`, `ls`, file reads). If it does, use that and skip the question.
+4. Resolve dependencies in order — do not ask about deployment before the data model is pinned.
+5. Stop when the plan is shippable cold to a fresh agent. Do not interview past the point of usefulness.
+
+## Five interview rules
+
+1. **One question at a time.** Never multi-question; force depth on every branch.
+2. **Always recommend.** Every question carries "my answer would be X because Y".
+3. **Explore before asking.** Code answers beat user-attention answers.
+4. **Walk the tree, do not jump.** Order matters.
+5. **Stop when shippable.** End state is a plan a fresh agent could execute, not an infinite interview.
+
+## Skill file
+
+Full behavior is defined in [`skills/grill-me.md`](../skills/grill-me.md). The verbatim upstream cold-storage copy lives at [`third-party/mattpocock-skills/skills/productivity/grill-me/SKILL.md`](../third-party/mattpocock-skills/skills/productivity/grill-me/SKILL.md); SHA pin in [`third-party/MANIFEST.md`](../third-party/MANIFEST.md).
+
+## Attribution
+
+Ported from [mattpocock/skills `productivity/grill-me`](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) (MIT, © 2026 Matt Pocock).

package/commands/grill-with-docs.md

@@ -0,0 +1,38 @@
+---
+name: grill-with-docs
+description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates CONTEXT.md + ADRs inline as decisions crystallise. Ported from mattpocock/skills under MIT."
+---
+
+# /grill-with-docs
+
+Stress-test the current plan or design by interviewing the user one question at a time AND updating the project's domain-language doc (`CONTEXT.md`) and architecture decision records (`docs/adr/`) inline as decisions land.
+
+## Trigger phrases
+
+- `/grill-with-docs`
+- "grill me and update the docs"
+- "stress-test this against our domain model"
+- "let's nail down the language and ADR this"
+
+## What happens
+
+1. Read `CONTEXT.md` (or `CONTEXT-MAP.md` + per-context `CONTEXT.md`) and `docs/adr/` if they exist. Use them as the source of truth for project language and prior decisions.
+2. Walk the decision tree top-down. One question at a time with a recommended answer.
+3. Challenge fuzzy terms against the glossary. Sharpen vague language. Stress-test relationships with concrete scenarios. Cross-reference user statements against the code.
+4. When a term is resolved, update `CONTEXT.md` immediately (lazy-create if missing). Use the format in the skill's Appendix A.
+5. Offer an ADR only when all three are true: hard to reverse, surprising without context, result of a real trade-off. Use the format in Appendix B.
+
+## When to fire this instead of `/grill-me`
+
+| Skill | Use when |
+|---|---|
+| `/grill-me` | Conversation-only grilling; no project to update yet, or no docs convention. |
+| `/grill-with-docs` | Project has `CONTEXT.md` or is ready to start one; decisions should persist past the session. |
+
+## Skill file
+
+Full behavior, format specs, and 7 Laws fit are defined in [`skills/grill-with-docs.md`](../skills/grill-with-docs.md). The verbatim upstream cold-storage copies live at [`third-party/mattpocock-skills/skills/engineering/grill-with-docs/`](../third-party/mattpocock-skills/skills/engineering/grill-with-docs/) (`SKILL.md`, `CONTEXT-FORMAT.md`, `ADR-FORMAT.md`); SHA pin in [`third-party/MANIFEST.md`](../third-party/MANIFEST.md).
+
+## Attribution
+
+Ported from [mattpocock/skills `engineering/grill-with-docs`](https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs/SKILL.md) (MIT, © 2026 Matt Pocock). Mattpocock calls this his most powerful skill: "It's hard to explain how powerful this is. It might be the single coolest technique in this repo."