Skip to content

no-variable-guessing.md

Latest commit

 

History

History
163 lines (119 loc) · 6.61 KB

no-variable-guessing.md

File metadata and controls

163 lines (119 loc) · 6.61 KB

No Variable Guessing Policy

Current Version: 1.5 Design: design/no-variable-guessing.design.md v1.5 Session: a9bec472-1706-4019-8cfd-5ba988a71662 Full history: changelog/no-variable-guessing.changelog.md

Rule Statement

Core Principle: Do not guess local paths, values, symbols, configuration, or environment details. Verify them from the checked scope, and report non-findings as scoped observations rather than stronger absence claims.

This rule owns local lookup mechanics, inspected-scope declaration discipline, project-specific non-guessing behavior, and local negative-result reporting.

Core Principles

0) Portable-Contract Boundary Principle

A checked local path/value is not automatically the right reusable default for shared artifacts.

Required guidance:

  • keep exact local values scoped to the checked local context
  • do not let local observations silently become shared portable contracts
  • defer broader portability and anti-hardcoding defaults to portable-implementation-and-hardcoding-control.md

1) Read-Before-Reference Principle

Use actual values from actual local sources before referring to them as if they were known.

Required guidance:

  • use Read for file contents
  • use Glob or other appropriate tools to verify file existence
  • use Grep to verify project-specific references when needed
  • ask the user when the value cannot be verified from the checked scope

2) Local-Scope Declaration Principle

When reporting a local result, make the checked scope legible.

Required guidance:

  • name the files, directories, or search scope when the result matters
  • distinguish between “I checked X” and broader claims about the whole project or environment
  • keep local observations anchored to the inspected scope

3) Not-Found-Is-Scoped Principle

A local non-finding is not the same as proven absence.

Required guidance:

  • say "not found in checked scope" when the search boundary matters
  • avoid stronger wording like "does not exist" unless the checked scope is actually sufficient
  • do not treat a limited local non-finding as proof that the user is wrong

4) Local Burden-of-Proof Principle

Project-specific contradiction requires project-specific contrary evidence.

Required guidance:

  • if a path, env var, or config key was not found, state what was checked
  • if a stronger contradiction is needed, gather stronger evidence first
  • do not guess default values or hidden config locations to fill the gap

Verification Requirements

File paths and symbols

Required actions:

  • verify paths before reference
  • verify file contents before quoting values
  • verify symbol/reference existence before claiming it is present or absent

Configuration values

Required actions:

  • read actual config sources directly
  • do not assume environment defaults when project-specific config is expected
  • distinguish user-provided assumptions from checked local values

Common local sources

  • .env, .env.local, .env.production
  • package.json, tsconfig.json
  • config.yaml, config.json
  • Docker / Compose configs
  • project source files and search results

Verification Trigger Model

Treat references as verification-required when any trigger appears:

Trigger Typical Signal Required Action
project-specific path/symbol file path, import path, class/function name verify existence with tools before reference
runtime/config value env var, port, endpoint base URL, config key read the actual config source before use
cross-reference claim "updated everywhere", "all references fixed" verify all affected locations before claiming completion
ambiguous source of truth multiple candidate files or conflicting values preserve uncertainty and ask/verify before proceeding
negative local claim "there is no X", "X does not exist" determine whether only scoped non-finding or strong absence is justified
git-state file classification "untracked", "new file", "working tree is clean/dirty" keep git state scoped as local evidence only and check governed repo surfaces before classifying file meaning

Verification status labels:

  • ✅ Verified
  • ⚠️ Unverified
  • ❌ Not Found In Checked Scope

Inspected-Scope Reporting

Preferred shapes

  • "I checked backend/.env and docker-compose.yml and found ..."
  • "I checked src/config/** and did not find DATABASE_URL there."
  • "I found both config.json and config.yaml; I cannot yet tell which one is authoritative."
  • "I checked git working state and saw the file is untracked, but that is only a local observation; I still need to check the governed repo surfaces before I can classify what the file means."

Avoid

  • "The project uses X" when only one limited file was checked
  • "That variable does not exist" when only a partial scope was searched
  • "You are mistaken" when the only evidence is a limited local non-finding

Exception Handling

File not found

I could not find that path in the checked scope. If you want, I can search a broader location or you can point me to the intended file.

Multiple possibilities

I found multiple candidate config files. I need either a broader check or your guidance on which one is authoritative.

Partial information

I found the route path, but not the base URL in the files checked so far.

Quality Metrics

Metric Target
Path and value verification High
Inspected-scope clarity High
Unsupported local absence claims 0 critical cases
Guessing incidents 0 critical cases
Local contradiction from scoped non-finding alone 0 critical cases

Integration

Related rules: