From d5af1cb1058abc083f368090ffd3c0198af4ad69 Mon Sep 17 00:00:00 2001 From: Thomas Kosiewski Date: Fri, 5 Jun 2026 13:36:44 +0200 Subject: [PATCH] chore: skills Change-Id: Ie4e8762000dc88d7f99c6ebf6b450d3b7367d781 Signed-off-by: Thomas Kosiewski --- .../skills/grill-with-docs/CONTEXT-FORMAT.md | 23 +-- .agents/skills/grill-with-docs/SKILL.md | 2 +- .../HTML-REPORT.md | 133 ++++++++++++++++++ .../improve-codebase-architecture/SKILL.md | 20 ++- .agents/skills/to-issues/SKILL.md | 4 +- .agents/skills/to-prd/SKILL.md | 10 +- .agents/skills/triage/OUT-OF-SCOPE.md | 3 + skills-lock.json | 8 +- 8 files changed, 167 insertions(+), 36 deletions(-) create mode 100644 .agents/skills/improve-codebase-architecture/HTML-REPORT.md diff --git a/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md b/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md index ddfa247c..eaf2a185 100644 --- a/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md +++ b/.agents/skills/grill-with-docs/CONTEXT-FORMAT.md @@ -10,7 +10,7 @@ ## Language **Order**: -{A concise description of the term} +{A one or two sentence description of the term} _Avoid_: Purchase, transaction **Invoice**: @@ -20,31 +20,14 @@ _Avoid_: Bill, payment request **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account - -## Relationships - -- An **Order** produces one or more **Invoices** -- An **Invoice** belongs to exactly one **Customer** - -## Example dialogue - -> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?" -> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed." - -## Flagged ambiguities - -- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts. ``` ## Rules -- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid. -- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution. -- **Keep definitions tight.** One sentence max. Define what it IS, not what it does. -- **Show relationships.** Use bold term names and express cardinality where obvious. +- **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. -- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts. ## Single vs multi-context repos diff --git a/.agents/skills/grill-with-docs/SKILL.md b/.agents/skills/grill-with-docs/SKILL.md index 6dad6ad7..5ea0aa91 100644 --- a/.agents/skills/grill-with-docs/SKILL.md +++ b/.agents/skills/grill-with-docs/SKILL.md @@ -73,7 +73,7 @@ When the user states how something works, check whether the code agrees. If you 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). -Don't couple `CONTEXT.md` to implementation details. Only include terms that are meaningful to domain experts. +`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 diff --git a/.agents/skills/improve-codebase-architecture/HTML-REPORT.md b/.agents/skills/improve-codebase-architecture/HTML-REPORT.md new file mode 100644 index 00000000..de09df52 --- /dev/null +++ b/.agents/skills/improve-codebase-architecture/HTML-REPORT.md @@ -0,0 +1,133 @@ +# 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 + + + + + Architecture review — {{repo name}} + + + + + +
+
...
+
...
+
...
+
+ + +``` + +## 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 ([LANGUAGE.md](LANGUAGE.md)) without ceremony. + +Each candidate is one `
`: + +- **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 +
+ 
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+
+
+``` + +### Hand-built boxes-and-arrows (when Mermaid's layout fights you) + +Modules as `
`s with borders and labels. Arrows as inline SVG `` or `` 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 — 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 — they should 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 [LANGUAGE.md](LANGUAGE.md). 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"_ — 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 [LANGUAGE.md](LANGUAGE.md), reach for one that is before inventing a new one. diff --git a/.agents/skills/improve-codebase-architecture/SKILL.md b/.agents/skills/improve-codebase-architecture/SKILL.md index 05984a60..c12b263b 100644 --- a/.agents/skills/improve-codebase-architecture/SKILL.md +++ b/.agents/skills/improve-codebase-architecture/SKILL.md @@ -44,20 +44,30 @@ Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want. -### 2. Present candidates +### 2. Present candidates as an HTML report -Present a numbered list of deepening opportunities. For each candidate: +Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `/architecture-review-.html` so each run gets a fresh file. Open it for the user — `xdg-open ` on Linux, `open ` on macOS, `start ` on Windows — and tell them the absolute path. + +The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual. + +For each candidate, the same template as before, but rendered as a card: - **Files** — which files/modules are involved - **Problem** — why the current architecture is causing friction - **Solution** — plain English description of what would change -- **Benefits** — explained in terms of locality and leverage, and also in how tests would improve +- **Benefits** — explained in terms of locality and leverage, and how tests would improve +- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening +- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge + +End the report with a **Top recommendation** section: which candidate you'd tackle first and why. **Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." -**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids. +**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids. + +See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance. -Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?" +Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?" ### 3. Grilling loop diff --git a/.agents/skills/to-issues/SKILL.md b/.agents/skills/to-issues/SKILL.md index 5a407161..9f6efbfe 100644 --- a/.agents/skills/to-issues/SKILL.md +++ b/.agents/skills/to-issues/SKILL.md @@ -51,7 +51,7 @@ Iterate until the user approves the breakdown. ### 5. Publish the issues to the issue tracker -For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. Apply the `needs-triage` triage label so each issue enters the normal triage flow. +For each approved slice, publish a new issue to the issue tracker. Use the issue body template below. These issues are considered ready for AFK agents, so publish them with the correct triage label unless instructed otherwise. Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field. @@ -64,6 +64,8 @@ A reference to the parent issue on the issue tracker (if the source was an exist A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation. +Avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it here and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + ## Acceptance criteria - [ ] Criterion 1 diff --git a/.agents/skills/to-prd/SKILL.md b/.agents/skills/to-prd/SKILL.md index 7bdc82a0..ee758fdc 100644 --- a/.agents/skills/to-prd/SKILL.md +++ b/.agents/skills/to-prd/SKILL.md @@ -11,13 +11,11 @@ The issue tracker and triage label vocabulary should have been provided to you 1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching. -2. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation. +2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. -A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes. +Check with the user that these seams match their expectations. -Check with the user that these modules match their expectations. Check with the user which modules they want tests written for. - -3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `needs-triage` triage label so it enters the normal triage flow. +3. Write the PRD using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage. @@ -55,6 +53,8 @@ A list of implementation decisions that were made. This can include: Do NOT include specific file paths or code snippets. They may end up being outdated very quickly. +Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits. + ## Testing Decisions A list of testing decisions that were made. Include: diff --git a/.agents/skills/triage/OUT-OF-SCOPE.md b/.agents/skills/triage/OUT-OF-SCOPE.md index df6aaa49..e89845ca 100644 --- a/.agents/skills/triage/OUT-OF-SCOPE.md +++ b/.agents/skills/triage/OUT-OF-SCOPE.md @@ -53,6 +53,8 @@ interface ThemeConfig { - #87 — "Night theme for accessibility" - #134 — "Dark theme option" +``` + ### Naming the file Use a short, descriptive kebab-case name for the concept: `dark-mode.md`, `plugin-system.md`, `graphql-api.md`. The name should be recognizable enough that someone browsing the directory understands what was rejected without opening the file. @@ -99,3 +101,4 @@ If the maintainer changes their mind about a previously rejected concept: - Delete the `.out-of-scope/` file - The skill does not need to reopen old issues — they're historical records - The new issue that triggered the reconsideration proceeds through normal triage +``` diff --git a/skills-lock.json b/skills-lock.json index 6ace0a96..61fbe3a3 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -11,13 +11,13 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/grill-with-docs/SKILL.md", - "computedHash": "31a5b1ae116558bf7d3f633f442835f54bd7645923d4f45c7823e52a97317666" + "computedHash": "eb0e91e84277283dc2b23ed544399e53afd6b5287e5b6929f25fe8aa608e164b" }, "improve-codebase-architecture": { "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/improve-codebase-architecture/SKILL.md", - "computedHash": "c77b86b4332919499608f9af1880074e1fec65a59b95c70c27a9f39cd137865e" + "computedHash": "ef32aea0a8fab9b365ff9e08a95f8d353e20ca21ea46ec2e73587c86dd341351" }, "tdd": { "source": "mattpocock/skills", @@ -29,13 +29,13 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/to-issues/SKILL.md", - "computedHash": "73a91f30784523aa59ec9b02769576ebfc738e2cd5ad8f6441076031f0a5d5ac" + "computedHash": "47f648f3414848ccfc62cb41d2828b7e575fb5e7cbd6c4bdf630c063b5dc5e82" }, "to-prd": { "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/to-prd/SKILL.md", - "computedHash": "fd8c259f9c44eff08e29a1a2fc71a806a3568d279a55387a361f78620b10f2aa" + "computedHash": "a6d6d475f1d01c201937fa0c306e55b7056b02023ad615bc92f57514e831dd31" }, "triage": { "source": "mattpocock/skills",