@eltonssouza/development-utility-kit 0.16.0 → 0.18.0

package/.claude/CONTEXT.template.md

@@ -0,0 +1,44 @@
+# CONTEXT — project domain glossary
+
+> Per-repo **ubiquitous-language** glossary (ADR-050). Agents read this before
+> exploring code and use its exact vocabulary in plans, issues, code, and tests.
+> Together with the stack pack it forms the project's working context.
+> Copy this template to the project root as `CONTEXT.md` and fill it in
+> (`stack-discovery` / `create-stack-pack` can seed it for you).
+
+## Domain in one paragraph
+
+<What this project is, who uses it, and the core value — 2–4 sentences in the
+team's own words.>
+
+## Ubiquitous language (the glossary)
+
+Use these terms verbatim — never invent synonyms. One row per concept.
+
+| Term | Means | NOT to be confused with |
+|---|---|---|
+| `<Order>` | <a customer's confirmed purchase, after payment> | `Cart` (pre-payment) |
+| `<...>` | <...> | <...> |
+
+## Bounded contexts (if multi-context)
+
+- `<context-name>` — <responsibility>; owns `<entities>`.
+- (Single-context project: write "single context".)
+
+## Core invariants
+
+Business rules that must always hold (named, so plans/tests reference them).
+
+- `INV-1`: <e.g. an Order always has at least one line item>
+- `INV-2`: <...>
+
+## Naming conventions
+
+- Entities/tables: <e.g. singular PascalCase entities, snake_case tables>
+- Endpoints: <e.g. `/api/v1/<plural-resource>`>
+- Events/statuses: <the allowed status strings, exactly>
+
+## Pointers
+
+- ADRs that touch the domain: `docs/brain/decisions/` (or `docs/adr/`)
+- Stack pack: resolved from `## Project Identity` via `stack-resolver`

package/.claude/agents/analyst.md

@@ -31,17 +31,25 @@ Do NOT generate the PLAN from a free description in the human path.
 
 Receive an ambiguous feature/bug/task description and distill it into a complete plan with requirements, BDD user stories, sprint ordering, and **DoD criteria written so that each task or sprint can be handed to `/goal <condition>` in Claude Code and run autonomously until the condition is met**.
 
+## Synthesis principles (ADR-050)
+
+Three patterns shape every plan you write — they are *our* implementations of ideas learned from the community, not optional flavour:
+
+- **Domain glossary first (`CONTEXT.md`).** If the project has a `CONTEXT.md` (per-repo ubiquitous-language glossary), read it before anything and use its exact vocabulary throughout the plan — entities, actions, statuses. The glossary + the stack pack together are the project's working context. If absent, propose seeding one in §7 (Decisões pendentes).
+- **Tracer-bullet vertical slices.** Decompose sprints/tasks by **end-to-end vertical slices** that cut through every layer (DB → service → API → UI) and ship something demonstrable — NOT horizontal layers ("all backend, then all frontend"). Each slice is independently shippable and gated.
+- **Deep modules (Ousterhout).** In modeling, prefer **deep modules**: a simple, stable, testable interface hiding substantial functionality. Flag **shallow modules** (interface as wide as the implementation, pass-through) as a smell to consolidate.
+
 ## Flow
 
-1. **Understanding**: objective, personas, flows, criteria, copywriting, constraints. Inspect existing code.
+1. **Understanding**: read `CONTEXT.md` (domain glossary) if present and adopt its vocabulary; then objective, personas, flows, criteria, copywriting, constraints. Inspect existing code.
 2. **Requirements**:
    - **FR** (functional) — what the system does.
    - **NFR** (non-functional) — performance, security, UX.
    - **BR** (business rules) — validations, policies.
    - **IR** (implicit) — permissions, audit, pagination, loading, responsiveness, empty states.
-3. **Modeling**: entities + attributes, relationships, detailed flows, technical mapping (endpoints, components, migrations).
+3. **Modeling**: entities + attributes, relationships, detailed flows, technical mapping (endpoints, components, migrations). **Sketch the modules** you will build/modify and mark each **deep** (simple interface, encapsulated complexity — preferred) or **shallow** (pass-through — consolidate). Use the `CONTEXT.md` vocabulary for module + entity names.
 4. **BDD User Stories**: Given/When/Then for happy path AND edge cases. Priority (S/M/L) and estimate.
