From 45afd8074a8b7de5fe073845d080fa9dd6c429fa Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Mon, 13 Jul 2026 10:08:50 +0100 Subject: [PATCH] improve-codebase-architecture: scope the scan to where change is landing (YAGNI) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before scanning, decide where to look. If the user named a direction, take it; otherwise read the last ~20 commit messages to bias exploration toward actively-developed paths. A deepening opportunity in code nobody touches is a refactor you'll never cash in — leverage only pays off where you keep editing. Syncs the docs page and adds a changeset. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/yagni-scope-improve-architecture.md | 5 +++++ docs/engineering/improve-codebase-architecture.md | 2 ++ skills/engineering/improve-codebase-architecture/SKILL.md | 5 +++++ 3 files changed, 12 insertions(+) create mode 100644 .changeset/yagni-scope-improve-architecture.md diff --git a/.changeset/yagni-scope-improve-architecture.md b/.changeset/yagni-scope-improve-architecture.md new file mode 100644 index 0000000..bb1565a --- /dev/null +++ b/.changeset/yagni-scope-improve-architecture.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": minor +--- + +Add a YAGNI scoping filter to the **`improve-codebase-architecture`** skill's Explore step. Instead of scanning the whole repo evenly, it now scopes to where change is actually landing: if you name a direction it takes it, otherwise it reads the last ~20 commit messages to bias exploration toward actively-developed paths. A deepening opportunity in code nobody touches is a refactor you'll never cash in — the leverage only pays off where you keep editing — so the report stops tidying dormant corners of the repo. diff --git a/docs/engineering/improve-codebase-architecture.md b/docs/engineering/improve-codebase-architecture.md index 71589a0..1af6ae8 100644 --- a/docs/engineering/improve-codebase-architecture.md +++ b/docs/engineering/improve-codebase-architecture.md @@ -16,6 +16,8 @@ npx skills update improve-codebase-architecture It does **not** hand you a flat list of refactors. Every candidate has to pass the **deletion test** — would removing this module *concentrate* complexity behind a smaller interface, or just move it around? Only the "concentrates" cases earn a card. That filter is what stops the report from becoming generic cleanup advice. +Unless you point it at a specific area, it also scopes itself to where development is actually landing — reading the recent commits to bias toward the code you're still changing. Deepening a module pays off by making future changes to it easier, so it puts extra weight on the parts of the repo that have recently changed. + ## When to reach for it You invoke this by typing `/improve-codebase-architecture` — the agent won't reach for it on its own. diff --git a/skills/engineering/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md index a79b493..fa7ae91 100644 --- a/skills/engineering/improve-codebase-architecture/SKILL.md +++ b/skills/engineering/improve-codebase-architecture/SKILL.md @@ -17,6 +17,11 @@ This command is _informed_ by the project's domain model and built on a shared d ### 1. Explore +**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look: + +- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below. +- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net. + Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: