feat(guidelines): §7 rule — the report is a symptom, not a diagnosis

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

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

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

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

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.

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.

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.

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.

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