-5. **Sprints**: tasks ordered with dependencies.
+5. **Sprints**: tasks ordered with dependencies, decomposed as **tracer-bullet vertical slices** — each task/slice cuts end-to-end (DB → service → API → UI as applicable) and is independently demonstrable + gated, never a horizontal layer.
 6. **Risks and pending items**: ambiguities (mark as "ask the client"), `tech-lead` decisions.
 7. **Goal-ready DoD**: for every task and every sprint, write a Definition of Done that a `/goal` evaluator (Haiku by default) can verify objectively from command output or file inspection. See §"Goal-ready output rules" below.
 8. **Generate**: `docs/plans/PLAN_<NAME>.md` following the canonical structure (§"Plan structure").
@@ -100,11 +108,12 @@ The generated `docs/plans/PLAN_<NAME>.md` must have these sections in this order
 
 ## 5. Sprints
 ### Sprint 1 — <tema>
-- Tasks (em ordem de dependência):
-  1. T-001 <descrição>
-     - Cobre US-001, US-002
+- Tasks = tracer-bullet vertical slices (cada uma corta DB→service→API→UI e é demonstrável):
+  1. T-001 <slice end-to-end, ex: "criar produto: migration + endpoint POST + tela mínima de cadastro">
+     - Cobre US-001 (happy path da fatia)
+     - Módulos: <deep: X | shallow a consolidar: Y>
      - DoD: <condição machine-checkable>
-  2. T-002 ...
+  2. T-002 <próxima fatia vertical, ex: "listar produtos: query + GET + tela de listagem">
 
 ### Sprint 2 — ...
 
@@ -165,6 +174,9 @@ retornou GO.
 6. **§8 `/goal` block ends the file.** Always present, never empty. If the plan has a single sprint, you still emit one sprint-level `/goal` plus one final goal.
 7. **No AI/Claude/Anthropic/LLM references in the plan prose.** The PLAN must read as written by the engineering team. Same restriction as commits.
 8. **Filename**: `docs/plans/PLAN_<NAME_KEBAB_CASE>.md`. No spaces, no accents in filename — slug derived from the feature name.
+9. **Tracer-bullet decomposition (ADR-050).** Sprints/tasks are vertical end-to-end slices, never horizontal layers. A task that touches only one layer must be justified (e.g. a pure migration) or merged into a slice.
+10. **Deep modules (ADR-050).** §3 marks each module deep/shallow; shallow modules are flagged for consolidation, not shipped silently.
+11. **Domain glossary (ADR-050).** If `CONTEXT.md` exists, the plan uses its vocabulary verbatim; if absent, §7 proposes seeding it.
 
 ## Interface
 

package/.claude/agents/code-reviewer.md

