@heihei0299/matt-skills 2.1.13 → 3.0.1

package/template/.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh

@@ -1,44 +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.
-#
-# `capture` prints its value back to the terminal, where the agent reads it,
-# so capture observations, and leave signing in to the user as a `step`.
-
-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/template/.agents/skills/domain-modeling/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/template/.agents/skills/domain-modeling/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.

package/template/.agents/skills/domain-modeling/SKILL.md

@@ -1,74 +0,0 @@
----
-name: domain-modeling
-description: Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a CONTEXT.md, or recording or editing an ADR.
----
-
-# Domain Modeling
-
-Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)
-
-## File structure
-
-Most repos have a single context:
-
-```
-/
-├── CONTEXT.md
-├── docs/
-│   └── adr/
-│       ├── 0001-event-sourced-orders.md
-│       └── 0002-postgres-for-write-model.md
-└── src/
-```
-
-If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
-
-```
-/
-├── CONTEXT-MAP.md
-├── docs/
-│   └── adr/                          ← system-wide decisions
-├── src/
-│   ├── ordering/
-│   │   ├── CONTEXT.md
-│   │   └── docs/adr/                 ← context-specific decisions
-│   └── billing/
-│       ├── CONTEXT.md
-│       └── docs/adr/
-```
-
-Create files lazily: only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
-
-## During the session
-
-### 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."
-
-### Discuss concrete scenarios
-
-When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
-
-### 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. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
-
-`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
-
-### 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. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).

package/template/.agents/skills/domain-modeling/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Domain Modeling"
-  short_description: "Build and sharpen a domain model"

package/template/.agents/skills/grill-me/SKILL.md

@@ -1,7 +0,0 @@
----
-name: grill-me
-description: A relentless interview to sharpen a plan or design.
-disable-model-invocation: true
----
-
-Call the Skill tool with "grilling".

package/template/.agents/skills/grill-me/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Grill Me"
-  short_description: "Sharpen a plan through interview"
-policy:
-  allow_implicit_invocation: false

package/template/.agents/skills/grill-to-spec/SKILL.md

@@ -1,55 +0,0 @@
----
-name: grill-to-spec
-description: "Router：编排 grill-with-docs → to-spec，把模糊想法打磨成可执行 Spec。Use when the user asks to grill/design/polish an idea into a spec——只产出领域文档与 spec，不写代码。"
-disable-model-invocation: true
----
-
-# Grill to Spec
-
-只做两个上游 skill 的编排：先把想法打磨成共识，再把共识发布成 spec。本 skill 不写代码、不修改源码或测试、不自动 commit。
-
-## 流程
-
-### 0. 预检
-
-- 只读确认 issue tracker、目标上下文、feature slug 和已有 spec/issue 状态。
-- tracker 未配置、slug 不明确或目标路径不可写时，在任何 ADR/spec/issue 写入前报告阻塞。
-- 已有同一 feature 的产物先读取并比较；相同共识不重复发布，设计变化进入变更流程。
-
-### ① 形成共识
-
-调用 [`grill-with-docs`](.agents/skills/grill-with-docs/SKILL.md)，由 `grilling` 与 `domain-modeling` 完成采访、术语和设计决策。
-
-- glossary 按上游规则 inline 更新；
-- 只有同时满足 ADR 条件时才提出 ADR，但 ADR 等最终决策清单确认后再写入；
-- 在本阶段让 [`to-spec`](.agents/skills/to-spec/SKILL.md) 做代码理解和 seam 分析；seam 是共识的一部分，不单独制造发布确认；
-- 形成精简决策清单：目标、范围、关键选择、seam、未纳入范围和待验证假设；只展示清单，不展示任何 ADR/spec/issue 正文或草稿；
-- 用户确认决策清单后，立即进入阶段 ②。
-
-出口：决策清单已确认，glossary 已按需更新；尚未确认的 ADR/spec/issue 不写入。
-
-### ② 发布 spec
-
-将已确认的决策清单和 seam 分析交给 `to-spec`；此处只综合、写入和发布，不重新采访或再次确认 seam。
-
-- 按 ADR → spec → issue 的顺序执行；issue 发布成功后设置 `ready-for-agent`；格式细则只读取 [`references/rules.md`](references/rules.md)。
-- 相同 feature 复用已有产物，设计变化按 tracker 的更新语义保留历史；
-- 任一步失败都保留已成功写入的内容，记录状态和失败点，重跑时从第一个未完成出口继续；不回滚、不重复发布。
-
-出口：ADR/spec/issue 已写入或发布，只报告路径或标识、状态和未纳入范围，不复制正文。
-
-## 回合连续性
-
-本 skill 是 Long-Horizon Skill。预检、阶段 ①、代码理解、决策清单确认后的阶段 ② 在同一任务链连续执行；进度汇报和阶段切换不是回合终点。仅在需要设计确认、决策清单确认、外部阻塞、用户主动停止或整个 skill 出口时暂停；确认完成后不要求用户额外回复“继续”。
-
-## 本 skill 独有门禁
-
-- 文档正文永不展示；用户只确认精简决策清单，发布后只接收元数据报告；
-- ADR/spec/issue 不设置额外草稿确认；
-- 不写代码、不修改源码或测试、不自动 commit；实现 tickets 交给 `to-tickets`。
-
-## 异常
-
-- 用户放弃或没有可形成 spec 的主题时终止；
-- issue tracker 未配置时报告配置阻塞，不绕过发布；
-- 用户改变已确认设计时回到阶段 ①，按变更语义保留历史，不静默覆盖。

package/template/.agents/skills/grill-to-spec/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Grill to Spec"
-  short_description: "从模糊想法到可执行 Spec — 只打磨设计、产出领域文档与 Spec，不写代码"
-policy:
-  allow_implicit_invocation: false

package/template/.agents/skills/grill-to-spec/references/rules.md

@@ -1,47 +0,0 @@
-# 守则：Grill-to-Spec 本地增量规则
-
-本文件只保存 `grill-to-spec` 相对上游 `grill-with-docs` / `to-spec` 的**增量约束**。Spec 的章节、User Story 形状、Implementation Decisions 等格式全部以 `to-spec` 为唯一事实源，本文件不复制上游模板。
-
-## 预检与状态规则
-
-- 写入前只读确认 issue tracker、目标上下文、feature slug、已有 spec/issue 和当前状态；tracker 未配置或目标不可写时不写 ADR/spec/issue。
-- feature slug 是 spec 路径和 issue 幂等键；候选不明确或冲突时才询问。
-- 记录共识、ADR、spec、issue、`ready-for-agent` 出口；重跑从第一个未完成出口继续，不重复已成功动作。
-- 已有相同共识的 feature 只报告已有路径或标识；设计变化走变更流程，不创建重复 issue。
-
-## Glossary 增量规则
-
-- 懒创建：首个术语解析时才建 `CONTEXT.md`；多上下文时先确认归属，归属不清则询问。
-- 只收本上下文特有术语；定义 WHAT 非 HOW，避免把 glossary 变成实现草稿。
-- glossary 可按上游流程 inline 更新，不额外增加确认轮次；设计变化时按历史保留规则修正。
-
-## ADR 增量规则
-
-- 只有同时满足“难逆转 / 无上下文费解 / 存在真实权衡”时才提议 ADR。
-- ADR 不像 glossary 一样静默 inline 更新；等最终决策清单确认后直接落盘，不展示正文，不增加独立确认轮次。
-- 用户改变决策时不静默覆盖旧 ADR；按项目 ADR 规则追加、废弃或标记 superseded。
-
-## Spec 增量规则
-
-- Spec 的结构与字段全部委托 `to-spec`，本文件不维护第二份模板。
-- 代码理解和 seam 分析属于共识阶段；seam 纳入最终决策清单，不在发布阶段再次询问。
-- 决策清单确认后直接写入 spec；不展示 spec 正文或草稿。
-- 全文沿用已经确认的 glossary 词汇，并尊重所触区域既有 ADR。
-
-## Issue 增量规则
-
-- 按已配置的 issue tracker 直接发布唯一 spec issue；implementation tickets 交给 `to-tickets`。
-- issue 正文不在对话中展示；发布成功后设置 `ready-for-agent`。
-- issue 创建成功但 label/status 更新失败时保留 issue，报告标识和失败点，不删除、不误报为 ready。
-- 设计变化委托 tracker 的原生更新语义：本地追加变更记录，远端按 body/comment/关联关系更新；不另造版本模板。
-
-## 失败与 Git 边界
-
-- 任一步失败都保留已成功写入的内容并报告部分状态；不做跨文件或跨 tracker 回滚，不盲目重试。
-- 本 skill 不自动创建 Git commit；发布文档与 Git 提交是两个独立出口。
-
-## 反模式
-
-- 不复制 `to-spec` 的章节清单、User Story 模板或 Implementation Decisions 细则。
-- 不产出 Glossary / ADR / Spec 之外的额外设计文件。
-- 不把本文件当逐条朗读的对话脚本；它只约束本地增量行为。

package/template/.agents/skills/grill-with-docs/SKILL.md

@@ -1,7 +0,0 @@
----
-name: grill-with-docs
-description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
-disable-model-invocation: true
----
-
-Call the Skill tool twice, for "grilling" and "domain-modeling".

package/template/.agents/skills/grill-with-docs/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Grill with Docs"
-  short_description: "Grill a design and write its docs"
-policy:
-  allow_implicit_invocation: false

package/template/.agents/skills/grilling/SKILL.md

@@ -1,28 +0,0 @@
----
-name: grilling
-description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
----
-
-Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
-
-Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
-
-Format a round like so:
-
-```
-❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
-
-➡️ <your recommended answer>
-
----
-
-❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
-
-➡️ <your recommended answer>
-```
-
-Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
-
-Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
-
-The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/template/.agents/skills/grilling/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Grilling"
-  short_description: "Stress-test thinking a round of questions at a time"

package/template/.agents/skills/handoff/SKILL.md

@@ -1,16 +0,0 @@
----
-name: handoff
-description: Compact the current conversation into a handoff document for another agent to pick up.
-argument-hint: "What will the next session be used for?"
-disable-model-invocation: true
----
-
-Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
-
-Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.
-
-Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
-
-Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
-
-If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/template/.agents/skills/handoff/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Handoff"
-  short_description: "Compact a conversation into a handoff"
-policy:
-  allow_implicit_invocation: false

package/template/.agents/skills/implement/SKILL.md

@@ -1,15 +0,0 @@
----
-name: implement
-description: "Implement a piece of work based on a spec or set of tickets."
-disable-model-invocation: true
----
-
-Implement the work described by the user in the spec or tickets.
-
-Use /tdd where possible, at pre-agreed seams.
-
-Run typechecking regularly, single test files regularly, and the full test suite once at the end.
-
-Once done, use /code-review to review the work.
-
-Commit your work to the current branch.

package/template/.agents/skills/implement/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Implement"
-  short_description: "Build work from a spec or tickets"
-policy:
-  allow_implicit_invocation: false

package/template/.agents/skills/implement-review-loop/SKILL.md

@@ -1,34 +0,0 @@
----
-name: implement-review-loop
-description: "Implement changes with one executor model and one independent reviewer model, iterating on only the changed surface until no actionable issues remain."
-disable-model-invocation: true
----
-
-Use two distinct roles:
-
-- **Executor**: implements the requested change, fixes findings, and runs the smallest relevant verification.
-- **Reviewer**: independently reviews the latest diff and relevant verification results. It does not perform the implementation.
-
-Workflow:
-
-```text
-Executor implements
-→ targeted verification
-→ Reviewer reviews latest diff
-→ if findings exist: Executor fixes only those findings
-→ targeted re-verification
-→ Reviewer re-reviews changed parts and unresolved findings
-→ repeat until Reviewer reports no actionable issues
-```
-
-Rules:
-
-- Keep implementation, testing, and review scoped to the current change and directly affected paths.
-- Prefer targeted tests: changed test files, affected modules, regression cases, or the original reproduction path.
-- Do not rerun equivalent checks after every small edit.
-- Reviewer should inspect the latest diff first, then only enough surrounding code to validate behavior and integration.
-- On subsequent rounds, review the new changes plus unresolved findings; do not restart a whole-project review.
-- Expand test or review scope only when the change crosses modules, modifies shared/public contracts or core infrastructure, targeted evidence is insufficient, final release/merge validation requires it, or the user explicitly requests it.
-- Findings must be concrete and actionable. Separate blockers from optional improvements.
-- Stop the loop when the Reviewer has no actionable findings and targeted verification is green.
-- Do not let the Reviewer silently become the Executor; preserve role independence throughout the loop.

package/template/.agents/skills/implement-review-loop/agents/openai.yaml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "Implement Review Loop"
-  short_description: "Implement with an independent review loop"
-policy:
-  allow_implicit_invocation: false

package/template/.agents/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -1,123 +0,0 @@
-# HTML Report Format
-
-The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
-
-## Scaffold
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Architecture review for {{repo name}}</title>
-    <script src="https://cdn.tailwindcss.com"></script>
-    <script type="module">
-      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
-    </script>
-    <style>
-      /* small custom layer for things Tailwind doesn't cover cleanly:
-         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
-      .seam { stroke-dasharray: 4 4; }
-      .leak { stroke: #dc2626; }
-      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
-    </style>
-  </head>
-  <body class="bg-stone-50 text-slate-900 font-sans">
-    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
-      <header>...</header>
-      <section id="candidates" class="space-y-10">...</section>
-      <section id="top-recommendation">...</section>
-    </main>
-  </body>
-</html>
-```
-
-## Header
-
-Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
-
-## Candidate card
-
-The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
-
-Each candidate is one `<article>`:
-
-- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
-- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
-- **Files**: monospaced list, `font-mono text-sm`.
-- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
-- **Problem**: one sentence. What hurts.
-- **Solution**: one sentence. What changes.
-- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
-- **ADR callout** (if applicable): one line in an amber-tinted box.
-
-No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
-
-## Diagram patterns
-
-Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
-
-### Mermaid graph (the workhorse for dependencies / call flow)
-
-Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
-
-```html
-<div class="rounded-lg border border-slate-200 bg-white p-4">
-  <pre class="mermaid">
-    flowchart LR
-      A[OrderHandler] --> B[OrderValidator]
-      B --> C[OrderRepo]
-      C -.leak.-> D[PricingClient]
-      classDef leak stroke:#dc2626,stroke-width:2px;
-      class C,D leak
-  </pre>
-</div>
-```
-
-### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
-
-Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
-
-### Cross-section (good for layered shallowness)
-
-Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
-
-### Mass diagram (good for "interface as wide as implementation")
-
-Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
-
-### Call-graph collapse
-
-Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
-
-## Style guidance
-
-- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
-- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
-- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
-- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
-- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
-
-## Top recommendation section
-
-One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
-
-## Tone
-
-Plain English, concise, but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
-
-**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
-
-**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
-
-**Phrasings that fit the style:**
-
-- "Order intake module is shallow: interface nearly matches the implementation."
-- "Pricing leaks across the seam."
-- "Deepen: one interface, one place to test."
-- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
-
-**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"*, because those terms aren't in the glossary and don't earn their place.
-
-No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.