From b5460d2623bb8b361631c739875d0aff54c8d64d Mon Sep 17 00:00:00 2001 From: pallaoro Date: Thu, 9 Jul 2026 23:46:26 +0200 Subject: [PATCH] =?UTF-8?q?guidelines:=20verify=20the=20invocation=20contr?= =?UTF-8?q?act=20+=20"compiles=20=E2=89=A0=20works"=20(=C2=A77,=20=C2=A74)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two checks that close a common gap: verifying a change's *behavior* while assuming its *invocation*. A feature can shell out to a command with flags lifted from the wrong docs section, or ship behind a self-written "deployed but never exercised" caveat, and still pass a green build — a wrong flag, dead endpoint, or mis-set env var is invisible to compile/typecheck/deploy. - §7: verify the invocation contract (exact flags/params/env, arg order) against the primary source — the command's own option definition, the API schema — not prose docs or a sibling example. The mundane call detail is most likely wrong and least likely checked, precisely because it feels beneath verifying. - §4: "compiles/typechecks/deploys" is not "it works" — run it once against the real target; a self-flagged "unverified" caveat on a load-bearing path is a gate, not a footnote, and the bar scales with blast radius. Regenerated fan-out copies via scripts/build-rules.js (--check clean). --- .clinerules/karpathy-skills.md | 3 +++ .cursor/rules/karpathy-skills.mdc | 3 +++ .github/copilot-instructions.md | 3 +++ .windsurf/rules/karpathy-skills.md | 3 +++ AGENTS.md | 3 +++ CLAUDE.md | 3 +++ GEMINI.md | 3 +++ 7 files changed, 21 insertions(+) diff --git a/.clinerules/karpathy-skills.md b/.clinerules/karpathy-skills.md index 0b74bd0..50081c8 100644 --- a/.clinerules/karpathy-skills.md +++ b/.clinerules/karpathy-skills.md @@ -66,6 +66,8 @@ For multi-step tasks, state a brief plan: Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +**"It compiles / typechecks / deploys" is not "it works."** For anything that shells out or calls an external system, done includes running it once against the real target and watching it behave — a green build catches a syntax slip, never a wrong flag, a dead endpoint, or a mis-set env var. And a caveat you write about your *own* work — "not yet tested against the real API", "deployed but never exercised" — is an unmet success criterion, not a footnote: don't let it past a blast radius (prod, a fleet, someone else's data) until it's resolved. The bigger the blast radius, the lower the bar for *actually running it* over *reasoning about it*. + ## 5. Recalibrate Time Estimates **"Weeks of work" in pre-AI terms is often 1–2 hours now. Don't cut corners on something you can actually finish this session.** @@ -117,6 +119,7 @@ Your priors are a starting hypothesis, not the answer. The most expensive mistak - 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. - **Read this codebase, don't infer it.** Before editing, read the actual code, types, and tests the change touches, and trace the real flow end to end. How it works *here* beats how it works *in general*. - **Reuse before you build — look down the stack, not just sideways.** Before adding any new state — config keys, DB columns, env vars, endpoints, files, abstractions — search the framework / platform / library you build on, *and* the rest of this repo, for a primitive that already models the concern. "The code this touches" is too narrow: the answer often lives one layer down, adjacent to the change, not in it. Reinventing what the host already exposes is the single most common efficiency miss. Verify the primitive against the dependency's actual source, not its docs alone. +- **Verify the invocation contract, not just the behavior.** When your change emits something a machine will run — a command line, an API call, a query, a config — confirming *what it does* is not confirming *how it's called*. Check the exact signature (flag names, params, arg order, whether auth is a `--flag` or an env var) against the **primary source**: the command's own option definition, the API's schema, the function's real signature — not prose docs, and not a nearby example. Reference docs group by topic and quietly invite you to cross-apply a sibling command's flags onto yours; the sample that "looks right" is how a wrong flag ships. That mundane call detail is the part most likely wrong *and* least likely checked — precisely because it feels beneath verifying — and it is often what decides whether the thing runs at all. - **Map before you move.** For non-trivial work, get the overview first: where this lives, what calls it and what it calls, the data and infrastructure boundaries it crosses. A change that's locally correct but wrong about the architecture is a new bug. - **When you can't verify, say so.** Flag it as an assumption and state how you'd confirm — never launder a guess into a claim. diff --git a/.cursor/rules/karpathy-skills.mdc b/.cursor/rules/karpathy-skills.mdc index 314d5c2..124a478 100644 --- a/.cursor/rules/karpathy-skills.mdc +++ b/.cursor/rules/karpathy-skills.mdc @@ -72,6 +72,8 @@ For multi-step tasks, state a brief plan: Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +**"It compiles / typechecks / deploys" is not "it works."** For anything that shells out or calls an external system, done includes running it once against the real target and watching it behave — a green build catches a syntax slip, never a wrong flag, a dead endpoint, or a mis-set env var. And a caveat you write about your *own* work — "not yet tested against the real API", "deployed but never exercised" — is an unmet success criterion, not a footnote: don't let it past a blast radius (prod, a fleet, someone else's data) until it's resolved. The bigger the blast radius, the lower the bar for *actually running it* over *reasoning about it*. + ## 5. Recalibrate Time Estimates **"Weeks of work" in pre-AI terms is often 1–2 hours now. Don't cut corners on something you can actually finish this session.** @@ -123,6 +125,7 @@ Your priors are a starting hypothesis, not the answer. The most expensive mistak - 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. - **Read this codebase, don't infer it.** Before editing, read the actual code, types, and tests the change touches, and trace the real flow end to end. How it works *here* beats how it works *in general*. - **Reuse before you build — look down the stack, not just sideways.** Before adding any new state — config keys, DB columns, env vars, endpoints, files, abstractions — search the framework / platform / library you build on, *and* the rest of this repo, for a primitive that already models the concern. "The code this touches" is too narrow: the answer often lives one layer down, adjacent to the change, not in it. Reinventing what the host already exposes is the single most common efficiency miss. Verify the primitive against the dependency's actual source, not its docs alone. +- **Verify the invocation contract, not just the behavior.** When your change emits something a machine will run — a command line, an API call, a query, a config — confirming *what it does* is not confirming *how it's called*. Check the exact signature (flag names, params, arg order, whether auth is a `--flag` or an env var) against the **primary source**: the command's own option definition, the API's schema, the function's real signature — not prose docs, and not a nearby example. Reference docs group by topic and quietly invite you to cross-apply a sibling command's flags onto yours; the sample that "looks right" is how a wrong flag ships. That mundane call detail is the part most likely wrong *and* least likely checked — precisely because it feels beneath verifying — and it is often what decides whether the thing runs at all. - **Map before you move.** For non-trivial work, get the overview first: where this lives, what calls it and what it calls, the data and infrastructure boundaries it crosses. A change that's locally correct but wrong about the architecture is a new bug. - **When you can't verify, say so.** Flag it as an assumption and state how you'd confirm — never launder a guess into a claim. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0b74bd0..50081c8 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -66,6 +66,8 @@ For multi-step tasks, state a brief plan: Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +**"It compiles / typechecks / deploys" is not "it works."** For anything that shells out or calls an external system, done includes running it once against the real target and watching it behave — a green build catches a syntax slip, never a wrong flag, a dead endpoint, or a mis-set env var. And a caveat you write about your *own* work — "not yet tested against the real API", "deployed but never exercised" — is an unmet success criterion, not a footnote: don't let it past a blast radius (prod, a fleet, someone else's data) until it's resolved. The bigger the blast radius, the lower the bar for *actually running it* over *reasoning about it*. + ## 5. Recalibrate Time Estimates **"Weeks of work" in pre-AI terms is often 1–2 hours now. Don't cut corners on something you can actually finish this session.** @@ -117,6 +119,7 @@ Your priors are a starting hypothesis, not the answer. The most expensive mistak - 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. - **Read this codebase, don't infer it.** Before editing, read the actual code, types, and tests the change touches, and trace the real flow end to end. How it works *here* beats how it works *in general*. - **Reuse before you build — look down the stack, not just sideways.** Before adding any new state — config keys, DB columns, env vars, endpoints, files, abstractions — search the framework / platform / library you build on, *and* the rest of this repo, for a primitive that already models the concern. "The code this touches" is too narrow: the answer often lives one layer down, adjacent to the change, not in it. Reinventing what the host already exposes is the single most common efficiency miss. Verify the primitive against the dependency's actual source, not its docs alone. +- **Verify the invocation contract, not just the behavior.** When your change emits something a machine will run — a command line, an API call, a query, a config — confirming *what it does* is not confirming *how it's called*. Check the exact signature (flag names, params, arg order, whether auth is a `--flag` or an env var) against the **primary source**: the command's own option definition, the API's schema, the function's real signature — not prose docs, and not a nearby example. Reference docs group by topic and quietly invite you to cross-apply a sibling command's flags onto yours; the sample that "looks right" is how a wrong flag ships. That mundane call detail is the part most likely wrong *and* least likely checked — precisely because it feels beneath verifying — and it is often what decides whether the thing runs at all. - **Map before you move.** For non-trivial work, get the overview first: where this lives, what calls it and what it calls, the data and infrastructure boundaries it crosses. A change that's locally correct but wrong about the architecture is a new bug. - **When you can't verify, say so.** Flag it as an assumption and state how you'd confirm — never launder a guess into a claim. diff --git a/.windsurf/rules/karpathy-skills.md b/.windsurf/rules/karpathy-skills.md index 0b74bd0..50081c8 100644 --- a/.windsurf/rules/karpathy-skills.md +++ b/.windsurf/rules/karpathy-skills.md @@ -66,6 +66,8 @@ For multi-step tasks, state a brief plan: Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +**"It compiles / typechecks / deploys" is not "it works."** For anything that shells out or calls an external system, done includes running it once against the real target and watching it behave — a green build catches a syntax slip, never a wrong flag, a dead endpoint, or a mis-set env var. And a caveat you write about your *own* work — "not yet tested against the real API", "deployed but never exercised" — is an unmet success criterion, not a footnote: don't let it past a blast radius (prod, a fleet, someone else's data) until it's resolved. The bigger the blast radius, the lower the bar for *actually running it* over *reasoning about it*. + ## 5. Recalibrate Time Estimates **"Weeks of work" in pre-AI terms is often 1–2 hours now. Don't cut corners on something you can actually finish this session.** @@ -117,6 +119,7 @@ Your priors are a starting hypothesis, not the answer. The most expensive mistak - 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. - **Read this codebase, don't infer it.** Before editing, read the actual code, types, and tests the change touches, and trace the real flow end to end. How it works *here* beats how it works *in general*. - **Reuse before you build — look down the stack, not just sideways.** Before adding any new state — config keys, DB columns, env vars, endpoints, files, abstractions — search the framework / platform / library you build on, *and* the rest of this repo, for a primitive that already models the concern. "The code this touches" is too narrow: the answer often lives one layer down, adjacent to the change, not in it. Reinventing what the host already exposes is the single most common efficiency miss. Verify the primitive against the dependency's actual source, not its docs alone. +- **Verify the invocation contract, not just the behavior.** When your change emits something a machine will run — a command line, an API call, a query, a config — confirming *what it does* is not confirming *how it's called*. Check the exact signature (flag names, params, arg order, whether auth is a `--flag` or an env var) against the **primary source**: the command's own option definition, the API's schema, the function's real signature — not prose docs, and not a nearby example. Reference docs group by topic and quietly invite you to cross-apply a sibling command's flags onto yours; the sample that "looks right" is how a wrong flag ships. That mundane call detail is the part most likely wrong *and* least likely checked — precisely because it feels beneath verifying — and it is often what decides whether the thing runs at all. - **Map before you move.** For non-trivial work, get the overview first: where this lives, what calls it and what it calls, the data and infrastructure boundaries it crosses. A change that's locally correct but wrong about the architecture is a new bug. - **When you can't verify, say so.** Flag it as an assumption and state how you'd confirm — never launder a guess into a claim. diff --git a/AGENTS.md b/AGENTS.md index 0b74bd0..50081c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,6 +66,8 @@ For multi-step tasks, state a brief plan: Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +**"It compiles / typechecks / deploys" is not "it works."** For anything that shells out or calls an external system, done includes running it once against the real target and watching it behave — a green build catches a syntax slip, never a wrong flag, a dead endpoint, or a mis-set env var. And a caveat you write about your *own* work — "not yet tested against the real API", "deployed but never exercised" — is an unmet success criterion, not a footnote: don't let it past a blast radius (prod, a fleet, someone else's data) until it's resolved. The bigger the blast radius, the lower the bar for *actually running it* over *reasoning about it*. + ## 5. Recalibrate Time Estimates **"Weeks of work" in pre-AI terms is often 1–2 hours now. Don't cut corners on something you can actually finish this session.** @@ -117,6 +119,7 @@ Your priors are a starting hypothesis, not the answer. The most expensive mistak - 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. - **Read this codebase, don't infer it.** Before editing, read the actual code, types, and tests the change touches, and trace the real flow end to end. How it works *here* beats how it works *in general*. - **Reuse before you build — look down the stack, not just sideways.** Before adding any new state — config keys, DB columns, env vars, endpoints, files, abstractions — search the framework / platform / library you build on, *and* the rest of this repo, for a primitive that already models the concern. "The code this touches" is too narrow: the answer often lives one layer down, adjacent to the change, not in it. Reinventing what the host already exposes is the single most common efficiency miss. Verify the primitive against the dependency's actual source, not its docs alone. +- **Verify the invocation contract, not just the behavior.** When your change emits something a machine will run — a command line, an API call, a query, a config — confirming *what it does* is not confirming *how it's called*. Check the exact signature (flag names, params, arg order, whether auth is a `--flag` or an env var) against the **primary source**: the command's own option definition, the API's schema, the function's real signature — not prose docs, and not a nearby example. Reference docs group by topic and quietly invite you to cross-apply a sibling command's flags onto yours; the sample that "looks right" is how a wrong flag ships. That mundane call detail is the part most likely wrong *and* least likely checked — precisely because it feels beneath verifying — and it is often what decides whether the thing runs at all. - **Map before you move.** For non-trivial work, get the overview first: where this lives, what calls it and what it calls, the data and infrastructure boundaries it crosses. A change that's locally correct but wrong about the architecture is a new bug. - **When you can't verify, say so.** Flag it as an assumption and state how you'd confirm — never launder a guess into a claim. diff --git a/CLAUDE.md b/CLAUDE.md index 20303fa..c2fd630 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -64,6 +64,8 @@ For multi-step tasks, state a brief plan: Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +**"It compiles / typechecks / deploys" is not "it works."** For anything that shells out or calls an external system, done includes running it once against the real target and watching it behave — a green build catches a syntax slip, never a wrong flag, a dead endpoint, or a mis-set env var. And a caveat you write about your *own* work — "not yet tested against the real API", "deployed but never exercised" — is an unmet success criterion, not a footnote: don't let it past a blast radius (prod, a fleet, someone else's data) until it's resolved. The bigger the blast radius, the lower the bar for *actually running it* over *reasoning about it*. + ## 5. Recalibrate Time Estimates **"Weeks of work" in pre-AI terms is often 1–2 hours now. Don't cut corners on something you can actually finish this session.** @@ -115,6 +117,7 @@ Your priors are a starting hypothesis, not the answer. The most expensive mistak - 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. - **Read this codebase, don't infer it.** Before editing, read the actual code, types, and tests the change touches, and trace the real flow end to end. How it works *here* beats how it works *in general*. - **Reuse before you build — look down the stack, not just sideways.** Before adding any new state — config keys, DB columns, env vars, endpoints, files, abstractions — search the framework / platform / library you build on, *and* the rest of this repo, for a primitive that already models the concern. "The code this touches" is too narrow: the answer often lives one layer down, adjacent to the change, not in it. Reinventing what the host already exposes is the single most common efficiency miss. Verify the primitive against the dependency's actual source, not its docs alone. +- **Verify the invocation contract, not just the behavior.** When your change emits something a machine will run — a command line, an API call, a query, a config — confirming *what it does* is not confirming *how it's called*. Check the exact signature (flag names, params, arg order, whether auth is a `--flag` or an env var) against the **primary source**: the command's own option definition, the API's schema, the function's real signature — not prose docs, and not a nearby example. Reference docs group by topic and quietly invite you to cross-apply a sibling command's flags onto yours; the sample that "looks right" is how a wrong flag ships. That mundane call detail is the part most likely wrong *and* least likely checked — precisely because it feels beneath verifying — and it is often what decides whether the thing runs at all. - **Map before you move.** For non-trivial work, get the overview first: where this lives, what calls it and what it calls, the data and infrastructure boundaries it crosses. A change that's locally correct but wrong about the architecture is a new bug. - **When you can't verify, say so.** Flag it as an assumption and state how you'd confirm — never launder a guess into a claim. diff --git a/GEMINI.md b/GEMINI.md index 0b74bd0..50081c8 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -66,6 +66,8 @@ For multi-step tasks, state a brief plan: Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. +**"It compiles / typechecks / deploys" is not "it works."** For anything that shells out or calls an external system, done includes running it once against the real target and watching it behave — a green build catches a syntax slip, never a wrong flag, a dead endpoint, or a mis-set env var. And a caveat you write about your *own* work — "not yet tested against the real API", "deployed but never exercised" — is an unmet success criterion, not a footnote: don't let it past a blast radius (prod, a fleet, someone else's data) until it's resolved. The bigger the blast radius, the lower the bar for *actually running it* over *reasoning about it*. + ## 5. Recalibrate Time Estimates **"Weeks of work" in pre-AI terms is often 1–2 hours now. Don't cut corners on something you can actually finish this session.** @@ -117,6 +119,7 @@ Your priors are a starting hypothesis, not the answer. The most expensive mistak - 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. - **Read this codebase, don't infer it.** Before editing, read the actual code, types, and tests the change touches, and trace the real flow end to end. How it works *here* beats how it works *in general*. - **Reuse before you build — look down the stack, not just sideways.** Before adding any new state — config keys, DB columns, env vars, endpoints, files, abstractions — search the framework / platform / library you build on, *and* the rest of this repo, for a primitive that already models the concern. "The code this touches" is too narrow: the answer often lives one layer down, adjacent to the change, not in it. Reinventing what the host already exposes is the single most common efficiency miss. Verify the primitive against the dependency's actual source, not its docs alone. +- **Verify the invocation contract, not just the behavior.** When your change emits something a machine will run — a command line, an API call, a query, a config — confirming *what it does* is not confirming *how it's called*. Check the exact signature (flag names, params, arg order, whether auth is a `--flag` or an env var) against the **primary source**: the command's own option definition, the API's schema, the function's real signature — not prose docs, and not a nearby example. Reference docs group by topic and quietly invite you to cross-apply a sibling command's flags onto yours; the sample that "looks right" is how a wrong flag ships. That mundane call detail is the part most likely wrong *and* least likely checked — precisely because it feels beneath verifying — and it is often what decides whether the thing runs at all. - **Map before you move.** For non-trivial work, get the overview first: where this lives, what calls it and what it calls, the data and infrastructure boundaries it crosses. A change that's locally correct but wrong about the architecture is a new bug. - **When you can't verify, say so.** Flag it as an assumption and state how you'd confirm — never launder a guess into a claim.