@@ -77,6 +77,11 @@ For any check above, the **STACK CONTEXT pack overrides** when more specific (e.
 
 ## 4. Cross-cutting checks (universal)
 
+### Design — deep modules (ADR-050)
+- Prefer **deep modules**: simple, stable interface hiding substantial functionality.
+- Flag **shallow modules** as MINOR/MAJOR: interface as wide/complex as the implementation, pure pass-through wrappers, or a class that just forwards to another. Recommend consolidation.
+- New names match the project's `CONTEXT.md` glossary (if present) — flag vocabulary drift as MINOR.
+
 ### Security (delegate hard cases to `security-engineer`)
 - Token / password / PII not logged.
 - CORS not `permitAll` in production.

package/.claude/agents/stack-resolver.md

@@ -24,15 +24,16 @@ Read project's CLAUDE.md, parse `## Project Identity`, identify Primary stack, l
 6. **Read the pack**:
    - If pack exists -> Read it -> return rendered STACK CONTEXT block (see §Output below).
    - If pack absent -> **hard-fail** with `PACK_MISSING_ERROR` (see §Hard-fail protocol below). Do NOT silently fall through to defaults. Do NOT invent a pack.
-7. **Always emit first-line tag** for validation by invoking skill:
-   `[STACK: <lang>/<framework>-<major> | PACK: loaded|none]`
+7. **Read the domain glossary (ADR-050)**: check the project root for `CONTEXT.md` (per-repo ubiquitous-language glossary). If present, read it and append a `DOMAIN GLOSSARY` section to the output so downstream agents use the project's exact vocabulary. If absent, note `Domain glossary: none (suggest seeding CONTEXT.md)` — non-fatal.
+8. **Always emit first-line tag** for validation by invoking skill:
+   `[STACK: <lang>/<framework>-<major> | PACK: loaded|none | GLOSSARY: present|none]`
 
 ## Output format
 
 When pack loaded:
 
 ```
-[STACK: java/spring-boot-3 | PACK: loaded]
+[STACK: java/spring-boot-3 | PACK: loaded | GLOSSARY: present]
 
 === STACK CONTEXT ===
 Language: java
@@ -43,6 +44,9 @@ Pack path: .claude/stacks/java/spring-boot-3.md
 
 === STACK RULES (inline — do not Read again) ===
 <full pack content, including frontmatter, all 10 sections>
+
+=== DOMAIN GLOSSARY (CONTEXT.md — use this vocabulary) ===
+<full CONTEXT.md content if present, else: "none — suggest seeding CONTEXT.md">
 === END STACK CONTEXT ===
 ```
 
@@ -91,6 +95,7 @@ When the pack is absent, before emitting `PACK_MISSING_ERROR`:
 5. **No agent dispatch** — this agent is a leaf; invokers (skills) dispatch others based on the resolver's output.
 6. **Hard-fail on missing pack** — no silent fallback. `PACK_MISSING_ERROR` is mandatory. Invokers must stop or present bypass confirmation. This is non-negotiable (ADR-026 T1.2).
 7. **Always suggest nearest packs** — a resolver that returns only "not found" without suggestions violates this contract.
+8. **Domain glossary is non-fatal (ADR-050)** — read project `CONTEXT.md` if present and append it; if absent, note it and proceed. Never hard-fail on a missing glossary (unlike a missing pack).
 
 ## Interface
 

package/.claude/hooks/flow-state.js

@@ -129,6 +129,36 @@ function deriveState(projectRoot) {
     // docs/plans/ does not exist — no plan artifacts
   }
 
+  // Local-files issue layer (ADR-050): .scratch/<feature>/ is an OPTIONAL,
+  // governed alternative to docs/ artifacts. A PRD.md counts as discovery; an
+  // issues/ dir with at least one issue counts as a plan. So governance still
+  // holds for projects that use the issue-style local files instead of docs/.
+  try {
+    const scratch = path.join(root, '.scratch');
+    for (const feat of fs.readdirSync(scratch)) {
+      const featDir = path.join(scratch, feat);
+      let isDir = false;
+      try { isDir = fs.statSync(featDir).isDirectory(); } catch { /* skip */ }
+      if (!isDir) continue;
+      if (!discoveryArtifact && fs.existsSync(path.join(featDir, 'PRD.md'))) {
+        discoveryArtifact = path.join(featDir, 'PRD.md');
+        if (!activeFeature) activeFeature = feat;
+      }
+      if (!planArtifact) {
+        const issuesDir = path.join(featDir, 'issues');
+        try {
+          const issues = fs.readdirSync(issuesDir).filter((f) => f.endsWith('.md'));
+          if (issues.length > 0) {
+            planArtifact = path.join(issuesDir, issues.sort()[0]);
+            if (!activeFeature) activeFeature = feat;
+          }
+        } catch { /* no issues/ dir */ }
+      }
+    }
+  } catch {
+    // .scratch/ does not exist — no local-files issue artifacts
+  }
+
   // Determine stage
   let stage = 'none';
   if (planArtifact) {

package/.claude/skills/stack-discovery/SKILL.md

@@ -108,6 +108,13 @@ Use `Edit` para substituir SOMENTE a seção `## Project Identity` em `CLAUDE.md
    > "Pack `.claude/stacks/java/spring-boot-5.md` não existe. Disparando `create-stack-pack` para gerar antes de continuar."
    Depois que `create-stack-pack` retorna, feche com o output normal.
 
+### Step 7 — Seed CONTEXT.md (domain glossary — ADR-050)
+
+Se o projeto **não** tem `CONTEXT.md` no root, ofereça semear a partir do template:
+> "Quer que eu crie um `CONTEXT.md` (glossário de domínio) a partir do template? Os agents usam o vocabulário dele em planos/issues/código."
+
+Se **sim**: copie `.claude/CONTEXT.template.md` para `CONTEXT.md` no root e pré-preencha o que já souber da sabatina (domínio em 1 parágrafo + 2-3 termos do glossário). Deixe o resto como placeholder pro user completar. Não bloqueia o fim da skill (opcional).
+
 ## 5. Inviolable rules
 
 1. **Sabatina conversacional, opt-in.** Nunca rode em CI, `sprint-runner`, ou qualquer fluxo autônomo.

package/.claude/skills/to-issues/SKILL.md

@@ -54,13 +54,17 @@ Read the full `PRD_*.md`. Extract from each section:
 
 If `docs/issues/` does not exist, create it. Use `Write` to create `docs/issues/.gitkeep` if needed, then proceed to write the ISSUES file.
 
-### Step 4 — Decompose into issues
+### Step 4 — Decompose into issues (tracer-bullet vertical slices — ADR-050)
 
-Apply the following decomposition rules:
-- One issue per User Story (from the PRD `## User Stories` section).
-- Additional issues for cross-cutting NFRs (security hardening, a11y audit, performance baseline) when they represent distinct, shippable work items.
-- Do NOT create an issue for items listed in `## Out of scope`.
-- Issue granularity: each issue must be completable in one sprint by one developer. Split large stories.
+Decompose by **tracer-bullet vertical slices**, not horizontal layers. Each issue cuts **end-to-end** through every layer it needs (DB → service → API → UI) and ships something demonstrable on its own — never "backend of feature X" + "frontend of feature X" as separate issues.
+
+Rules:
+- **One issue per vertical slice.** A User Story is usually one slice; if a story spans layers, the issue still owns the whole slice end-to-end.
+- **First slice = the thinnest end-to-end path** that proves the architecture (the literal "tracer bullet"). Order issues so the thinnest walking-skeleton slice ships first.
+- Additional issues for cross-cutting NFRs (security hardening, a11y audit, performance baseline) when they are distinct, shippable items.
+- Do NOT create an issue for items in `## Out of scope`.
+- Granularity: each slice completable in one sprint by one developer. Split large stories **by slice** (e.g. "create + read" then "update + delete"), never by layer.
+- Use the project's `CONTEXT.md` glossary vocabulary in titles/bodies if present.
 
 ### Step 5 — Write ISSUES_*.md
 

package/CLAUDE.md

@@ -250,8 +250,21 @@ These thresholds are **universal across stacks**. Stack-specific tooling (JaCoCo
 
 - **Clean Code + SOLID** applied through code, without naming names ostentatiously.
 - **No premature abstraction**. Interface for one implementation = code smell.
+- **Prefer deep modules** (Ousterhout, ADR-050): a **simple, stable interface hiding substantial functionality**. A **shallow module** — interface as wide/complex as its implementation, or a pure pass-through — is a smell; consolidate it. `analyst` marks modules deep/shallow in the plan; `code-reviewer`/`tech-lead` flag shallow ones in review.
 - **Never suggest a technology without justification**. Simplest solution = best.
 
+## Project domain glossary — `CONTEXT.md` (ADR-050)
+
+A project MAY ship a root `CONTEXT.md` (per-repo ubiquitous-language glossary — terms, bounded contexts, invariants, naming). When present, **agents read it before exploring code and use its vocabulary verbatim** in plans, issues, code, and tests. `stack-resolver` surfaces it alongside the stack pack (`DOMAIN GLOSSARY` block); together they are the project's working context. Seed one from `.claude/CONTEXT.template.md` (`stack-discovery` offers this). Absent glossary is non-fatal.
+
+## Decomposition — tracer-bullet vertical slices (ADR-050)
+
+Features are decomposed into **end-to-end vertical slices** (DB → service → API → UI) that each ship something demonstrable — never horizontal layers ("all backend, then all frontend"). The thinnest end-to-end slice ships first (the walking skeleton). `analyst` and `to-issues` own this; `sprint-runner` executes slice by slice.
+
+## Optional local-files issue layer — `.scratch/` (ADR-050)
+
+Projects may use an **issue-style local-files layer** instead of (or alongside) the `docs/discovery|prd|plans/` artifacts: one dir per feature at `.scratch/<feature-slug>/` with `PRD.md` and `issues/NN-<slug>.md` (each issue carries a `Status:` line). This is **governed** — `flow-guard` recognizes `.scratch/<feature>/PRD.md` as a discovery artifact and `.scratch/<feature>/issues/*.md` as a plan artifact, so the same prerequisite gating applies. It is an option, not a replacement; the `docs/` file pipeline remains the default.
+
 ## Backend layout (DDD, universal pattern)
 
 The package/folder names below are **conceptual** — actual naming may vary by language (`com.company.project/domain/...` in Java, `app/domain/...` in Python, `internal/domain/...` in Go):

package/README.repo.md

@@ -404,7 +404,7 @@ Full vault under [`docs/brain/`](docs/brain/) — browse via Obsidian. Live ADR
 
 Honest thanks to:
 
-- **[`mattpocock/skills`](https://github.com/mattpocock/skills)** — by **[Matt Pocock](https://github.com/mattpocock)** ([aihero.dev](https://www.aihero.dev/my-grill-me-skill-has-gone-viral)). The relentless `grill-me` discovery interview is Matt's design. As of **v0.16.0** the harness is **adopting Matt's full issue-tracker engineering workflow** (ADR-049, MIT): we **vendor** his skills — `diagnose`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `setup-matt-pocock-skills`, `tdd`, `triage`, `zoom-out` (and, in a later sprint, `to-prd`/`to-issues`) — under `.claude/skills/` with his `LICENSE` + a `NOTICE` (see `.claude/skills/_vendor/`). They are bundled, not re-authored; upstream is the source of truth. The staged migration is in `docs/plans/PLAN_mattpocock-workflow-adoption.md`.
+- **[`mattpocock/skills`](https://github.com/mattpocock/skills)** — by **[Matt Pocock](https://github.com/mattpocock)** ([aihero.dev](https://www.aihero.dev/my-grill-me-skill-has-gone-viral)). The relentless `grill-me` discovery interview is Matt's design, and several of his ideas inform our own pipeline — **tracer-bullet vertical-slice issues**, a **`CONTEXT.md` domain glossary**, the **deep-modules** heuristic, and a **local-files issue model**. We evaluated adopting his issue-tracker workflow wholesale (ADR-049) and decided instead to **build our own superior synthesis** (ADR-050): keep our role-agent team, Senior+ gate, stack-awareness and deterministic flow governance — where his skills-only model falls short — while learning from the patterns above. We do **not** vendor his skills; we credit the ideas and reimplement them better-integrated.
 - **[`caveman`](https://github.com/JuliusBrussee/caveman)** — by **[Julius Brussee](https://github.com/JuliusBrussee)**. The telegraphic communication mode that saves us 65–75% of output tokens with zero technical loss. We use it as the default style in this harness; the compression rules, the levels (lite/full/ultra), and the auto-clarity carve-outs are Julius's work.
 - **[`impeccable`](https://github.com/pbakaus/impeccable)** — by **[Paul Bakaus](https://github.com/pbakaus)**. The design-refinement skill (`polish | harden | audit`) that drives our visual-quality gate. Paul's `npx skills add pbakaus/impeccable` distribution pattern also directly inspired our own `npx @eltonssouza/development-utility-kit install` installer (ADR-018).
 - **[`rtk`](https://github.com/rtk-ai/rtk)** — by the **[rtk-ai](https://github.com/rtk-ai) team**. The Rust Token Killer CLI proxy that powers the live "RTK savings" widget on the `duk dashboard` (`rtk gain --format json` → `/api/rtk`). The 60–90% savings on dev operations we surface in the dashboard are RTK's, not ours.

package/bin/lib/lint.js

@@ -174,23 +174,9 @@ function findStackPacks() {
 // ── Category 1: skills.frontmatter ──────────────────────────────────────────
 
 const SKILL_REQUIRED_FIELDS = ['name', 'description', 'tools', 'model'];
-// Vendored third-party skills are valid Claude Code skills as-authored upstream;
-// `tools`/`model` are a harness-internal convention, not a Claude Code requirement.
-const VENDORED_REQUIRED_FIELDS = ['name', 'description'];
-
-function loadVendoredSkillNames() {
-  try {
-    const p = path.join(packageRoot(), '.claude', 'skills', '_vendor', 'vendored.json');
-    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
-    return new Set(Array.isArray(data.skills) ? data.skills : []);
-  } catch {
-    return new Set();
-  }
-}
 
 function checkSkillsFrontmatter() {
   const violations = [];
-  const vendored = loadVendoredSkillNames();
   for (const skill of findSkills()) {
     const content = readSafe(skill.path);
     if (content === null) {
@@ -198,8 +184,7 @@ function checkSkillsFrontmatter() {
       continue;
     }
     const { frontmatter } = extractFrontmatter(content);
-    const required = vendored.has(skill.name) ? VENDORED_REQUIRED_FIELDS : SKILL_REQUIRED_FIELDS;
-    for (const f of required) {
+    for (const f of SKILL_REQUIRED_FIELDS) {
       if (!frontmatter[f]) {
         violations.push({
           category: 'skills', severity: ERROR, file: skill.path, line: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eltonssouza/development-utility-kit",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "npx installer for the development-utility-kit harness",
   "bin": {
     "duk": "bin/cli.js"

package/.claude/skills/_vendor/NOTICE.md

@@ -1,11 +0,0 @@
-# Vendored skills — attribution
-
-The following skills are vendored from **[mattpocock/skills](https://github.com/mattpocock/skills)**
-by **Matt Pocock**, under the **MIT License** (see `mattpocock-LICENSE`):
-
-- `diagnose`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`,
-  `setup-matt-pocock-skills`, `tdd`, `triage`, `zoom-out`
-- (Sprint 4: `to-prd`, `to-issues`)
-
-They are bundled — not re-authored. Upstream is the source of truth; we re-sync
-on update. See `docs/plans/PLAN_mattpocock-workflow-adoption.md` (ADR-049).

package/.claude/skills/_vendor/mattpocock-LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/.claude/skills/_vendor/vendored.json

@@ -1,15 +0,0 @@
-{
-  "_comment": "Skills vendored from third parties (MIT). Exempt from the harness tools/model frontmatter convention — they are valid Claude Code skills as-authored upstream. See _vendor/NOTICE.md.",
-  "source": "mattpocock/skills",
-  "license": "MIT",
-  "skills": [
-    "diagnose",
-    "grill-with-docs",
-    "improve-codebase-architecture",
-    "prototype",
-    "setup-matt-pocock-skills",
-    "tdd",
-    "triage",
-    "zoom-out"
-  ]
-}

package/.claude/skills/diagnose/SKILL.md

@@ -1,117 +0,0 @@
----
-name: diagnose
-description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
----
-
-# Diagnose
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
-
-## Phase 1 — Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
-
-### Ways to construct one — try them in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-Do not proceed to Phase 2 until you have a loop you believe in.
-
-## Phase 2 — Reproduce
-
-Run the loop. Watch the bug appear.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-Do not proceed until you reproduce the bug.
-
-## Phase 3 — Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before the fix** — but only if there is a **correct seam** for it.
-
-A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
-
-**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
-## Phase 6 — Cleanup + post-mortem
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/.claude/skills/diagnose/scripts/hitl-loop.template.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [Enter when done] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- edit below ---------------------------------------------------------
-
-step "Open the app at http://localhost:3000 and sign in."
-
-capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
-
-capture ERROR_MSG "Paste the error message (or 'none'):"
-
-# --- edit above ---------------------------------------------------------
-
-printf '\n--- Captured ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/.claude/skills/grill-with-docs/ADR-FORMAT.md

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

package/.claude/skills/grill-with-docs/CONTEXT-FORMAT.md

@@ -1,60 +0,0 @@
-# CONTEXT.md Format
-
-## Structure
-
-```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
-
-**Customer**:
-A person or organization that places orders.
-_Avoid_: Client, buyer, account
-```
-
-## 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 (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
-- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
-
-## Single vs multi-context repos
-
-**Single context (most repos):** One `CONTEXT.md` at the repo root.
-
-**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
-
-```md
-# Context Map
-
-## Contexts
-
-- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
-- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
-- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
-
-## Relationships
-
-- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
-- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
-- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
-```
-
-The skill infers which structure applies:
-
-- If `CONTEXT-MAP.md` exists, read it to find contexts
-- If only a root `CONTEXT.md` exists, single context
-- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
-
-When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.