Skip to content

document-consistency.md

Latest commit

 

History

History
162 lines (129 loc) · 7.06 KB

document-consistency.md

File metadata and controls

162 lines (129 loc) · 7.06 KB

Document Consistency and Cross-Reference Validation

Current Version: 1.7 Design: design/document-consistency.design.md v1.7 Session: a9bec472-1706-4019-8cfd-5ba988a71662 Full history: changelog/document-consistency.changelog.md

Rule Statement

Core Principle: Keep names, paths, identifiers, and cross-references consistent across the checked scope, while clearly separating portable shared references, source-side references, destination/runtime references, checked local facts, and machine-scoped examples.

This rule governs cross-reference consistency, change-propagation discipline, and reference verification across files, sections, symbols, commands, and configuration values.

Core Rules

1) Consistency Requirements

  • keep names, paths, identifiers, and references consistent across the whole response
  • when referencing, ensure it exists or mark it as unknown or unverified
  • if a change impacts multiple sections/files, describe or update the dependencies
  • keep portable shared references distinct from checked local facts or machine-scoped examples
  • keep source-side references distinct from destination/runtime references when both appear in install or onboarding guidance
  • keep local execution paths used only for tool/runtime operation distinct from reusable source-artifact references so tool-local paths do not silently become skill/plugin/source contracts
  • defer broader portable-default and anti-hardcoding ownership to portable-implementation-and-hardcoding-control.md

2) Reference Types

Type Example Verification Method
File paths <workspace-root>/src/config.js for portable examples, or exact path only when scoped as a checked local fact Glob / LS / Read
Source-side install path <repo-root> or ./ when a command is run from the repo root Read / command-context verification
Destination/runtime path <install-root>/skills or <user-runtime-rules> Read config/source contract when applicable
Local execution path exact tool/runtime path used only for the current machine or harness turn Read / execution context
Symbols getUserById Grep
Commands npm run build Test execution when needed
Config DATABASE_URL Read config source

3) Shared Verification Trigger Model

Apply verification before finalizing references or consistency claims when triggers are present:

Trigger Typical Signal Required Action
Concrete reference file path, symbol, command, config key/value verify existence/validity with tools before asserting
Cross-file consistency claim "fully synchronized", "all references updated", "no drift" verify all impacted files/sections before confirming
Rename/move/update impact path or identifier changed in one place trace and update dependent references deterministically
Ambiguous or unresolved reference missing file/symbol or uncertain mapping mark status explicitly and avoid unstated assumptions
Mixed source/destination wording install docs blur clone/source path with installed/runtime path separate the reference roles explicitly and normalize wording
Tool-path leakage into reusable source a local tool/runtime path is copied into skill/plugin/source content as if it were a shared contract relabel it as local execution context or replace it with a portable placeholder / runtime variable
Disposal or junk classification file may still be referenced by governed repo surfaces check master surfaces and dependent references before classifying the file as cleanup noise

Implementation

Verification Flow

Create reference
  ↓
Does it exist or resolve?
  → YES: use precise reference
  → NO: mark as unknown/unverified
  ↓
What reference role is it?
  → portable shared reference
  → source-side reference
  → destination/runtime reference
  → checked local fact
  → machine-scoped example
  ↓
Is it consistent with related references?
  → YES: continue
  → NO: fix inconsistency

Change Impact Analysis

Making a change
  ↓
Identify all affected references
  ↓
List dependencies
  ↓
Update all references
  ↓
Verify consistency

Output Standards

Preferred references

  • file paths: <workspace-root>/src/config.js for portable examples, or an exact path only when explicitly scoped as a checked local fact
  • source-side install guidance: <repo-root> or ./ when the command is explicitly intended for the repo root
  • destination/runtime guidance: <install-root>, <user-runtime-rules>, <user-runtime-skills>, <user-runtime-agents>
  • line numbers: config.js:42
  • symbols: getUserById() function in user.service.ts

Avoid

  • "The config file"
  • "That function we created earlier"
  • "The variable somewhere in the code"
  • one exact workstation path acting as both the source path and the destination/runtime path without explanation

Verification labels

✅ Verified: `<workspace-root>/src/config.js` (portable example) or exact checked local path when scoped
⚠️ Unverified: `api.endpoint.url` (not checked)
❌ Not Found: `/missing/file.js`

Cross-Section Validation

When modifying:

  1. scan the entire document or checked scope for related references
  2. identify all cross-section or cross-file dependencies
  3. update affected sections deterministically
  4. verify consistency throughout

When classifying a newly encountered file as junk/disposable/non-governed:

  1. scan the master repo surfaces that could assign governed meaning
  2. identify whether dependent references or history entries already explain the file
  3. keep the classification unresolved if the checked scope is still incomplete
  4. do not treat missing immediate recognition as disposal proof
Change Type Required Actions
Rename file update all imports/references
Move file update all paths
Rename symbol update all usages
Change config update all references
Normalize install docs update source-side references and destination/runtime references separately

Quality Metrics

Metric Target
Naming consistency 100%
Reference verification High
Dependency updates 100%
Reference precision 100%
Portable-vs-local reference separation High
Source-vs-destination reference separation High

Integration

Related rules: