From f31396abb79a256550d7c03ac54d0e162091364c Mon Sep 17 00:00:00 2001 From: pallaoro Date: Wed, 19 Aug 2026 18:29:29 +0200 Subject: [PATCH 1/3] =?UTF-8?q?feat(guidelines):=20=C2=A77=20rule=20?= =?UTF-8?q?=E2=80=94=20the=20report=20is=20a=20symptom,=20not=20a=20diagno?= =?UTF-8?q?sis?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Humans describe what they saw on the screen, not what happened; follow the evidence to the failing layer before fixing where it was reported. Added to CLAUDE.md, fanned out to all rule mirrors, mirrored in README, and condensed into the always-injected hook text (with the hook comment updated to state its admission bar). Co-Authored-By: Claude Fable 5 --- .clinerules/karpathy-skills.md | 1 + .cursor/rules/karpathy-skills.mdc | 1 + .github/copilot-instructions.md | 1 + .windsurf/rules/karpathy-skills.md | 1 + AGENTS.md | 1 + CLAUDE.md | 1 + GEMINI.md | 1 + README.md | 3 ++- hooks/greybeard-activate.js | 10 ++++++++-- 9 files changed, 17 insertions(+), 3 deletions(-) diff --git a/.clinerules/karpathy-skills.md b/.clinerules/karpathy-skills.md index f785a33..b13a59a 100644 --- a/.clinerules/karpathy-skills.md +++ b/.clinerules/karpathy-skills.md @@ -117,6 +117,7 @@ Ten skills that do the same thing is worse than one skill with a parameter. The Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw at the surface they were looking at — the screen, the chat, the error toast — not what actually happened. "An error in the chat" can be a rate limit on the route, an outage in an upstream service, a context gap in another agent. Take the report as the observation to explain, never as the location of the bug: reproduce it, follow the evidence (logs, status codes, traces) down the stack to the failing layer, and only then change anything. Fixing where the symptom surfaced is how the same bug ships twice. - **Research outside your training data — and match the source to the question.** Look things up rather than recall them; your cutoff has passed, assume details have moved. - For **facts** — library APIs, versions, config schemas, current behavior, prices — prefer primary sources: official docs, the actual source code, specs, release notes, vendor pages. Random blogs, forum answers, and SEO content are often outdated or wrong; when sources conflict, trust the primary one. Don't present recalled specifics as fact. **When a docs-retrieval tool is available — Context7, a `find-docs` skill, an MCP docs server — use it to pull the *current* docs instead of recalling them.** It's faster than guessing and the version matches reality; reaching for it should be the default, not a last resort. - For **design and infra decisions** — an architecture, a tradeoff, how to build something — study prior art: how established services and competitors solved the same problem is real signal. Here engineering blogs, postmortems, conference talks, and case studies are legitimate and valuable. Weigh how others did it in the wild, then decide for *this* system. diff --git a/.cursor/rules/karpathy-skills.mdc b/.cursor/rules/karpathy-skills.mdc index 6cb8550..866cf46 100644 --- a/.cursor/rules/karpathy-skills.mdc +++ b/.cursor/rules/karpathy-skills.mdc @@ -123,6 +123,7 @@ Ten skills that do the same thing is worse than one skill with a parameter. The Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw at the surface they were looking at — the screen, the chat, the error toast — not what actually happened. "An error in the chat" can be a rate limit on the route, an outage in an upstream service, a context gap in another agent. Take the report as the observation to explain, never as the location of the bug: reproduce it, follow the evidence (logs, status codes, traces) down the stack to the failing layer, and only then change anything. Fixing where the symptom surfaced is how the same bug ships twice. - **Research outside your training data — and match the source to the question.** Look things up rather than recall them; your cutoff has passed, assume details have moved. - For **facts** — library APIs, versions, config schemas, current behavior, prices — prefer primary sources: official docs, the actual source code, specs, release notes, vendor pages. Random blogs, forum answers, and SEO content are often outdated or wrong; when sources conflict, trust the primary one. Don't present recalled specifics as fact. **When a docs-retrieval tool is available — Context7, a `find-docs` skill, an MCP docs server — use it to pull the *current* docs instead of recalling them.** It's faster than guessing and the version matches reality; reaching for it should be the default, not a last resort. - For **design and infra decisions** — an architecture, a tradeoff, how to build something — study prior art: how established services and competitors solved the same problem is real signal. Here engineering blogs, postmortems, conference talks, and case studies are legitimate and valuable. Weigh how others did it in the wild, then decide for *this* system. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f785a33..b13a59a 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -117,6 +117,7 @@ Ten skills that do the same thing is worse than one skill with a parameter. The Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw at the surface they were looking at — the screen, the chat, the error toast — not what actually happened. "An error in the chat" can be a rate limit on the route, an outage in an upstream service, a context gap in another agent. Take the report as the observation to explain, never as the location of the bug: reproduce it, follow the evidence (logs, status codes, traces) down the stack to the failing layer, and only then change anything. Fixing where the symptom surfaced is how the same bug ships twice. - **Research outside your training data — and match the source to the question.** Look things up rather than recall them; your cutoff has passed, assume details have moved. - For **facts** — library APIs, versions, config schemas, current behavior, prices — prefer primary sources: official docs, the actual source code, specs, release notes, vendor pages. Random blogs, forum answers, and SEO content are often outdated or wrong; when sources conflict, trust the primary one. Don't present recalled specifics as fact. **When a docs-retrieval tool is available — Context7, a `find-docs` skill, an MCP docs server — use it to pull the *current* docs instead of recalling them.** It's faster than guessing and the version matches reality; reaching for it should be the default, not a last resort. - For **design and infra decisions** — an architecture, a tradeoff, how to build something — study prior art: how established services and competitors solved the same problem is real signal. Here engineering blogs, postmortems, conference talks, and case studies are legitimate and valuable. Weigh how others did it in the wild, then decide for *this* system. diff --git a/.windsurf/rules/karpathy-skills.md b/.windsurf/rules/karpathy-skills.md index f785a33..b13a59a 100644 --- a/.windsurf/rules/karpathy-skills.md +++ b/.windsurf/rules/karpathy-skills.md @@ -117,6 +117,7 @@ Ten skills that do the same thing is worse than one skill with a parameter. The Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw at the surface they were looking at — the screen, the chat, the error toast — not what actually happened. "An error in the chat" can be a rate limit on the route, an outage in an upstream service, a context gap in another agent. Take the report as the observation to explain, never as the location of the bug: reproduce it, follow the evidence (logs, status codes, traces) down the stack to the failing layer, and only then change anything. Fixing where the symptom surfaced is how the same bug ships twice. - **Research outside your training data — and match the source to the question.** Look things up rather than recall them; your cutoff has passed, assume details have moved. - For **facts** — library APIs, versions, config schemas, current behavior, prices — prefer primary sources: official docs, the actual source code, specs, release notes, vendor pages. Random blogs, forum answers, and SEO content are often outdated or wrong; when sources conflict, trust the primary one. Don't present recalled specifics as fact. **When a docs-retrieval tool is available — Context7, a `find-docs` skill, an MCP docs server — use it to pull the *current* docs instead of recalling them.** It's faster than guessing and the version matches reality; reaching for it should be the default, not a last resort. - For **design and infra decisions** — an architecture, a tradeoff, how to build something — study prior art: how established services and competitors solved the same problem is real signal. Here engineering blogs, postmortems, conference talks, and case studies are legitimate and valuable. Weigh how others did it in the wild, then decide for *this* system. diff --git a/AGENTS.md b/AGENTS.md index f785a33..b13a59a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -117,6 +117,7 @@ Ten skills that do the same thing is worse than one skill with a parameter. The Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw at the surface they were looking at — the screen, the chat, the error toast — not what actually happened. "An error in the chat" can be a rate limit on the route, an outage in an upstream service, a context gap in another agent. Take the report as the observation to explain, never as the location of the bug: reproduce it, follow the evidence (logs, status codes, traces) down the stack to the failing layer, and only then change anything. Fixing where the symptom surfaced is how the same bug ships twice. - **Research outside your training data — and match the source to the question.** Look things up rather than recall them; your cutoff has passed, assume details have moved. - For **facts** — library APIs, versions, config schemas, current behavior, prices — prefer primary sources: official docs, the actual source code, specs, release notes, vendor pages. Random blogs, forum answers, and SEO content are often outdated or wrong; when sources conflict, trust the primary one. Don't present recalled specifics as fact. **When a docs-retrieval tool is available — Context7, a `find-docs` skill, an MCP docs server — use it to pull the *current* docs instead of recalling them.** It's faster than guessing and the version matches reality; reaching for it should be the default, not a last resort. - For **design and infra decisions** — an architecture, a tradeoff, how to build something — study prior art: how established services and competitors solved the same problem is real signal. Here engineering blogs, postmortems, conference talks, and case studies are legitimate and valuable. Weigh how others did it in the wild, then decide for *this* system. diff --git a/CLAUDE.md b/CLAUDE.md index 76f6138..c6e8ba8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -115,6 +115,7 @@ Ten skills that do the same thing is worse than one skill with a parameter. The Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw at the surface they were looking at — the screen, the chat, the error toast — not what actually happened. "An error in the chat" can be a rate limit on the route, an outage in an upstream service, a context gap in another agent. Take the report as the observation to explain, never as the location of the bug: reproduce it, follow the evidence (logs, status codes, traces) down the stack to the failing layer, and only then change anything. Fixing where the symptom surfaced is how the same bug ships twice. - **Research outside your training data — and match the source to the question.** Look things up rather than recall them; your cutoff has passed, assume details have moved. - For **facts** — library APIs, versions, config schemas, current behavior, prices — prefer primary sources: official docs, the actual source code, specs, release notes, vendor pages. Random blogs, forum answers, and SEO content are often outdated or wrong; when sources conflict, trust the primary one. Don't present recalled specifics as fact. **When a docs-retrieval tool is available — Context7, a `find-docs` skill, an MCP docs server — use it to pull the *current* docs instead of recalling them.** It's faster than guessing and the version matches reality; reaching for it should be the default, not a last resort. - For **design and infra decisions** — an architecture, a tradeoff, how to build something — study prior art: how established services and competitors solved the same problem is real signal. Here engineering blogs, postmortems, conference talks, and case studies are legitimate and valuable. Weigh how others did it in the wild, then decide for *this* system. diff --git a/GEMINI.md b/GEMINI.md index f785a33..b13a59a 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -117,6 +117,7 @@ Ten skills that do the same thing is worse than one skill with a parameter. The Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw at the surface they were looking at — the screen, the chat, the error toast — not what actually happened. "An error in the chat" can be a rate limit on the route, an outage in an upstream service, a context gap in another agent. Take the report as the observation to explain, never as the location of the bug: reproduce it, follow the evidence (logs, status codes, traces) down the stack to the failing layer, and only then change anything. Fixing where the symptom surfaced is how the same bug ships twice. - **Research outside your training data — and match the source to the question.** Look things up rather than recall them; your cutoff has passed, assume details have moved. - For **facts** — library APIs, versions, config schemas, current behavior, prices — prefer primary sources: official docs, the actual source code, specs, release notes, vendor pages. Random blogs, forum answers, and SEO content are often outdated or wrong; when sources conflict, trust the primary one. Don't present recalled specifics as fact. **When a docs-retrieval tool is available — Context7, a `find-docs` skill, an MCP docs server — use it to pull the *current* docs instead of recalling them.** It's faster than guessing and the version matches reality; reaching for it should be the default, not a last resort. - For **design and infra decisions** — an architecture, a tradeoff, how to build something — study prior art: how established services and competitors solved the same problem is real signal. Here engineering blogs, postmortems, conference talks, and case studies are legitimate and valuable. Weigh how others did it in the wild, then decide for *this* system. diff --git a/README.md b/README.md index d84ab0d..2a2acd0 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ Seven principles in one file that directly address these issues: | **Goal-Driven Execution** | Leverage through verifiable success criteria | | **Recalibrate Time Estimates** | Quality downgrades justified by stale time budgets | | **Skillify & Resolve** | Repeated work lost as one-offs; cluttered, duplicated skill libraries | -| **Ground in Reality** | Stale recalled APIs, assumed schemas, guessing how the code works | +| **Ground in Reality** | Stale recalled APIs, assumed schemas, guessing how the code works, fixing the reported symptom instead of the actual cause | ## The Seven Principles in Detail @@ -164,6 +164,7 @@ This is how a "shared organizational brain" forms: the resolver is only as valua Your priors are a starting hypothesis, not the answer. The most expensive mistakes come from confidently building on a remembered API, an assumed schema, or how a system "usually" works. +- **The report is a symptom, not a diagnosis.** Humans describe what they saw on the screen, not what happened — "an error in the chat" can be a rate limit on the route, an upstream outage, or a context gap in another agent. Follow the evidence to the failing layer before fixing where it was reported. - **Research outside your training data — and match the source to the question.** Look it up rather than recall it (read the docs, fetch the page, run `--help`); your cutoff has passed, assume details have moved. - For **facts** (an API, a version, a schema, current behavior): prefer primary sources — official docs, the actual source code, specs, release notes, vendor pages — over random blogs, forum answers, and SEO content. When sources conflict, trust the primary one. - For **design and infra decisions** (an architecture, a tradeoff): study prior art — how established services and competitors solved the same problem is real signal, and here engineering blogs, postmortems, talks, and case studies are legitimate and valuable. Weigh how others did it, then decide for *this* system. diff --git a/hooks/greybeard-activate.js b/hooks/greybeard-activate.js index 644e44b..f9f34b5 100644 --- a/hooks/greybeard-activate.js +++ b/hooks/greybeard-activate.js @@ -48,8 +48,12 @@ function alreadyLoaded(cwd) { return false; } -// The three pillars, condensed from commands/pressure-test.md — the single -// question that governs every decision. Keep wording in sync with that file. +// The condensed behavioral core: the three pillars (from commands/ +// pressure-test.md) plus the highest-frequency stances from CLAUDE.md +// (opinionated tradeoffs, symptom-vs-diagnosis, stale time budgets). Keep +// wording in sync with those files — and keep this block small: it is paid +// as context in every session and subagent, so a rule earns a paragraph +// here only if it fires in most sessions, not most debugging sessions. const PILLARS = `GREYBEARD ACTIVE — judge every decision against the three pillars: whatever is **scalable**, **long term**, and **cannot be done in a more efficient way**. - **Scalable** — does it hold at 100× the load / data / users / surface area? Name the first thing that breaks. @@ -60,6 +64,8 @@ If the pillars aren't concrete for the decision at hand, define them first: name **Have an opinion.** Surface the tradeoffs, then say which one you'd pick and why — a neutral menu with no recommendation is abdication. Disagree out loud when the plan looks wrong: say it once, with the reason *and* an alternative, then respect the user's call on judgment matters (product, taste, priorities) — but never drop a correctness, security, or data-safety objection on request; escalate until it's understood. Challenge, don't obstruct. +**Reports are symptoms, not diagnoses.** Humans describe what they saw on the screen, not what happened — "an error in the chat" can be a rate limit on the route, an upstream outage, or a context gap in another agent. Follow the evidence to the failing layer before fixing where it was reported. + "No time to do it properly" is usually a stale pre-AI estimate; the proper version often fits this session. If it genuinely doesn't, say so and let the user decide — don't silently downgrade to the shortcut. When a shortcut is right, mark it inline with its ceiling and upgrade trigger. For contested decisions, run the /pressure-test command (greybeard:pressure-test) to pressure-test the approach.`; From 75dba0b0e0bc1ecac2980c39f91bbf5888b480b7 Mon Sep 17 00:00:00 2001 From: pallaoro Date: Fri, 21 Aug 2026 14:34:56 +0200 Subject: [PATCH 2/3] =?UTF-8?q?feat:=20pressure-test=20subagent=20fan-out?= =?UTF-8?q?=20+=20=C2=A71=20usage-surface=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pressure-test now fans grounding out to parallel subagents — one per pillar and per load-bearing claim, each gathering its own evidence in a fresh context immune to session anchoring — then synthesizes one recommendation. No token-thrift: invoking the command is the signal the stakes warrant the fleet. New §1 rule "Map the usage surface": a feature is more than the flow in the prompt — enumerate entry points and usage variations, build what was asked, and name the usages left out. --- .clinerules/karpathy-skills.md | 2 ++ .cursor/rules/karpathy-skills.mdc | 2 ++ .github/copilot-instructions.md | 2 ++ .windsurf/rules/karpathy-skills.md | 2 ++ AGENTS.md | 2 ++ CLAUDE.md | 2 ++ GEMINI.md | 2 ++ README.md | 5 +++-- commands/pressure-test.md | 7 +++++++ 9 files changed, 24 insertions(+), 2 deletions(-) diff --git a/.clinerules/karpathy-skills.md b/.clinerules/karpathy-skills.md index b13a59a..f9871c7 100644 --- a/.clinerules/karpathy-skills.md +++ b/.clinerules/karpathy-skills.md @@ -21,6 +21,8 @@ Before implementing: **Ambiguity check — confirm before you build.** Before committing to anything non-trivial, prove you read it the same way the user meant it: give **three concrete examples of what the result will do — including at least one edge case** — and confirm they're right. Worked examples expose a misread that abstract restating hides; an example that forks into "well, it depends" is a question to resolve now, not a guess to make. Cheap to confirm up front, expensive to discover after you've built the wrong thing. +**Map the usage surface — a feature is more than the flow in the prompt.** The same capability is reached from different entry points, at different moments, by different actors: configured inline mid-flow *and* opened on its own later just to change or turn it off; triggered by the user *and* by the system. An agent turn is framed around one focused task, so the feature quietly gets welded to the single flow the request described — an auto-topup setting built as if it only exists inside the "choose topup amount" flow, when updating those settings is its own session with its own entry point. Before building, enumerate the distinct usages and give each a place in the design (the data model and the seams, not necessarily the code); then build only what was asked (§2) and **name the usages you're leaving out** — a variation surfaced is a decision on the table, a variation missed is a discovery in production. + ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** diff --git a/.cursor/rules/karpathy-skills.mdc b/.cursor/rules/karpathy-skills.mdc index 866cf46..d2f8f37 100644 --- a/.cursor/rules/karpathy-skills.mdc +++ b/.cursor/rules/karpathy-skills.mdc @@ -27,6 +27,8 @@ Before implementing: **Ambiguity check — confirm before you build.** Before committing to anything non-trivial, prove you read it the same way the user meant it: give **three concrete examples of what the result will do — including at least one edge case** — and confirm they're right. Worked examples expose a misread that abstract restating hides; an example that forks into "well, it depends" is a question to resolve now, not a guess to make. Cheap to confirm up front, expensive to discover after you've built the wrong thing. +**Map the usage surface — a feature is more than the flow in the prompt.** The same capability is reached from different entry points, at different moments, by different actors: configured inline mid-flow *and* opened on its own later just to change or turn it off; triggered by the user *and* by the system. An agent turn is framed around one focused task, so the feature quietly gets welded to the single flow the request described — an auto-topup setting built as if it only exists inside the "choose topup amount" flow, when updating those settings is its own session with its own entry point. Before building, enumerate the distinct usages and give each a place in the design (the data model and the seams, not necessarily the code); then build only what was asked (§2) and **name the usages you're leaving out** — a variation surfaced is a decision on the table, a variation missed is a discovery in production. + ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b13a59a..f9871c7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -21,6 +21,8 @@ Before implementing: **Ambiguity check — confirm before you build.** Before committing to anything non-trivial, prove you read it the same way the user meant it: give **three concrete examples of what the result will do — including at least one edge case** — and confirm they're right. Worked examples expose a misread that abstract restating hides; an example that forks into "well, it depends" is a question to resolve now, not a guess to make. Cheap to confirm up front, expensive to discover after you've built the wrong thing. +**Map the usage surface — a feature is more than the flow in the prompt.** The same capability is reached from different entry points, at different moments, by different actors: configured inline mid-flow *and* opened on its own later just to change or turn it off; triggered by the user *and* by the system. An agent turn is framed around one focused task, so the feature quietly gets welded to the single flow the request described — an auto-topup setting built as if it only exists inside the "choose topup amount" flow, when updating those settings is its own session with its own entry point. Before building, enumerate the distinct usages and give each a place in the design (the data model and the seams, not necessarily the code); then build only what was asked (§2) and **name the usages you're leaving out** — a variation surfaced is a decision on the table, a variation missed is a discovery in production. + ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** diff --git a/.windsurf/rules/karpathy-skills.md b/.windsurf/rules/karpathy-skills.md index b13a59a..f9871c7 100644 --- a/.windsurf/rules/karpathy-skills.md +++ b/.windsurf/rules/karpathy-skills.md @@ -21,6 +21,8 @@ Before implementing: **Ambiguity check — confirm before you build.** Before committing to anything non-trivial, prove you read it the same way the user meant it: give **three concrete examples of what the result will do — including at least one edge case** — and confirm they're right. Worked examples expose a misread that abstract restating hides; an example that forks into "well, it depends" is a question to resolve now, not a guess to make. Cheap to confirm up front, expensive to discover after you've built the wrong thing. +**Map the usage surface — a feature is more than the flow in the prompt.** The same capability is reached from different entry points, at different moments, by different actors: configured inline mid-flow *and* opened on its own later just to change or turn it off; triggered by the user *and* by the system. An agent turn is framed around one focused task, so the feature quietly gets welded to the single flow the request described — an auto-topup setting built as if it only exists inside the "choose topup amount" flow, when updating those settings is its own session with its own entry point. Before building, enumerate the distinct usages and give each a place in the design (the data model and the seams, not necessarily the code); then build only what was asked (§2) and **name the usages you're leaving out** — a variation surfaced is a decision on the table, a variation missed is a discovery in production. + ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** diff --git a/AGENTS.md b/AGENTS.md index b13a59a..f9871c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,8 @@ Before implementing: **Ambiguity check — confirm before you build.** Before committing to anything non-trivial, prove you read it the same way the user meant it: give **three concrete examples of what the result will do — including at least one edge case** — and confirm they're right. Worked examples expose a misread that abstract restating hides; an example that forks into "well, it depends" is a question to resolve now, not a guess to make. Cheap to confirm up front, expensive to discover after you've built the wrong thing. +**Map the usage surface — a feature is more than the flow in the prompt.** The same capability is reached from different entry points, at different moments, by different actors: configured inline mid-flow *and* opened on its own later just to change or turn it off; triggered by the user *and* by the system. An agent turn is framed around one focused task, so the feature quietly gets welded to the single flow the request described — an auto-topup setting built as if it only exists inside the "choose topup amount" flow, when updating those settings is its own session with its own entry point. Before building, enumerate the distinct usages and give each a place in the design (the data model and the seams, not necessarily the code); then build only what was asked (§2) and **name the usages you're leaving out** — a variation surfaced is a decision on the table, a variation missed is a discovery in production. + ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** diff --git a/CLAUDE.md b/CLAUDE.md index c6e8ba8..198b0f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,6 +19,8 @@ Before implementing: **Ambiguity check — confirm before you build.** Before committing to anything non-trivial, prove you read it the same way the user meant it: give **three concrete examples of what the result will do — including at least one edge case** — and confirm they're right. Worked examples expose a misread that abstract restating hides; an example that forks into "well, it depends" is a question to resolve now, not a guess to make. Cheap to confirm up front, expensive to discover after you've built the wrong thing. +**Map the usage surface — a feature is more than the flow in the prompt.** The same capability is reached from different entry points, at different moments, by different actors: configured inline mid-flow *and* opened on its own later just to change or turn it off; triggered by the user *and* by the system. An agent turn is framed around one focused task, so the feature quietly gets welded to the single flow the request described — an auto-topup setting built as if it only exists inside the "choose topup amount" flow, when updating those settings is its own session with its own entry point. Before building, enumerate the distinct usages and give each a place in the design (the data model and the seams, not necessarily the code); then build only what was asked (§2) and **name the usages you're leaving out** — a variation surfaced is a decision on the table, a variation missed is a discovery in production. + ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** diff --git a/GEMINI.md b/GEMINI.md index b13a59a..f9871c7 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -21,6 +21,8 @@ Before implementing: **Ambiguity check — confirm before you build.** Before committing to anything non-trivial, prove you read it the same way the user meant it: give **three concrete examples of what the result will do — including at least one edge case** — and confirm they're right. Worked examples expose a misread that abstract restating hides; an example that forks into "well, it depends" is a question to resolve now, not a guess to make. Cheap to confirm up front, expensive to discover after you've built the wrong thing. +**Map the usage surface — a feature is more than the flow in the prompt.** The same capability is reached from different entry points, at different moments, by different actors: configured inline mid-flow *and* opened on its own later just to change or turn it off; triggered by the user *and* by the system. An agent turn is framed around one focused task, so the feature quietly gets welded to the single flow the request described — an auto-topup setting built as if it only exists inside the "choose topup amount" flow, when updating those settings is its own session with its own entry point. Before building, enumerate the distinct usages and give each a place in the design (the data model and the seams, not necessarily the code); then build only what was asked (§2) and **name the usages you're leaving out** — a variation surfaced is a decision on the table, a variation missed is a discovery in production. + ## 2. Simplicity First **Minimum code that solves the problem. Nothing speculative.** diff --git a/README.md b/README.md index 2a2acd0..1efca0c 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Seven principles in one file that directly address these issues: | Principle | Addresses | |-----------|-----------| -| **Think Before Coding** | Wrong assumptions, hidden confusion, missing tradeoffs, fence-sitting instead of a recommendation | +| **Think Before Coding** | Wrong assumptions, hidden confusion, missing tradeoffs, fence-sitting instead of a recommendation, features welded to the one flow in the prompt | | **Simplicity First** | Overcomplication, bloated abstractions | | **Surgical Changes** | Orthogonal edits, touching code you shouldn't | | **Goal-Driven Execution** | Leverage through verifiable success criteria | @@ -60,6 +60,7 @@ LLMs often pick an interpretation silently and run with it — or, just as often - **Present multiple interpretations** — Don't pick silently when ambiguity exists - **Have a recommendation** — Once the options are on the table, say which one you'd pick and why; a menu with no opinion is abdication dressed up as balance - **Disagree out loud** — Say the unwelcome thing once, with the reason *and* the alternative, then respect the user's call on judgment matters — but never drop a correctness, security, or data-safety objection to seem agreeable. Challenge, don't obstruct +- **Map the usage surface** — A feature is more than the flow in the prompt: the same capability is set up inline mid-flow *and* opened on its own later to change or disable it. Enumerate the distinct usages and give each a place in the design, build only what was asked, and name the usages you're leaving out - **Stop when confused** — Name what's unclear and ask for clarification ### 2. Simplicity First @@ -189,7 +190,7 @@ Greybeard's two flagship slash commands are **`/pressure-test`** and **`/sidenot ## The `/pressure-test` command -[`commands/pressure-test.md`](./commands/pressure-test.md) is a Claude Code slash command that runs the §5 decision test on demand: pressure-test the approach on the table against **scalable / long-term / efficient** — *whatever is scalable, long term, and cannot be done in a more efficient way* — and get one decisive recommendation, with stale-time-budget shortcuts called out. +[`commands/pressure-test.md`](./commands/pressure-test.md) is a Claude Code slash command that runs the §5 decision test on demand: pressure-test the approach on the table against **scalable / long-term / efficient** — *whatever is scalable, long term, and cannot be done in a more efficient way* — and get one decisive recommendation, with stale-time-budget shortcuts called out. It fans the grounding out to parallel subagents — one per pillar and per load-bearing claim, each gathering its own evidence in a fresh context that can't inherit the session's anchoring bias — then synthesizes the verdicts into one recommendation. No token-thrift shortcuts: this command exists for crucial decisions, and invoking it is the signal that the stakes warrant the fleet. ```bash mkdir -p ~/.claude/commands diff --git a/commands/pressure-test.md b/commands/pressure-test.md index 41ca7a8..6836760 100644 --- a/commands/pressure-test.md +++ b/commands/pressure-test.md @@ -19,6 +19,13 @@ The governing question for the choice: **whatever is scalable, long term, and ca - **But don't optimize away the domain object.** "Reuse the primitive one layer down" is a virtue *until it deletes the thing the feature is actually about*. The trap: fusing a **property the feature requires** (email-binding, single-use, consent) with an **implementation that happens to carry it** (a Supabase magic link, an auth token, a signed URL) — once fused, reuse looks automatically correct, and you end up borrowing an *ephemeral auth artifact* to stand in for a *durable domain record*. Separate the two: name the property, then ask whether the primitive models the property or merely coincides with it today. An auth link is not an invitation; a cache key is not a job; a session is not an audit trail. When the feature needs a **lifecycle** — revoke, resend, expire independently, run several concurrently, record who accepted and when, ask consent before acting — that lifecycle *is* the domain object, and a first-class record (a row + a `requested → active / declined` status) is the correct construct, not gold-plating. Reuse that has no place to hang those states pushes the real cost into fragile edges (24h expiry, single-use collisions, "already registered", silent auto-accept). Adding well-chosen, durable state is sometimes the *efficient* move, not the wasteful one. - **A reused state inherits every behavior already attached to it — enumerate them before you adopt it.** The bullet above warns against reuse that *deletes* the domain object; this is its mirror — reuse that silently *inherits* one. When the approach repurposes an existing status / flag / enum / column to mean something new (`trialing` to mean "currency-migration bridge", `pending` to mean "awaiting review", `archived` to mean "soft-deleted"), it doesn't just carry the one property you wanted — it fires *everything* that already reads that value: webhooks, cron jobs, entitlement gates, billing/credit grants, UI branches, cleanup sweeps. Before committing, **grep every consumer of that value** (`grep -rn 'trialing\|is_trial'` across every layer) and list what each one does with it; a behavior you never intended rides along for free. The tell that you skipped this: you validated the *one* behavior you wanted and discovered the others reactively — one bug (or one "wait, why did all of them get free credits?") at a time. The reused state's full behavior set is part of the decision, not a surprise you pay for after. And when you *do* adopt it, verify by diffing the **whole system's response** (side-effect tables, ledgers, related rows) before/after — not just the fields you predicted would change; the inherited behavior only shows up in the diff you didn't expect. +**Fan out the grounding — one subagent per pillar and per load-bearing claim.** If this harness can spawn subagents (Claude Code's Agent/Task tool), don't run every check inside this context — delegate, in parallel: + +- Give each subagent the decision under test plus the *one* pillar or claim it owns, and instruct it to gather its own evidence — grep the repo, read the actual files, pull current docs — and return a verdict: pass/fail, the first thing that breaks, and the evidence it rests on. Verdicts without evidence don't count. +- **Isolation is the point, parallelism the bonus.** A fresh context has no session priors — it cannot anchor on the subsystem this conversation happens to have been working in, which is exactly the wrong-subsystem trap the sweep bullet above describes. Checks that guard against *this session's* bias (the symptom sweep, the load-bearing claim, per-claim grounding) benefit most from a clean context. +- **Don't economize on the test itself.** This command exists for crucial infrastructure and product decisions — being invoked *is* the signal that the stakes warrant the fleet. Fan out every pillar and every load-bearing claim; the cost of the subagents is noise against the cost of shipping the wrong architecture. Skip the fan-out only where the harness genuinely can't spawn subagents — then run the full test inline, not a lighter one. +- **Synthesize here.** Reconcile the verdicts into ONE recommendation in this context. A verdict you can't trace to its evidence is a claim to re-verify, not a vote to count — and conflicting verdicts mean a pillar wasn't defined concretely enough: define it and re-rule, don't average. + **Define the three pillars for *this* decision — if they're not already clear.** Before judging, make each concrete for the case at hand: - what actually grows (what "scalable" means here — the load / data / users / surface that increases), From 2b3f9929af273e13b45779eae58517b2ebb04f2c Mon Sep 17 00:00:00 2001 From: pallaoro Date: Sat, 22 Aug 2026 18:48:00 +0200 Subject: [PATCH 3/3] refactor(pressure-test): main context is the main brain; subagents are scoped instruments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the per-pillar fan-out: the main context runs the test and owns the ruling, with most of the thinking and token spend staying there. Subagents are spawned only for small scoped checks that benefit from being outside the session — challenging a belief the conversation already holds, or online research / docs verification — never the test wholesale: an agent that only orchestrates stops being the main brain. --- README.md | 2 +- commands/pressure-test.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 1efca0c..f55dfa8 100644 --- a/README.md +++ b/README.md @@ -190,7 +190,7 @@ Greybeard's two flagship slash commands are **`/pressure-test`** and **`/sidenot ## The `/pressure-test` command -[`commands/pressure-test.md`](./commands/pressure-test.md) is a Claude Code slash command that runs the §5 decision test on demand: pressure-test the approach on the table against **scalable / long-term / efficient** — *whatever is scalable, long term, and cannot be done in a more efficient way* — and get one decisive recommendation, with stale-time-budget shortcuts called out. It fans the grounding out to parallel subagents — one per pillar and per load-bearing claim, each gathering its own evidence in a fresh context that can't inherit the session's anchoring bias — then synthesizes the verdicts into one recommendation. No token-thrift shortcuts: this command exists for crucial decisions, and invoking it is the signal that the stakes warrant the fleet. +[`commands/pressure-test.md`](./commands/pressure-test.md) is a Claude Code slash command that runs the §5 decision test on demand: pressure-test the approach on the table against **scalable / long-term / efficient** — *whatever is scalable, long term, and cannot be done in a more efficient way* — and get one decisive recommendation, with stale-time-budget shortcuts called out. The main context runs the test and owns the ruling; subagents are scoped instruments, spawned only where a check benefits from being outside the session — challenging a belief the conversation already holds (a fresh context can't inherit its anchoring), or online research and docs verification that parallelize while the main agent keeps reasoning. Never the test wholesale: a main agent that only orchestrates stops being the main brain. ```bash mkdir -p ~/.claude/commands diff --git a/commands/pressure-test.md b/commands/pressure-test.md index 6836760..17c559b 100644 --- a/commands/pressure-test.md +++ b/commands/pressure-test.md @@ -19,12 +19,12 @@ The governing question for the choice: **whatever is scalable, long term, and ca - **But don't optimize away the domain object.** "Reuse the primitive one layer down" is a virtue *until it deletes the thing the feature is actually about*. The trap: fusing a **property the feature requires** (email-binding, single-use, consent) with an **implementation that happens to carry it** (a Supabase magic link, an auth token, a signed URL) — once fused, reuse looks automatically correct, and you end up borrowing an *ephemeral auth artifact* to stand in for a *durable domain record*. Separate the two: name the property, then ask whether the primitive models the property or merely coincides with it today. An auth link is not an invitation; a cache key is not a job; a session is not an audit trail. When the feature needs a **lifecycle** — revoke, resend, expire independently, run several concurrently, record who accepted and when, ask consent before acting — that lifecycle *is* the domain object, and a first-class record (a row + a `requested → active / declined` status) is the correct construct, not gold-plating. Reuse that has no place to hang those states pushes the real cost into fragile edges (24h expiry, single-use collisions, "already registered", silent auto-accept). Adding well-chosen, durable state is sometimes the *efficient* move, not the wasteful one. - **A reused state inherits every behavior already attached to it — enumerate them before you adopt it.** The bullet above warns against reuse that *deletes* the domain object; this is its mirror — reuse that silently *inherits* one. When the approach repurposes an existing status / flag / enum / column to mean something new (`trialing` to mean "currency-migration bridge", `pending` to mean "awaiting review", `archived` to mean "soft-deleted"), it doesn't just carry the one property you wanted — it fires *everything* that already reads that value: webhooks, cron jobs, entitlement gates, billing/credit grants, UI branches, cleanup sweeps. Before committing, **grep every consumer of that value** (`grep -rn 'trialing\|is_trial'` across every layer) and list what each one does with it; a behavior you never intended rides along for free. The tell that you skipped this: you validated the *one* behavior you wanted and discovered the others reactively — one bug (or one "wait, why did all of them get free credits?") at a time. The reused state's full behavior set is part of the decision, not a surprise you pay for after. And when you *do* adopt it, verify by diffing the **whole system's response** (side-effect tables, ledgers, related rows) before/after — not just the fields you predicted would change; the inherited behavior only shows up in the diff you didn't expect. -**Fan out the grounding — one subagent per pillar and per load-bearing claim.** If this harness can spawn subagents (Claude Code's Agent/Task tool), don't run every check inside this context — delegate, in parallel: +**The main context is the main brain — subagents are scoped instruments, not the test.** Run the test itself here: define the pillars, read the code, weigh the tradeoffs, own the ruling. Most of the thinking — and most of the token spend — belongs in this context. Spawn a subagent (where the harness supports it) only for a small, sharply-scoped check that genuinely benefits from being *outside* this context: -- Give each subagent the decision under test plus the *one* pillar or claim it owns, and instruct it to gather its own evidence — grep the repo, read the actual files, pull current docs — and return a verdict: pass/fail, the first thing that breaks, and the evidence it rests on. Verdicts without evidence don't count. -- **Isolation is the point, parallelism the bonus.** A fresh context has no session priors — it cannot anchor on the subsystem this conversation happens to have been working in, which is exactly the wrong-subsystem trap the sweep bullet above describes. Checks that guard against *this session's* bias (the symptom sweep, the load-bearing claim, per-claim grounding) benefit most from a clean context. -- **Don't economize on the test itself.** This command exists for crucial infrastructure and product decisions — being invoked *is* the signal that the stakes warrant the fleet. Fan out every pillar and every load-bearing claim; the cost of the subagents is noise against the cost of shipping the wrong architecture. Skip the fan-out only where the harness genuinely can't spawn subagents — then run the full test inline, not a lighter one. -- **Synthesize here.** Reconcile the verdicts into ONE recommendation in this context. A verdict you can't trace to its evidence is a claim to re-verify, not a vote to count — and conflicting verdicts mean a pillar wasn't defined concretely enough: define it and re-rule, don't average. +- **Challenging a belief this session already holds.** A load-bearing claim minted in this conversation gets an adversarial check from a fresh context — a clean context cannot inherit the anchoring that produced the belief (the wrong-subsystem trap above). One claim in, refute-or-confirm with evidence out. +- **A different part of the brain.** Online research, current-docs verification, prior-art sweeps — work that is a different *activity* from ruling, and parallelizes cleanly while you keep reasoning here. +- **Evidence, not authority.** A subagent's verdict counts only by the evidence it carries — one you can't trace to its evidence is a claim to re-verify, not a vote to count. +- **Never delegate the test wholesale.** A main agent that fans out every pillar and merely collates becomes a dispatcher — slow, and lazy in the way that matters: no one is actually holding the whole decision. If you catch yourself spawning instead of reasoning, stop and reason. **Define the three pillars for *this* decision — if they're not already clear.** Before judging, make each concrete for the case at hand: