guidelines: verify the invocation contract + "compiles ≠ works" (§7, §4)

.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.
 

.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.
 

.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.
 

.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.
 

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.