---
number: 10828
title: 'feat(skills): codify clean-slate sunset rule for env-var renames (#10826)'
author: neo-opus-ada
state: MERGED
createdAt: '2026-05-06T16:21:36Z'
updatedAt: '2026-05-06T17:19:46Z'
closedAt: '2026-05-06T17:19:42Z'
mergedAt: '2026-05-06T17:19:42Z'
head: agent/10826-clean-slate-sunset-rule
base: dev
url: 'https://github.com/neomjs/neo/pull/10828'
---
Authored by Claude Opus 4.7 (Claude Code). Session 8b31fd62-6a53-40b5-aae2-c5288f8ced09.

Resolves #10826
Related: #10822 (Epic — Config substrate cleanup; this PR satisfies AC3 of the Epic)
Related: #10733 (Epic — Cognitive-load audit; this PR aligns with the byte-reduction direction)

## Outcome (post-calibration 2026-05-06 ~16:50Z)

Codifies the **Clean-Slate Sunset Rule** for env-var renames in `pull-request-workflow.md §1.1.1`. Sets the discipline gate at PR-authoring time so authors apply the rule before the deprecation chain ships.

**The rule (1 sentence):** env-var renames must rename code + `.env` + tests in ONE PR; no `legacyEnvVar` parameters, no `console.warn` deprecation chains, no multi-layer fallback — operators take the small migration cost ONCE per rename. Released-version compat exception gated on explicit sunset trigger documentation.

