feat(skills): absorb Matt Pocock's skills into pb-spec — grilling loop, two-axis review, diagnostics, domain modeling

Tier 1 — High impact merges:

- pb-brainstorming: absorb grilling loop (model-invoked reusable engine) and
  domain-modeling discipline (CONTEXT.md glossary, inline ADR creation, fuzzy
  language sharpening, cross-reference with code). The grilling loop is now
  the core engine behind brainstorming — one question at a time, recommended
  answers, stress-test with scenarios.

- pb-requesting-code-review: replace single-subagent review with two-axis
  parallel review — Standards (repo standards + 12 Fowler smell baseline) and
  Spec (diff vs originating issue/PRD). Both axes run as parallel subagents
  so they don't pollute each other's context.

- pb-systematic-debugging: absorb diagnosing-bugs — Phase 1 feedback-loop
  construction (10 techniques: failing test, curl, CLI, headless browser,
  replay trace, throwaway harness, property/fuzz loop, bisection, differential,
  HITL script), loop tightening discipline, minimization phase, multi-component
  instrumentation, data flow tracing. Keeps pb-spec's Phase 4 architecture
  questioning for 3+ failures.

Tier 2 — Moderate impact additions:

- pb-plan: add Step 1.6 domain-modeling pre-step (read CONTEXT.md, read ADRs,
  challenge glossary, sharpen terms, update inline, offer ADRs) and deep-module
  vocabulary (module, interface, depth, seam, adapter, leverage, locality,
  deletion test, one-adapter-hypothetical / two-real rule).

- pb-build: add handoff document generation at context-compaction points —
  compact progress into markdown, save to OS temp dir, include suggested skills,
  redact secrets.

- pb-merge-conflicts: new skill — systematic 5-step merge/rebase resolution
  (see state, find primary sources, resolve hunks, run checks, finish merge).

- pb-prototype: new skill — throwaway prototypes with two branches: logic
  (state machine TUI, pure reducer/machine/functions, one command) and UI
  (N radically different variants, ?variant= switcher, floating bottom bar).

- using-pb-spec: update router table with new/changed skills and descriptions.

Source material: mattpocock/skills repo (engineering/ and productivity/ buckets).
Selected skills via impact analysis; skipped to-spec, to-tickets, wayfinder,
triage, teach, research (overlaps with pb-improve or too niche).

Author: Akagi201

skills/pb-brainstorming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pb-brainstorming
-description: You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
+description: You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. Contains the reusable grilling loop and domain-modeling discipline.
 ---
 
 # Brainstorming Ideas Into Designs
@@ -23,7 +23,7 @@ Every project goes through this process. A todo list, a single-function utility,
 
 You MUST complete these items in order:
 
-1. **Explore project context** — check files, docs, recent commits
+1. **Explore project context** — check files, docs, recent commits, and `CONTEXT.md` (if it exists)
 2. **Assess scope complexity** — classify as well-understood (quick plan) or complex (standard flow):
    - **Well-understood:** clear scope, known constraints, few edge cases, single subsystem, straightforward domain → quick plan path
    - **Complex:** ambiguous requirements, multi-system interactions, complex domain logic, unclear boundaries → standard flow
@@ -34,11 +34,39 @@ You MUST complete these items in order:
 6. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope
 7. **Transition to implementation** — invoke `pb-plan` to create implementation plan
 
+## The Grilling Loop (Core Engine)
+
+The grilling loop is the reusable engine behind brainstorming. Interview the user relentlessly about every aspect of the plan until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+### Grilling Rules
+
+1. **One question at a time.** Asking multiple questions at once is bewildering. Wait for feedback on each question before continuing.
+2. **Recommended answers.** For each question, provide your recommended answer with reasoning. Don't just ask — guide.
+3. **Look up facts, ask about decisions.** If a *fact* can be found by exploring the codebase, look it up rather than asking. The *decisions*, though, belong to the user — put each one to them and wait.
+4. **Don't enact until confirmed.** Do not proceed to implementation until the user confirms shared understanding.
+5. **Stress-test with scenarios.** When domain relationships are being discussed, invent concrete scenarios that probe edge cases and force precision about boundaries between concepts.
+
+### Grilling Flow
+
+```
+User message received
+  → Understand the idea (explore codebase, check CONTEXT.md)
+  → Assess scope complexity
+  → Grilling loop:
+      → Ask one question (with recommended answer)
+      → Wait for response
+      → Update understanding
+      → Repeat until all branches resolved
+  → Present design
+  → Get approval
+  → Transition to pb-plan
+```
+
 ## The Process
 
 **Understanding the idea:**
 
