Contents
1. Why This Exists
Not all code is equal. A function that has rendered prices correctly for 66 products across thousands of page loads is not the same as a function written ten minutes ago. They require fundamentally different levels of caution.
The failures that created this protocol all followed the same pattern:
- A bug exists in one specific place
- A broad edit (
replace_all, sweeping refactor, "while I'm in here" cleanup) touches code far beyond the bug - The broad edit breaks something that was working perfectly
- The breakage isn't discovered until the user encounters it in a different part of the system
- Now there are two bugs instead of one, and trust is damaged
This protocol prevents step 2 by making the stability and role of every code block visible. When you can see that a block is GREEN and impacts all product pricing, you don't run replace_all through it to fix an unrelated issue.
Companion to Doc 19: The Troubleshooting Protocol (Doc 19) governs how to diagnose and fix bugs. This document governs how to understand what you're looking at and what's at stake before you touch it. Read both before making any code change to fix a problem.
2. The Three Confidence Levels
GREEN Proven
Code that is production-tested, confirmed working, and touches critical functionality. Changing it has a high probability of breaking something important.
Qualifies as GREEN when:
- Has been deployed to production and confirmed working by the user or by verified output
- Handles critical features: price display, cart operations, checkout, authentication, data rendering, API responses
- Has survived at least one real-world usage cycle without issues
- Is the correct implementation of a known data flow (e.g., reads
retail_price_centsfrom the API, which is verified to return that field)
Examples:
- Price rendering logic in
shop.htmlandproduct.php - Cart add/remove/total calculations in
cart.js - API queries with verified
SELECTcolumns andCOALESCEfallbacks - Auth session validation in
portal-auth.php - Product data generator (
generate-products-js.php) field mapping - Deploy column mapping after schema verification
YELLOW Moderate
Code that is functional but either less battle-tested, handles non-critical features, or has known limitations that may require future changes.
Qualifies as YELLOW when:
- Works correctly but hasn't been extensively tested in production
- Handles supporting features: sorting, filtering, search, UI cosmetics, admin display
- Recently written and working, but hasn't proven itself over time
- Has a known dependency on external state that could change (e.g., a specific DB schema version)
Examples:
- Brand card rendering and category pill filtering in
shop.html - Sort functions (price low/high, name A-Z)
- Admin dashboard tab content and layout
- Feed generation formatting
- Sync health check display logic
RED Unproven
Code that is new, recently changed, not yet verified in production, or known to have issues. Expected to need iteration.
Qualifies as RED when:
- Just written and not yet deployed or tested in production
- Recently modified to fix a bug — the fix itself is unproven until confirmed
- Part of a feature that is still under active development
- Known to have edge cases, incomplete error handling, or TODO items
Examples:
- Any code written in the current session that hasn't been deployed and verified
- New API endpoints before first successful production call
- Migration SQL before execution
- Features behind flags or in staging
3. Rules of Engagement by Level
Each confidence level has specific rules governing how code at that level may be modified. These are not suggestions.
| Rule | GREEN | YELLOW | RED |
|---|---|---|---|
| Can you edit it? | Only if it is the verified, direct source of the bug | Yes, with standard caution | Yes, freely — this is expected to change |
Can you use replace_all? |
No. Surgical, targeted edits only. | Only after verifying all occurrences | Yes, with a quick check |
| Can you delete code? | No unless the code is confirmed dead/unreachable | If you understand what it does and why it's there | Yes |
| Can you refactor it? | No. Do not refactor working critical code. | If directly related to the current task | Yes |
| "While I'm in here" changes? | Absolutely not. | No — stay focused on the task | Use judgment |
| Pre-edit requirement | Complete Doc 19 diagnostic sequence. State in one sentence why THIS block must change. | Understand what the code does and what calls it | Basic reading of the code |
| Post-edit requirement | Verify the specific change. Test the exact feature it impacts. Confirm no collateral damage. | Quick verification of the change | Standard testing |
The GREEN rule in one sentence: If the code is GREEN, you do not touch it unless you can prove it is the direct cause of the bug, and your edit is the minimum change required to fix it. Nothing more.
4. Blast Radius Mapping
Every code block has a blast radius — the scope of what breaks if that code is changed incorrectly. This must be understood before editing.
Blast Radius Categories
| Radius | Label | Definition | Example |
|---|---|---|---|
| Critical | Site-wide impact | Breaking this affects every page or every product on the site | Price rendering in shop.html, components.js header/footer, API config.php |
| Feature | One feature affected | Breaking this disables a specific feature but doesn't take down the site | Cart logic, variant selectors, search autocomplete, sort/filter |
| Page | One page affected | Breaking this affects only a single page | Contact form, about page, single admin tab |
| Cosmetic | Visual only | Breaking this causes a visual issue but functionality is intact | Badge colors, spacing, font weights, hover effects |
Confidence + Blast Radius = Risk Level
The combination determines how carefully you must treat a code block:
| Critical Blast | Feature Blast | Page Blast | Cosmetic Blast | |
|---|---|---|---|---|
| GREEN | HIGHEST RISK — Do not touch without full diagnostic | High risk — surgical only | Moderate risk | Low risk |
| YELLOW | High risk | Moderate risk | Normal caution | Low risk |
| RED | Moderate risk — test thoroughly | Normal caution | Free to iterate | Free to iterate |
5. The Inline Annotation Format
Inline annotations are placed directly in source code so they are visible at the exact moment of editing. They use a structured comment format that identifies confidence level, role, data source, and blast radius.
Standard Format
/* ----------------------------------------------------------------
* @confidence GREEN
* @role Price rendering for product cards
* @datasource public-products.php API → field: retail_price_cents
* @blast Critical — affects ALL product prices on shop page
* @verified 2026-03-11 — 66 products confirmed showing correct prices
* ---------------------------------------------------------------- */
Required Fields
| Field | Purpose | Example Values |
|---|---|---|
@confidence |
The confidence level | GREEN, YELLOW, RED |
@role |
What this code block does in plain language | "Price rendering for product cards", "Cart quantity calculation", "Session validation" |
@datasource |
Where this code gets its data — the specific file AND field names | "public-products.php API → retail_price_cents", "products-data.js → priceCents" |
@blast |
What breaks if this code is changed incorrectly | "Critical — all prices", "Feature — cart totals", "Page — admin sync tab" |
@verified |
Date last confirmed working, with evidence | "2026-03-11 — 66 products confirmed", "2026-03-08 — checkout tested" |
Placement Rules
- Place annotations directly above the code block they describe. Not at the top of the file — above the specific function, block, or logic section.
- One annotation per logical block. A file may have multiple annotations at different confidence levels.
- Keep annotations tight. 3–6 lines. The annotation is a signal, not documentation.
Annotation Examples by Language
JavaScript / HTML inline scripts
/* @confidence GREEN | @role Price display | @datasource public-products.php → retail_price_cents
* @blast Critical — ALL product prices | @verified 2026-03-11 */
const price = p.price_type === 'contact' ? 'Contact for Price'
: p.price_type === 'quoted' ? 'Request Quote'
: p.retail_price_cents ? formatPrice(p.retail_price_cents) : 'Contact for Price';
PHP
/* @confidence GREEN | @role COALESCE price fallback for public API
* @blast Critical — all product prices in API responses | @verified 2026-03-11 */
$stmt = $db->prepare("
SELECT p.id, p.slug, p.name,
COALESCE(p.retail_price_cents, p.price_cents) AS retail_price_cents,
p.price_type
FROM {$sp}products p WHERE p.public_listed = 1
");
Compact Format (for tight spaces)
/* @confidence GREEN | @blast Critical — all prices | @datasource API:retail_price_cents */
: p.retail_price_cents ? formatPrice(p.retail_price_cents) : 'Contact for Price';
What NOT to Annotate
- CSS styling (unless it's a layout-critical responsive breakpoint)
- HTML structure that has no logic
- Comments, whitespace, import statements
- Code that is obviously RED (just written, not yet deployed) — annotate it when it graduates to YELLOW or GREEN
6. The Confidence Registry
Each site has a CODE-CONFIDENCE.md file in its root directory. This is the master map of all annotated code blocks, organized by file. It serves as a pre-edit reference — check the registry before opening a file to edit.
Registry Format
# Code Confidence Registry — The High Road Manufacturing
# Last updated: 2026-03-11
## shop.html
| Block | Level | Role | Data Source | Blast Radius |
|-------|-------|------|-------------|--------------|
| renderCard() price | GREEN | Price display in product cards | API: retail_price_cents | Critical — all prices |
| loadProducts() | GREEN | Fetches product list from API | public-products.php | Critical — entire shop grid |
| filterProducts() | GREEN | Brand/category/search filtering | In-memory from API response | Feature — filtering |
| buildBrandCards() | YELLOW | Brand filter card rendering | In-memory from API brands[] | Feature — brand nav |
| sort switch | YELLOW | Price/name sorting | In-memory, uses retail_price_cents | Feature — sort order |
## product.php
| Block | Level | Role | Data Source | Blast Radius |
|-------|-------|------|-------------|--------------|
| renderProduct() price | GREEN | Main product price display | API: retail_price_cents | Critical — product price |
| addToCart() | GREEN | Cart add with variant support | API data + variant selectors | Feature — cart |
| getProductVariants() | GREEN | Variant data from PRODUCTS array | products-data.js: priceCents | Feature — variants |
| renderVariants() | GREEN | Variant selector HTML generation | products-data.js: PRODUCTS | Feature — variants |
| schema.org JSON-LD | GREEN | Structured data for SEO | API: retail_price_cents | SEO — rich results |
| related products | YELLOW | Related product cards | API: p.related[] | Feature — recommendations |
Registry Rules
- One registry per site — stored at the site root (e.g.,
thehighroad/CODE-CONFIDENCE.md) - Check it before editing any file listed in it. If a file appears in the registry, read the entry before making changes.
- Update it after making changes. If you change a GREEN block, note what changed and re-verify. If you add new code that works, add it to the registry.
- The registry and inline annotations must agree. If they conflict, the inline annotation takes precedence (it's closer to the code).
7. How Confidence Levels Change
Confidence levels are not permanent. Code moves between levels as it proves itself or gets modified.
Promotion Path: RED → YELLOW → GREEN
| Transition | Trigger | Evidence Required |
|---|---|---|
| RED → YELLOW | Code deployed to production and working | Successful deploy + page loads correctly + no errors reported |
| YELLOW → GREEN | Code proven through real-world use | User has used the feature, confirmed correct output, or feature has operated correctly over multiple sessions. Critical-path code requires explicit verification (e.g., all 66 products show prices). |
Demotion Path: GREEN → YELLOW → RED
| Transition | Trigger | What Happens |
|---|---|---|
| GREEN → YELLOW | Code was modified (even a small change) | Any edit to a GREEN block demotes it to YELLOW until re-verified. The code may still work, but the modification means it's no longer the exact code that was proven. |
| YELLOW → RED | Significant rewrite or bug found in the block | Major changes or discovered bugs mean the code needs to re-prove itself from scratch. |
| GREEN → RED | A surrounding dependency changed (schema, API, data source) | If the data source changed field names, the rendering code that reads those fields drops to RED until verified against the new source. |
This is the key insight: When you edit a GREEN block, it becomes YELLOW. When you significantly rewrite it, it becomes RED. This means every edit to proven code carries a cost — it resets the confidence clock. This is intentional. It should make you think twice about whether the edit is truly necessary.
8. The replace_all Rule
replace_all is the most dangerous edit operation because it modifies every occurrence of a string in a file without distinguishing between code blocks at different confidence levels or serving different roles.
NEVER use
replace_all on a file that contains any GREEN-annotated code unless the replacement string appears ONLY inside RED or YELLOW blocks.
Before Using replace_all
- Search the file for ALL occurrences of the target string
- For EACH occurrence, identify what confidence level that code block is
- For EACH occurrence, identify what data source that code reads from
- Confirm that the replacement is correct for ALL occurrences, not just the one you're trying to fix
- If ANY occurrence is in a GREEN block that should NOT be changed, use targeted individual edits instead
The March 2026 Lesson
What Happened
replace_all was used to change retail_price_cents to priceCents in shop.html. The file had 4 occurrences. All 4 read from the API, which returns retail_price_cents. Changing them to priceCents broke every single price on the site. If confidence annotations had existed, the price rendering block would have been GREEN with @datasource public-products.php → retail_price_cents, and the replace_all would have been immediately flagged as dangerous.
What Should Have Happened
Before running replace_all: read the annotation, see GREEN + Critical blast + datasource is API returning retail_price_cents. Conclusion: the field name retail_price_cents is correct for this block because the data source uses that name. Do not change it. Investigate the actual bug elsewhere.
9. Collateral Damage Prevention
Collateral damage is when a change meant to fix one thing breaks an unrelated thing. The confidence system prevents this by making the boundaries visible.
The "One Bug, Two Bugs" Pattern
- A bug is reported in Feature A
- While fixing Feature A, you notice Feature B's code "could be improved" or "should be consistent"
- You change Feature B's code even though it's working
- Feature B breaks
- Now there are two bugs: the original one in Feature A, plus a new one you created in Feature B
Rules to Prevent Collateral Damage
- Scope your edits. If the task is "fix price display," you touch price display code only. Not sort functions. Not cart logic. Not filtering. Just prices.
- If it's not broken, don't touch it. Especially if it's GREEN. "Consistency" and "while I'm in here" are not reasons to change proven code.
- One concern per edit. Each edit operation should address exactly one issue. If you find a second problem, fix it in a separate, targeted edit.
- Check adjacent code. Before editing, look at what's immediately above and below your target. Are you about to change something that's part of a larger proven block?
- Don't delete code you don't understand. If you can't explain what a code block does and why it exists, you cannot safely delete it. Read it, trace its callers, understand it first.
Violation: "Cleaning Up" While Fixing
Task: "Fix the price display bug." Action taken: Fixed the price bug AND renamed variables for consistency AND removed a function that "looked unused" AND reformatted the sort logic. Result: The "unused" function was called by the search feature, which now breaks. The sort logic refactor introduced a new bug. Two new issues from a one-issue task.
Correct: Surgical Fix
Task: "Fix the price display bug." Action taken: Identified the exact line where p.priceCents should be p.retail_price_cents. Changed that one reference. Verified the fix. Done. Everything else untouched.
10. Integration with Troubleshooting (Doc 19)
The Code Confidence Protocol and Troubleshooting Protocol work together. Here is the combined workflow for fixing any bug:
Combined Pre-Edit Workflow
- Doc 19, Section 2: Diagnose the bug. Complete the 5-step diagnostic sequence. Identify the exact file, line, and field name that's wrong.
- Doc 20: Check the confidence registry. Look up the file in
CODE-CONFIDENCE.md. What level are the blocks you need to touch? - Doc 20: Read the inline annotations. Open the file, find the block you need to edit. What does the
@confidenceannotation say? What's the@blastradius? What's the@datasource? - Doc 20, Section 3: Apply the rules for that level. If GREEN: is this the verified direct source of the bug? Is your edit the minimum change required? If YELLOW/RED: proceed with appropriate caution.
- Make the edit. Targeted, surgical, minimum change.
- Update the annotation. If you changed a GREEN block, demote to YELLOW. Update
@verifieddate once confirmed working. - Doc 19, Section 8–9: Verify and deploy. Pre-deploy checklist, then post-deploy verification.
The confidence system works because the annotations are IN the code. When you open a file to make an edit, the annotation is right there above the block telling you: this code is proven, this is what it does, this is what breaks if you get it wrong, and this is where it gets its data. It's impossible to ignore if it's impossible to miss.
11. Maintaining the System
When to Add Annotations
- After a successful deploy: Code that just proved itself in production should be annotated YELLOW (new) or promoted to GREEN (re-verified).
- After fixing a bug: The fixed code starts at RED (just changed). Once deployed and confirmed, promote to YELLOW. After sustained correct operation, promote to GREEN.
- During a catalog pass: Periodically walk through critical files and annotate any un-annotated blocks that handle critical features.
- When creating the site's registry: Catalog all critical code paths when a site first adopts this protocol.
When to Update Annotations
- After any edit to annotated code: Demote the confidence level (GREEN → YELLOW, YELLOW → RED for significant changes).
- After re-verification: Promote the level back up with the new
@verifieddate. - When a data source changes: If the API changes field names, every annotation referencing those field names must be updated and the code re-verified.
Registry Hygiene
- The registry should be updated whenever annotations are added or changed
- Stale entries (blocks that no longer exist) should be removed
- The registry's "Last updated" date indicates when it was last reviewed
- A registry that hasn't been updated in 30+ days should be audited
The overhead is low. Adding a 3-line annotation takes seconds. Checking the registry before an edit takes seconds. The cost of NOT doing it — breaking a production site, losing user trust, spending hours fixing self-inflicted bugs — is orders of magnitude higher.