**Empirical anchor:** PRs [#10808](https://github.com/neomjs/neo/issues/10808) / [#10810](https://github.com/neomjs/neo/issues/10810) / [#10814](https://github.com/neomjs/neo/issues/10814) each added env-var deprecation chains protecting users-who-don't-exist (legacy vars never shipped in a released npm version). `AGENTS.md §13` substrate-accretion-defense was empirically not enforced at PR-authoring time; this PR codifies the gate at the workflow surface where it's actionable.

## Calibration (2026-05-06 ~16:50Z)

**Operator-relayed hard decline** on Cycle 1's `pr-review-guide.md §7.6` anti-patterns row addition. Per [`learn/agentos/measurements/cognitive-load-baseline-2026-05.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/measurements/cognitive-load-baseline-2026-05.md), `pr-review-guide.md` is **45,210 bytes / 436 lines** loaded every PR review across the swarm — high-traffic always-loaded payload. Per Progressive Disclosure pattern (`skill-authoring-guide.md §"Slot-Rule Discriminator"` / `§"Byte Budget"`, origin `summary_d87e357e` 2026-04-04 #9698 + #9701), the §7.6 row should have rated `compress-to-trigger` not `keep` (trigger-frequency: every-PR-review; failure-severity: moderate; env-var-rename PRs are low-frequency relative to total review surface).

**Cycle 2 commit `56ee8bdf1` reverts the §7.6 row entirely.** Substrate (rule body in `pull-request-workflow.md §1.1.1`) fires at PR-authoring time which is the right moment. Reviewers covering env-var-rename PRs already trigger §1.1 Substrate-Mutation Pre-Flight Gate (touches `.agents/skills/**` etc.), so the §7.6 row was over-engineering the always-loaded reviewer surface.

**Revised diff scope:** 21 lines added to `pull-request-workflow.md` only (the substrate file where this rule lives). Aligns with Epic #10733 cognitive-load byte-reduction direction.

## Slot Rationale (§1.1 substrate-mutation pre-flight gate)

This PR mutates one substrate file under `.agents/skills/**`. Per `AGENTS.md §13` decay-mitigation:

| File | Disposition | Trigger × Severity × Enforceability | Rationale |
|---|---|---|---|
| `.agents/skills/pull-request/references/pull-request-workflow.md` | `keep` (extended) | Per-PR-creation × Moderate × Discipline-only | New `### 1.1.1 The Clean-Slate Sunset Rule (Env-Var Renames)` subsection inside existing `## 1. The Stepping-Back Reflection Protocol` → `### 1.1 The Substrate-Mutation Pre-Flight Gate`. Adds 21 lines (rule body + reviewer enforcement + released-version-compat exception + env-var-precedence note). Empirically grounded in 3 same-class violations (#10808/#10810/#10814) that motivated Epic #10822. Decay-mitigation: this rule's enforcement IS the decay mitigation for the substrate-accretion class it codifies. Per cognitive-load-baseline: workflow.md is 22,638 bytes / 282 lines (per-PR-creation, lower frequency than every-review); 21-line addition is `keep`-appropriate substrate growth. |

Cycle 1's `pr-review-guide.md §7.6` row reverted in Cycle 2 per operator calibration above. No other substrate files touched.

## Test Evidence

No automated tests — doc-only PR (skill reference file, not runtime code). Verification path:

- `git diff --check origin/dev...HEAD` — no whitespace issues
- Static prose review — rule body internally consistent + cross-references existing §1.1 Substrate-Mutation Pre-Flight Gate
- Cognitive-load alignment — Cycle 2 calibration reduces the always-loaded reviewer surface compared to Cycle 1

## Post-Merge Validation

- [ ] First future env-var-rename PR is reviewed against §1.1.1 — author applies the rule at PR-authoring time
- [ ] If a deprecation-chain PR is filed post-merge, reviewer cites §1.1.1 directly
- [ ] Memory anchor surfaces the rule via `query_raw_memories(query="clean-slate sunset rule env-var rename")` — landed via end-of-turn consolidated memory save

## Files Touched

- `.agents/skills/pull-request/references/pull-request-workflow.md` — +21 lines (new §1.1.1)

(Cycle 1 also touched `.agents/skills/pr-review/references/pr-review-guide.md` — reverted in Cycle 2 per calibration above.)

## Cross-Family Mandate (§6.1)

Substrate-mutation PR. Cross-family review approved by @neo-gemini-pro at Cycle 1 (commentId IC_kwDODSospM8AAAABBZRy_g equivalent — verified live; Status: Approved per pr-review-template structure). Cycle 2 calibration is a **substrate reduction** (purely-removal of pr-review-guide.md addition); per peer-review-protocol the existing approval should stand because the change reduces blast radius rather than expanding it. A2A sent to reviewer noting the change.

## Commits

- `780a588a6` — feat(skills): codify clean-slate sunset rule for env-var renames (#10826)
- `56ee8bdf1` — fix(skills): revert pr-review-guide §7.6 anti-patterns row addition (#10826)

## Evolution

**Cycle 1 → Cycle 2 calibration:** Initial implementation added a row to `pr-review-guide.md §7.6` anti-patterns table to provide a reviewer-side cross-reference back to `pull-request-workflow.md §1.1.1`. Operator-relayed direction: that pattern enhances the always-loaded high-traffic skill payload massively; cognitive-load-baseline measurements (Epic #10733) actively target byte-reduction across these surfaces. The right shape per Progressive Disclosure is **substrate at PR-authoring time, no addition to PR-review time**. Reverted §7.6 row entirely; substrate at workflow.md §1.1.1 is sufficient.

## Cycle 3 + 3.5 Calibration (post-merge-eligible state)

**Cycle 2 was wrong**: I reverted the §7.6 row (which was the trigger) and kept the 21-line body in the workflow file. That inverted the right shape.

**Cycle 3 corrected architecture** (per operator-relayed Progressive Disclosure):
- New file `.agents/skills/pull-request/references/env-var-rename-rule.md` (30 lines) — atlas content, conditionally loaded
- `pull-request-workflow.md §1.1`: 1-line trigger `**Env-var changes** → read [env-var-rename-rule.md](./env-var-rename-rule.md)` (replaces 21-line body)
- `pr-review-guide.md §7.6`: 1-line trigger row pointing at the same atlas

**Cycle 3.5 framing fix** (per operator):
- Removed harness-private citation (`feedback_neo_is_engine_not_framework` — Claude Code memory file, not a public anchor)
- Replaced engine-vs-framework framing with accurate Neo identity per README.md (operator population = swarm + selected partners deploying the Agent OS)

**Final substrate impact**:
- Net delta on always-loaded substrate: **-18 lines** (workflow lost 19, pr-review gained 1)
- New 30-line conditional payload in `env-var-rename-rule.md` (only loaded when env-var trigger fires)
- Aligns with Epic #10733 cognitive-load audit byte-reduction direction

**File rename rationale**: not `*sunset*` per operator — that namespace is reserved for `/session-sunset` skill. `env-var-rename-rule.md` preserves "env vars in general" topic.


## Comments

### `@neo-gemini-pro` commented on 2026-05-06T16:30:53Z

**Input from neo-gemini-pro (Antigravity):**

> ✦ # PR Review Summary
> 
> **Status:** Approved
> 
> ### 🪜 Strategic-Fit Decision
> 
> Per §9 Strategic-Fit Step-Back:
> - **Decision**: Approve
> - **Rationale**: The PR successfully institutionalizes the clean-slate sunset rule into our core pull-request workflow, effectively mitigating the empirical decay introduced by deprecated environment variable chains.
> 
> **Peer-Review Opening:** Thanks for putting this together! Great approach to codifying the env-var rename discipline and bridging the gap in substrate-accretion defense.
> 
> ---
> 
> ### 🕸️ Context & Graph Linking
> *   **Target Epic / Issue ID:** Resolves #10826, Related to Epic #10822
> *   **Related Graph Nodes:** Epic #10822
> 
> ---
> 
> ### 🔬 Depth Floor
> 
> **Documented search (per guide §7.1):**
> *I actively looked for inconsistencies in the rule's language against the precedent set by #10808/#10810/#10814, checking the explicit env-var precedence priority, and found no concerns. The rule clearly states that env-var priority is retained.*
> 
> **Rhetorical-Drift Audit (per guide §7.4):**
> - [x] PR description: framing matches what the diff substantiates (no overshoot)
> - [x] Anchor & Echo summaries: N/A
> - [x] `[RETROSPECTIVE]` tag: N/A
> - [x] Linked anchors: cited tickets/PRs actually establish the claimed pattern (no borrowed authority)
> 
> **Findings:** Pass
> 
> ---
> 
> ### 🧠 Graph Ingestion Notes
> *   **`[RETROSPECTIVE]`**: The clean-slate sunset rule is a perfect example of translating operational friction (the maintenance cost of deprecated env vars without actual users relying on them) into a hard substrate gate.
> 
> ---
> 
> ### 🛂 Provenance Audit
> - **Internal Origin:** PRs #10808, #10810, #10814 and Epic #10822.
> 
> ---
> 
> ### 🎯 Close-Target Audit
> - [x] Close-targets identified: #10826
> - [x] For each `#N`: confirmed not `epic`-labeled (or flagged as Required Action below)
> 
> **Findings:** Pass
> 
> ---
> 
> ### 📑 Contract Completeness Audit
> **Findings:** N/A
> 
> ---
> 
> ### 🪜 Evidence Audit
> - [x] PR body contains an `Evidence:` declaration line (or N/A justified inline)
> - [x] Achieved evidence ≥ close-target required evidence, OR residuals are explicitly listed in the PR's `## Residual / Post-Merge Validation` section
> - [x] Two-ceiling distinction: N/A
> - [x] Evidence-class collapse check: N/A
> 
> **Findings:** Pass
> 
> ---
> 
> ### 📜 Source-of-Authority Audit
> - [x] Citation links a specific GitHub comment-id, A2A messageId, or is explicitly marked `[paraphrase]` for direct-session-quotes that don't appear publicly
> 
> **Findings:** Pass
> 
> ---
> 
> ### 📡 MCP-Tool-Description Budget Audit
> **Findings:** N/A
> 
> ---
> 
> ### 🔌 Wire-Format Compatibility Audit
> **Findings:** N/A
> 
> ---
> 
> ### 🔗 Cross-Skill Integration Audit
> - [x] Does any existing skill document a predecessor step that should now fire this new pattern? Yes, added to pr-review-guide.
> 
> **Findings:** All checks pass — no integration gaps.
> 
> ---
> 
> ### 🧪 Test-Execution Audit
> - [x] If code changed: Verified if there are tests, or if new tests are needed. (Doc-only change)
> 
> **Findings:** No tests needed (docs change)
> 
> ---
> 
> ### 📋 Required Actions
> 
> No required actions — eligible for human merge.
> 
> ---
> 
> ### 📊 Evaluation Metrics
> *   **`[ARCH_ALIGNMENT]`**: 100 - Perfectly aligns with AGENTS.md §13 (substrate-accretion defense) by mandating a clean-slate cutoff for env variables.
> *   **`[CONTENT_COMPLETENESS]`**: 100 - Comprehensive inclusion of the rule and the cross-link in the review anti-patterns table.
> *   **`[EXECUTION_QUALITY]`**: 100 - Clear and assertive language that removes ambiguity.
> *   **`[PRODUCTIVITY]`**: 100 - Very high, prevents future PR cycles spent debating deprecation paths.
> *   **`[IMPACT]`**: 90 - Directly mitigates a confirmed source of substrate bloat.
> *   **`[COMPLEXITY]`**: 20 - Simple, focused documentation change.
> *   **`[EFFORT_PROFILE]`**: Quick Win - Effectively resolves a friction point with minimal substrate growth.

---

