From 7a951a4bde04f1a13ad0eb86ef23dbeb84c8381a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 5 May 2026 02:56:29 +0000 Subject: [PATCH] =?UTF-8?q?P0003:=20accept=20+=20execute=20=E2=80=94=20ref?= =?UTF-8?q?rame-before-trimming=20method=20(new=20tier-2=20canon=20doc)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Acceptance: - Flip docs/promotions/P0003 promotion_status: proposed -> accepted - Update tags array ("proposed" -> "accepted") - Fill Review Notes with operator decision (klappy, 2026-05-05) Execution: - canon/methods/reframe-before-trimming.md (NEW): tier-2 method doc - Frontmatter declares: derives_from doing-less-enables-more, vodka-architecture, kiss-simplicity-is-the-ceiling; complements pivot-on-inversion - Codifies the diagnostic move when an MCP tool surface feels bloated: reframe first (the tool count usually collapses mechanically as a side effect); only trim if the frame is right and discomfort persists - Receipts: PTXprint v1.0 -> v1.2 (17 -> 7 -> 3 tools, with the v1.1 trim-only step kept for instructive contrast against the v1.2 reframe) - Sections follow precedent of canon/methods/pivot-on-inversion.md (H1 + blockquote + descriptive headers; no separate Summary section) Sixth of 8. Previous: P0009 (#167), P0001 (#168), P0008 (#169), P0007 (#170), P0006 (#171). Next: P0004 (docs-proxy pattern, new doc). --- canon/methods/reframe-before-trimming.md | 53 +++++++++++++++++++ .../P0003-reframe-before-trimming.md | 16 +++--- 2 files changed, 60 insertions(+), 9 deletions(-) create mode 100644 canon/methods/reframe-before-trimming.md diff --git a/canon/methods/reframe-before-trimming.md b/canon/methods/reframe-before-trimming.md new file mode 100644 index 0000000..37c1eee --- /dev/null +++ b/canon/methods/reframe-before-trimming.md @@ -0,0 +1,53 @@ +--- +uri: klappy://canon/methods/reframe-before-trimming +title: "Reframe Before Trimming — When a Tool Surface Feels Bloated, Question the Frame" +audience: canon +exposure: nav +tier: 2 +voice: neutral +stability: evolving +tags: ["canon", "method", "refactoring", "tool-surface", "mcp-server", "vodka-architecture", "doing-less", "diagnosis"] +derives_from: + - klappy://canon/principles/doing-less-enables-more + - klappy://canon/principles/vodka-architecture + - klappy://canon/principles/kiss-simplicity-is-the-ceiling +complements: + - klappy://canon/methods/pivot-on-inversion +status: active +--- + +# Reframe Before Trimming + +> When an MCP server's tool surface feels bloated, the bloat is usually in the frame the surface implies, not in the tool count. Reframe first; the trim follows mechanically. + +## When This Method Applies + +A surface feels bloated. The instinct is to cut tools. This method says: pause that instinct. + +Specifically, this method applies when: + +- An existing MCP server has accrued tools across multiple versions +- Reviewers describe the surface as "too many tools" or "feels overlapping" +- A refactor is being scoped that will trim the count + +## The Method + +1. **Do not ask "which tools can we cut?"** +2. **Ask "is the frame this surface implies actually correct?"** Write down what mental model a fresh consumer would build by reading the tool list cold. Compare it against what the server actually does in the world. +3. **If the frame is wrong, fix the frame.** Restate the server's job in one sentence that matches reality. The tool count usually collapses mechanically because tools justified only by the wrong frame stop being justified. +4. **If the frame is right and the tool count still feels high**, the discomfort is probably elsewhere — vodka-boundary leakage (`canon/principles/vodka-architecture.md`), async shape mismatch (`canon/principles/async-by-default-for-long-running-tools.md` if proposed), or consumer-side wiring friction. Diagnose that, not the count. + +## Failure Mode — Trimming Without Reframing + +Cutting tools without reframing produces a smaller surface that still embodies the wrong model. The tool count drops; the conceptual debt stays. Bloat returns at the next feature wave because the model's gravity pulls toward the same shape. + +## Receipts + +- **PTXprint-MCP v1.0 → v1.2.** v1.0 had 17 tools modeling the server as a project filesystem. v1.1 trimmed to 7 by cutting features but kept the filesystem frame. v1.2 reframed the server as a pure function `(config, sources, fonts) → PDF` with content-addressed cache. Tool count collapsed to 3 — `submit_typeset`, `get_job_status`, `cancel_job` — without functionality loss. The trim was a side effect of the reframe, not its goal. +- *(Receipt pattern: each future application adds one row — server, before-count, after-count, the reframe in one sentence. Dense, not narrative.)* + +## Relationship to Adjacent Canon + +This method is the operational complement to `canon/principles/doing-less-enables-more`. That principle is the structural empirical claim about why thin substrates win and catches NOT-ADOPTING-new-opinions through its smell test. This method addresses the post-hoc case: the substrate already drifted; the bloat is observable; what now? + +`canon/methods/pivot-on-inversion` is adjacent but different — that method is about recovery when an iteration's gradient turns negative. This method is about diagnosis when a surface's tool count feels wrong. Pivot-on-inversion answers "should we keep going?"; reframe-before-trimming answers "what should we change first?" diff --git a/docs/promotions/P0003-reframe-before-trimming.md b/docs/promotions/P0003-reframe-before-trimming.md index 630a95e..72188ad 100644 --- a/docs/promotions/P0003-reframe-before-trimming.md +++ b/docs/promotions/P0003-reframe-before-trimming.md @@ -6,8 +6,8 @@ exposure: nav tier: 3 voice: neutral stability: evolving -tags: ["promotions", "proposed", "mcp-server", "tool-surface", "refactoring", "vodka-architecture", "doing-less"] -promotion_status: proposed +tags: ["promotions", "accepted", "mcp-server", "tool-surface", "refactoring", "vodka-architecture", "doing-less"] +promotion_status: accepted --- # P0003: Reframe Before Trimming — When a Tool Surface Feels Bloated, Question the Frame @@ -134,16 +134,14 @@ Placing this in `canon/methods/` rather than `canon/principles/` is deliberate. ## Status -`proposed` +`accepted` (2026-05-05) ## Review Notes -(To be filled during review) - -- **Reviewer**: -- **Decision**: -- **Date**: -- **Notes**: +- **Reviewer**: klappy (operator) +- **Decision**: `accepted` +- **Date**: 2026-05-05 +- **Notes**: First of three new-doc proposals (P0003/P0004/P0005). Created `canon/methods/reframe-before-trimming.md` as a tier-2 method doc, following the precedent set by `canon/methods/pivot-on-inversion.md` (the doc named in P0003's `complements` field): H1 + blockquote + descriptive section headers, no separate `## Summary` (the blockquote carries the compressed argument). Frontmatter, body, and section structure used verbatim from P0003's "Proposed Language" block. ## Execution Record