-- Check out the current project state first (files, docs, recent commits)
+- Check out the current project state first (files, docs, recent commits, `CONTEXT.md`)
 - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
 - If the project is too large for a single spec, help the user decompose into sub-projects. Each sub-project gets its own spec → plan → implementation cycle.
 - For appropriately-scoped projects, ask questions one at a time to refine the idea
@@ -77,6 +105,71 @@ You MUST complete these items in order:
 - Where existing code has problems that affect the work, include targeted improvements as part of the design.
 - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
 
+## Domain Modeling (Inline Discipline)
+
+During brainstorming, actively build and sharpen the project's domain model. This is not a separate phase — it happens inline as decisions crystallize.
+
+### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen.
+
+`CONTEXT.md` format:
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+```
+
+Rules:
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts don't belong.
+- Create `CONTEXT.md` lazily — only when the first term is resolved.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR.
+
+ADR format — lives in `docs/adr/`, sequential numbering (`0001-slug.md`):
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
 ## Quick Plan Flow
 
 When scope assessment classifies a feature as well-understood, use this fast-track path instead of the standard multi-step flow. Quick plan generates all artifacts in one pass with minimal questions.
@@ -180,9 +273,11 @@ Please review each section. I'll proceed to the next after your approval.
 - **Incremental validation** - Present design, get approval before moving on
 - **Speed where it helps, depth where it matters** - Quick plan for well-understood scope, full process for complex features
 - **Be flexible** - Go back and clarify when something doesn't make sense
+- **Domain model stays current** — Update CONTEXT.md and ADRs inline as decisions land
 
 ## Integration with pb-spec
 
 - **Pre-pb-plan:** Use this skill before `/pb-plan` to ensure requirements are clear
 - **Pre-pb-build:** Use when requirements are ambiguous and need clarification
 - **Standalone:** Use for any design brainstorming need
+- **Model-invoked:** Other skills can invoke the grilling loop when they need to walk a decision tree with the user

skills/pb-build/SKILL.md

@@ -428,6 +428,38 @@ After updating `tasks.md`, **verify the mark actually took effect** before proce
 3. **If verification fails** — apply the mark immediately and re-verify.
 
 > **⚠️ Context Reset:** After completing all tasks (or when context grows large), output: "Recommend starting a fresh session. Run `/pb-build <feature-name>` again to continue from where you left off." The progress ledger ensures no completed work is lost.
+>
+> **Handoff Document:** When recommending a fresh session, generate a handoff document summarizing the current state so the next agent can continue without re-reading the entire conversation. Save to the OS temp directory (`$TMPDIR` or `/tmp`):
+>
+> ```markdown
+> # Handoff: <feature-name>
+>
+> ## What's done
+>
+> - Task X.Y: [name] — DONE (commits abc1234..def5678)
+> - Task X.Z: [name] — DONE (commits ...)
+>
+> ## What's next
+>
+> - Task A.B: [name] — TODO (next in queue)
+> - Dependencies: [what it depends on]
+>
+> ## Key context
+>
+> - Spec dir: specs/<spec-dir>/
+> - Design decisions: [1-2 bullets of non-obvious choices]
+> - Watch out for: [any gotchas discovered during build]
+>
+> ## Suggested skills
+>
+> - `/pb-build <feature-name>` — to continue from where we left off
+> - `/pb-systematic-debugging` — if tasks fail repeatedly
+>
+> ## Progress ledger
+> See specs/<spec-dir>/progress.md for full task-by-task record.
+> ```
+>
+> Redact any secrets or API keys from the handoff document.
 
 ### Step 4: Handle Failures (The Recovery Loop with Escalation)
 

skills/pb-merge-conflicts/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: pb-merge-conflicts
+description: Use when you need to resolve an in-progress git merge/rebase conflict. Guides systematic resolution preserving both intents where possible.
+---
+
+# pb-merge-conflicts
+
+Resolve merge/rebase conflicts systematically. Always resolve; never `--abort`.
+
+## Process
+
+### 1. See the current state
+
+Check git history, and the conflicting files:
+
+```bash
+git status
+git log --oneline -5
+```
+
+Identify whether this is a merge or a rebase, and which files have conflicts.
+
+### 2. Find the primary sources for each conflict
+
+For each conflicting file, understand deeply why each change was made:
+
+- Read the commit messages from both sides
+- Check PRs or issue references if available
+- Understand the original intent behind each change
+
+### 3. Resolve each hunk
+
+For each conflict marker (`<<<<<<<`, `=======`, `>>>>>>>`):
+
+- Preserve both intents where possible
+- Where incompatible, pick the one matching the merge's stated goal and note the trade-off
+- Do **not** invent new behaviour
+- Always resolve; never `--abort`
+
+### 4. Run automated checks
+
+Discover the project's automated checks and run them — typically typecheck, then tests, then format:
+
+```bash
+uv run ruff check
+uv run ty check
+uv run pytest
+```
+
+Fix anything the merge broke.
+
+### 5. Finish the merge/rebase
+
+Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased:
+
+```bash
+git add -A
+git commit  # or git rebase --continue
+```
+
+## Red Flags
+
+- `git merge --abort` or `git rebase --abort` without trying to resolve
+- Picking one side without understanding the other's intent
+- Skipping automated checks after resolving
+- Inventing new behavior that neither side intended
+
+## Integration with pb-spec
+
+- **During pb-build:** If a task causes merge conflicts with concurrent work, use this skill
+- **Standalone:** Use for any merge/rebase conflict

skills/pb-plan/SKILL.md

@@ -166,6 +166,31 @@ When abductive refinement reveals missing error paths or prerequisites, add them
 
 Non-compliant requirements are rewritten inline in the ledger before proceeding to design. The clarification log records every rewrite with its reason.
 
+### Step 1.6: Domain Modeling Pre-Step
+
+Before collecting project context, check and update the project's domain model. This grounds all subsequent planning in precise vocabulary.
+
+1. **Read `CONTEXT.md`** (if it exists at project root) — capture the project's canonical domain terms and their definitions. Use this vocabulary throughout the spec.
+2. **Read ADRs in `docs/adr/`** (if they exist) — capture existing architectural decisions. Do not re-litigate decided items.
+3. **Challenge against the glossary.** As requirements are parsed, check whether the user's terms conflict with `CONTEXT.md`. If "cancellation" means something different in the requirement vs the glossary, flag it.
+4. **Sharpen fuzzy language.** When requirements use vague or overloaded terms, propose precise canonical terms. "You're saying 'account' — do you mean the Customer or the User?"
+5. **Update `CONTEXT.md` inline.** When a new term is resolved during planning, add it to `CONTEXT.md` right there. Don't batch. Create `CONTEXT.md` lazily if it doesn't exist.
+6. **Offer ADRs for hard decisions.** When a planning decision is (a) hard to reverse, (b) surprising without context, and (c) the result of a real trade-off, create an ADR in `docs/adr/` with sequential numbering. Otherwise skip.
+
+**CONTEXT.md format:**
+
+```md
+# {Context Name}
+
+{One or two sentence description.}
+
+## Language
+
+**Term**:
+{Definition — one or two sentences. What it IS, not what it does.}
+_Avoid_: synonym1, synonym2
+```
+
 ### Step 2: Collect Project Context
 
 Gather context to inform the design. **Always perform live codebase analysis** — do not rely on any static file.
@@ -211,6 +236,16 @@ Subagent rules:
    - Reuse existing repo decisions when available; add new decisions only when the requirement creates a genuine gap.
    - **Apply the ponytail ladder** when evaluating patterns: prefer stdlib/native solutions over custom implementations. An interface with one implementation is a factory for one product — skip it. A config for a value that never changes is a constant — hardcode it.
    - **Performance impact assessment:** For any architectural decision that touches data access, API boundaries, or hot paths, briefly note the expected performance characteristic (e.g., "O(n) queries acceptable for n<100" or "requires lazy loading to avoid N+1"). Do not write full performance specs — just flag the obvious wins and risks.
+   - **Deep-module vocabulary** (use these terms in architecture sections):
+     - **Module** — anything with an interface and an implementation (function, class, package). Avoid: component, service.
+     - **Interface** — everything a caller must know: type signature, invariants, ordering, error modes, config, perf characteristics. Avoid: API (too narrow).
+     - **Depth** — leverage at the interface: lots of behavior behind a small interface = deep; interface nearly as complex as implementation = shallow.
+     - **Seam** — where you can alter behavior without editing in that place. Avoid: boundary (overloaded).
+     - **Adapter** — a concrete thing that satisfies an interface at a seam.
+     - **Leverage** — what callers get from depth: more capability per unit of interface learned.
+     - **Locality** — what maintainers get from depth: change, bugs, and verification concentrate in one place.
+   - **The deletion test:** When evaluating whether a module earns its place, imagine deleting it. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+   - **One adapter = hypothetical seam. Two = real.** Don't introduce a seam unless something actually varies across it.
 
 7. **Audit coding standards and simplification boundaries** — determine which style and maintainability rules the eventual implementation must follow:
    - Infer language- and framework-specific standards from `AGENTS.md`, `CLAUDE.md`, and the live codebase. Only apply standards that are relevant to the current repo; do not copy unrelated JavaScript or React rules into Python work.