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),