docs: align row-245 sibling characterizations with vendor-published status - #2057
Merged
Conversation
…tatus PR #2036 corrected the primary characterization of the context-engineering source: it is a post on Anthropic's Claude blog — vendor-published, but a blog post rather than reference documentation — not "one practitioner's post". Four sibling instances still carried the old characterization. - proportionality-gate.md severity-ceiling bullet: re-derive the `info` ceiling rationale from the vendor-published status — the ceiling holds because `OPINION`-tier rules are exactly those no official doc confirms, and `error`/`warning` assert a breach of documented doctrine; no verdict changes. - proportionality-gate.md emitting-rule rationale and D2 remediation labelling: wording aligned. - PLAN.md Phase 2.5 `OPINION` clause: wording aligned. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HbtPzLRe1yBavNpsmv5Tum
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
Contributor
|
Claude finished @kyle-sexton's task in 1m 31s —— View job Review: PR #2057 — align row-245 sibling characterizations
Scope check (CLAUDE.md fresh-docs mandate): this PR is a prose wording edit to internal design docs ( Verified independently:
Finding (posted inline on No other issues found — the remaining edits are straightforward, faithful wording swaps that preserve the stated "no verdict changes" claim (ceiling stays |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HbtPzLRe1yBavNpsmv5Tum
kyle-sexton
enabled auto-merge (squash)
August 9, 2026 04:25
Contributor
|
Claude finished @kyle-sexton's task in 1m 42s —— View job Review: PR #2057 — align row-245 sibling characterizations
Scope check (CLAUDE.md fresh-docs mandate): unchanged from the prior review — this is a prose wording edit to internal design docs, not a skill/subagent/manifest/hook contract surface, so the "WebFetch before editing" mandate doesn't apply. The previously-flagged grammar issue is resolved. Commit
This now parses correctly (relative clause "that vendor blog advice ... cannot carry" with "that" as the object of "carry"), and the comma splice is gone. Dense phrasing, but grammatically sound — no further copyedit needed. Verified independently:
No correctness or maintainability issues found. The "no verdict changes" claim holds — ceiling stays |
kyle-sexton
pushed a commit
that referenced
this pull request
Sep 2, 2026
…instruction exception register (#3588) No related issue: this PR is the corpus absorption itself; the actionable follow-ups it produced were filed as their own issues (#3562-#3568, #3598) and are referenced below rather than closed here. ## Summary Absorbs the context-engineering corpus (the trq212 "New rules of context engineering for Claude 5 models" X article of 2026-07-24, the Anthropic "Effective context engineering for AI agents" engineering post of 2025-09-29, and the nine first-party pages they link) into this repository: five graduated knowledge documents, one new convention with its wiring, and three skill corrections. The upstream facts it rests on were verified against current official surfaces, and the answer set was validated by two independent fresh-context arms before sign-off. Per topic-docs v3.0.0, the decision contract is contract tier: it was committed on this branch as it locked and pruned before merge. It is pasted at the bottom of this body, and its durable outcomes graduated through the knowledge-vault seam into `docs/specs/`. ## Fix **Graduated knowledge**, `docs/specs/context-engineering-*.md`, moved out of the contract slice by history-preserving `git mv`: - `corpus-knowledge.md`, both primary sources by theme with byte-verified quotes, the figure-borne facts that exist in no text on either page (the approximately 9,100-character TodoWrite tool description, the six-layer context stack), the settled upstream facts, custody findings CF-1 to CF-7, and an appendix carrying the three system-prompt calibration prompts verbatim, transcribed from the figure image and re-verified by a second reader. - `critical-apparatus.md`, 142 of 318 swept assumption, omission and tension rows, the cross-source tensions (including the few-shot reversal between the two primaries), the unstated interface-versus-behavior thesis, and ten adoption guardrails. - `linked-sources.md`, the nine linked pages with citations, mechanisms and numbers, including the dynamic-workflows API surface and the multi-agent token economics that upstream publishes only inside figures. - `vertical-decisions.md`, verticals V2 to V7 resolved here rather than deferred, four of them to no change with the reason recorded, plus the one V1 answer (post-upgrade instruction re-testing) whose disposition had no other durable home once the contract was pruned. - `deletion-evidence-attribution.md`, the mechanism the consequential deletion tier needs, and why a per-rule bare experiment is not affordable. **New convention.** `docs/conventions/instruction-exception-register/` answers the "except in highly important areas" carve-out that subtractive instruction guidance leaves undefined. It adopts Gate 0's six consequence classes by reference rather than forking them, and adds the operation Gate 0 does not govern: deletion. Non-exhaustive and tighten-only, so omission never licenses a cut. **Wiring, in the same change**, because an unconsumed register changes no behavior — every consumer the register's table names now reads it: - `audit-instructions` criteria I1, I4 and I5 hold a protected candidate and propose compression instead of deletion. I1 carries the reason its own bar cannot see the problem: it asks whether removal would change behavior *today*, and a protected rail's removal changes behavior only on the occasion it was written for. - `unhobble` Phase 4 no longer ends at "everything the ledger did not defend stays deleted". A rule matching a protected class is restored whether or not the ledger logged against it, since a rail whose absence is unrecoverable will not usually announce itself inside one experiment window. The strip stays permitted — it is reversible and branch-local — and register holds are tallied separately so restoring one is not miscounted as a deletion the ledger defeated. - `instruction-placement`'s routing rubric names the register as the deletion counterpart, so one concern keeps one adjudication chain and the class list keeps one owner. **Skill corrections.** `session-flow:orchestrate` reconciles its 3-10x token-multiplier line against the upstream ~15x measurement it conflicted with, and carries the 1-2k condensed-return magnitude with its citation. **Upstream-drift near-miss.** `docs/conventions/upstream-drift/CHANGELOG.md` gains a 1.6.3 entry recording a silent-revision near-miss adjacent to its content-hashing deferral, with the trigger explicitly not fired and the deferral text untouched. ## Verification - `scripts/affected-tests.sh --run`: 30 selected suites on the final tree, all passed or skipped, zero failures. - Net PR diff contains no path under `docs/topics/**`, satisfying `contract-slice-prune-gate`. - `scripts/check-changelog-parity.sh` `--check`, `--check-bump`, `--check-order` and `--check-preserved` all pass against `origin/main` after the three plugin bumps. - Every relative markdown link in the changed files was resolved against the working tree; all 10 files, zero broken. - Upstream facts verified against current official surfaces and cross-checked by a second fresh-context arm with five spot-fetches, all reproducing verbatim: the `#` memory hotkey was removed in changelog v2.0.70; `/doctor`'s documented behavior per `commands.md` (v2.1.205 and v2.1.206) trims, dedupes and migrates CLAUDE.md guidance and finds unused skills by context cost, and no official surface describes skill-content "rightsizing"; the memory tool spans all Claude 4 and later models with no beta header while context editing remains beta, and Claude Code exposes neither natively. Recency anchor: Claude Code v2.1.252. - The 80% system-prompt reduction figure appears on no official documentation surface; it is recorded OPINION-tier with directional corroboration from changelog v2.1.154, citing both first-party carriers. - Corpus slices passed their standing byte-exactness gates through four correction rounds; the two verification arms per slice were same-vendor, and that degradation is recorded rather than hidden. - Answer set validated by two independent fresh-context arms with the recommendation rationale withheld: 14 of 14 confirmed, zero challenged, one premise correction absorbed. ## Related - Refs #3562, #3563, #3564, #3565, #3566, #3567, #3568 — the execution receipts this PR files work against: the exception register's follow-ups, the deletion-evidence attribution design, the orchestrate reconciliation, the I15 boundary reopen, the unhobbling security caveats, the content-hash designed issue, and the shared-surface governance decision. - Refs #3598, the `work-item-tracker` `create-item` version-guard defect found while filing those receipts (`gh >= 2.94` is required unconditionally, so a create needing none of the gated features is refused on `gh` 2.45). - Refs #3552 / #3557, the topic-docs v3 clean-break wave, which landed mid-effort and is the reason this PR's contract slice is pruned rather than committed. - Refs #3592, the Finding Your Unknowns corpus integration, which landed `docs/FINDING-YOUR-UNKNOWNS.md` mid-effort; this PR's field-guide reference points at it. ### Contract-slice pointers (topic-docs v3, prune with pointer) - Pre-prune commit (the last one that still held the slice): `1f7a11a4`. Under squash-merge this SHA form is best-effort; the graduation targets below are the load-bearing record. - Durable outcomes graduated to: `docs/specs/context-engineering-corpus-knowledge.md`, `docs/specs/context-engineering-critical-apparatus.md`, `docs/specs/context-engineering-linked-sources.md`, `docs/specs/context-engineering-vertical-decisions.md`, `docs/specs/context-engineering-deletion-evidence-attribution.md`, and the new convention at `docs/conventions/instruction-exception-register/`. - Actionable follow-ups graduated to the work-item tracker as the issues listed above. --- ## Approved decision contract (pruned `docs/topics/context-engineering-integration/PLAN.md`) Pasted verbatim per the prune-with-pointer lifecycle. GitHub's body sanitizer strips `<details>` here, so it is inline rather than collapsed. # Context-engineering corpus integration — decision contract ## Brief Status: **SIGNED OFF** — the operator confirmed the full sheet (Q1-Q16, all recommended dispositions as presented) on 2026-09-01 ("lets go with those"), satisfying the standing directive of 2026-08-31 ("I will confirm final answers for ALL questions... I want final sign off"). Q15 resolved: **finish** the prior plan (phases 8-11, with the corpus input note as a mandatory Phase 10 input). Q16 resolved: **topic-docs v3 wave first**; Q11/Q12/C1-class work executes against v3 shapes. Execution proceeds per the contract below. Grounded as of commit `335081c6` (origin/main, fetched 2026-09-01). Evidence artifacts live in the session's memory tier (`.work/context-engineering-integration/` and `.work/context-eng-corpus/`): two byte-verified docpage-digest slices (P1 = the trq212 "New rules of context engineering for Claude 5 models" X article; P2 = the Anthropic "Effective context engineering for AI agents" engineering post, published 2025-09-29), nine deep tier-2 page inventories, a fresh unbiased paragraph-grain sweep with four-lens critical apparatus, bidirectional reconciliation against the prior plan and field-guide audit, a master coverage ledger, verified EXPLORE/RESEARCH artifacts, blindspot cards B1-B10, brainstorm candidates C1-C12, and a fresh-context devils-advocate report (1 CRITICAL / 4 HIGH). The memory tier is never committed; this Brief is the durable record and inlines every decision-bearing fact. ### TLDR Absorb the two-article context-engineering corpus (plus its nine linked pages) into this marketplace's decision record, and integrate what earns its place: inputs to the in-flight `context-engineering-claude-5` plan, a small set of doc+wiring artifacts, two skill-vocabulary extensions, and recorded settled facts — under OPINION-tier/provenance discipline, with everything gated on the operator's final sign-off. ### Goal A signed-off answer set (Q1-Q14) that routes every corpus finding to a named, durable home — or an explicit deferral — without duplicating the prior plan's territory, silently expanding its locked Brief, or authoring against surfaces that have drifted. ### Constraints - Final sign-off gate: the operator confirms ALL answers; "go with recommended" assembles the sheet, never skips the gate. - The prior plan `docs/topics/context-engineering-claude-5/` owns the P1 instruction-audit lane; this effort never re-absorbs P1 or edits that plan's design docs unilaterally. - Memory-tier evidence is cited by content (inlined here) or by tracker item, never by bare `.work` path in anything meant to outlive the session. - Sequencing: the work-folder-hierarchy / topic-docs v3 clean-break wave (#3552, Brief locked 2026-09-01) restructures the `.work` substrate; Q12/C1/B9-dependent work orders against it (operator sequencing question on the sheet). ### Provisionally locked answers (rounds 1-2; refined by blindspot/devils-advocate; ALL pending sign-off) - **Q1 (deletion evidence threshold):** two-tier — editorial audit-instructions pass may delete trivial legacy guards; consequential rules need ledger evidence. Refinement (B5 + DA-MEDIUM): express the consequential tier in unhobble's existing two-rows-same-cause grammar, BUT that grammar currently defends re-adds after a full strip, not per-rule deletions — the deletion tier needs an attribution design (observation window, same-cause rule) before it becomes a skill edit. - **Q2 (exception register):** yes — a docs/conventions owner doc naming the "highly important areas" where hard constraints stay. Refinements (B2 + DA-MEDIUM): inert unless wired — same change names it in consuming skills' criteria text; register is NON-EXHAUSTIVE with a tighten-only clause; cross-referenced from instruction-placement's routing-rubric (Gate 0) so one concern keeps one adjudication chain; omission never licenses deletion. - **Q3 (conflict coverage):** superseded by evidence — audit-instructions I15 scopes conflicts to resident-surface pairs BY RECORDED DESIGN (its criteria file cites the article's user-request example as Source). The user-request-clash axis is a boundary REOPEN with a detectability answer, filed as an OPINION-tier detector candidate to the prior plan's catalog via tracker item (see Q8/C9), not a simple extension. - **Q4 (/doctor):** verification DONE by research — commands.md (v2.1.205/206): /doctor trims/dedupes/migrates CLAUDE.md guidance into skills and finds unused skills by context cost; no official surface says "rightsize" or skill-content simplification. The audit-native-overlap run is unnecessary (Q9); repo docs citing /doctor cite commands.md. - **Q5 (80% claim posture):** OPINION-tier WITH directional-corroboration annotation. Carriers (corrected 2026-09-01 by validator 2): the X article AND its claude.com/blog twin (the-new-rules-of-context-engineering-for-claude-5-generation-models) both carry the figure — under the repo's recorded precedent (audit-instructions criteria.md:153-158) a vendor blog corroborates rather than defines, so the tier stands; changelog v2.1.154 ("lean system prompt is now the default") corroborates direction only. Magnitude and "no measurable loss" stay vendor-voice (verifier's world-truth ruling); scope qualifier ("on our coding evaluations") always carried. Never phrase the annotation as "no official surface carries it" — falsifiable in one fetch. - **Q6 (model-upgrade re-test):** documented trigger only; the shipped `audit-pass` re-run contract (lease/epoch, suppression, three-scope inventory) is the ritual vehicle. Cite shipped reference files, not design/rerun-contract.md (drifted; flagged to plan owner). - **Q7 (prior-plan relationship):** fresh unbiased pass FIRST (executed 2026-08-31: 10 fresh sweeps, 4 reconciliation adjudications, coverage ledger); prior work is one reconciliation input. Residual decision → sign-off sheet: is the prior plan alive (resume / finish / absorb-and-close)? Routing without that answer is burial. ### Open questions for the sign-off sheet (recommended dispositions; operator decides) - **Q8:** split the gap-cluster routing — only execution-changing inputs (I15 reopen, rerun-contract drift, CF-7 wording, P2-never-engaged) go to the prior plan via the C2 note + phase-section references + tracker items; G-SEC (guardrail-deletion / memory- poisoning security) becomes its OWN work item now (security cost of burial); G-THESIS + G-PRECOND ride with the corpus critical apparatus (Q12); G-GOV is green-field with C10. - **Q9:** drop the audit-native-overlap /doctor run (evidence inlined at Q4); CF-7 filed as a wording fix, tier logic unaffected (venue characterization was litigated in #2036/#2057 — the note engages that history, headline softened from "authority-inflating"). - **Q10:** adopt the prior plan's OPINION-tier vocabulary corpus-wide + snapshot-dated citations. REVISED per devils-advocate: CF-1 does NOT fire upstream-drift's recorded content-hashing reopen trigger (no committed stale stamp caused a defect) — record CF-1 as adjacent near-miss evidence in a dated changelog entry per that convention's own v1.6.2 precedent, and file the hash store as its own designed issue via tracker; do not edit the deferral text. - **Q11:** cite-only now; graduation + custody policy deferred to V7, sequenced after the topic-docs v3 wave. - **Q12:** critical-apparatus home rides the corpus slices pending V7 + v3 sequencing; the durable pointer is this Brief + tracker items. - **Q13:** apply the P2-slice zero-cost merges as corrections round 4 (bakery transcriptions, compaction caveat C105, sub-agent economics) with re-pin + re-verify — noting the slice is memory-tier until Q11/V7 graduation decides otherwise. - **Q14:** the dated input note lands under the prior plan's `design/` per topic-docs, is referenced from PLAN.md AND from the phase sections it gates (Phase 8 criteria edits, Phase 10 reconcile) in the same commit, with tracker items for each actionable payload. ### Validation record Two independent fresh-context validators (rationale withheld, devils-advocate evidence discipline, 2026-09-01) each audited all seven locked decisions: 14/14 CONFIRMED, 0 CHALLENGED, 0 RECLASSIFIED. Standing findings carried to execution: (1) D3's tracker item must be written to survive an absorb-and-close outcome on Q15; (2) D1's consequential tier is deliberately unclearable until its attribution design exists — the ordering is enforced, not incidental; (3) Q5's annotation cites both first-party carriers (above); (4) D2's same-change wiring into shipped skills respects the repo/product "two hats" boundary unhobble records. ### Captured assumptions - Same operator owns this effort, the prior plan, and the topic-docs v3 wave; sequencing is theirs alone (sheet question). - Claude Code surfaces verified 2026-08-31/09-01 (v2.1.252 changelog recency gate); any execution re-verifies against then-current surfaces per the repo's upstream-drift discipline. - The `#` memory hotkey is REMOVED (changelog v2.0.70) — settled fact, recorded; the memory tool and context editing are platform-side (memory tool: all Claude 4+ models, no beta header; context editing: beta) and Claude Code exposes neither natively (analogues: auto-memory, compaction). ### Out of scope - Re-absorbing P1 into a second plan; editing the prior plan's design docs beyond the Q14 note; implementing C6-C12 before sign-off; graduating corpus slices before V7/v3 sequencing; referenced-external sources (Karpathy, context-rot study, arXiv, Willison) beyond cataloging. ### Acceptance criteria - The sign-off sheet presents ALL of Q1-Q14 in their refined forms with the operator's explicit confirmation recorded per answer; no answer executes unconfirmed. - Every accepted routing has a durable receipt (commit, tracker item, or phase-section reference) — nothing disposed by memory-tier note alone. - Post-sign-off execution follows the per-unit loop: one artifact at a time — apply, verify (the repo's own gates), close. ### Deferred questions All USER-RESERVED items were resolved by the operator's sign-off (2026-09-01, full sheet); none remain deferred. Resolutions and receipts: - Q8 — split routing ADOPTED: execution-changing inputs via the design note; G-SEC → #3566; G-THESIS/G-PRECOND ride the corpus; G-GOV → #3568. - Q9 — /doctor overlap run DROPPED; CF-7 wording fix carried in the note (payload 4). - Q10 — ADOPTED as revised: upstream-drift CHANGELOG 1.6.3 near-miss entry (deferral untouched, trigger not fired); hash store → #3567. - Q11 — cite-only now; graduation deferred to V7, after topic-docs v3. - Q12 — critical apparatus rides the corpus slices pending V7 + v3; this Brief + trackers are the durable pointers. - Q13 — EXECUTED: P2-slice corrections round 4 applied (figure transcriptions, compaction caveat, economics grounding), PNG re-verified, standing gates 12/12 PASS, re-pinned. - Q14 — EXECUTED: `design/corpus-input-2026-09-01.md` + header/Phase 8/Phase 10 references in the prior plan (one commit). - Q15 — FINISH the prior plan (phases 8-11; the note is a mandatory Phase 10 input). - Q16 — topic-docs v3 wave FIRST; v3-dependent work (Q11/Q12/C1-class) sequences after it. ### Execution receipts Tracker items: #3562 (C6 exception register), #3563 (C7 deletion-evidence attribution design), #3564 (C8 orchestrate reconciliation + annotation), #3565 (C9 I15 boundary reopen, written to survive any prior-plan outcome), #3566 (G-SEC security caveats), #3567 (hash store designed-issue placeholder), #3568 (G-GOV ownership decision). Commits: 6b7cd13 (contract), 48d851e (validator findings), 0c8bc33 (C2/C3/C5 batch), plus this one. Operational note: the work-item-tracker seam's `create-item` requires gh >= 2.94 and this cloud environment ships 2.45 (seam exit 3), so receipts were filed through the bound GitHub adapter's provider-mechanic path (repo-scoped REST) — coordination verbs (claim/lease) were not needed for solo-session creates. ## Plan (Empty — `/planning:plan` fills this after sign-off.) --- ### Post-sign-off amendments Two decisions above were overtaken by events after sign-off, and the amendment is recorded here rather than by editing the signed text: - **Q14** named the prior plan's `design/` as the input note's home. That slice was pruned from `main` by the topic-docs v3.0.0 adoption (#3557) while this work was in flight, so the note has no home. Its four payloads survive elsewhere: the I15 reopen as #3565, the P2-never-engaged finding in `context-engineering-critical-apparatus.md`, CF-7 in `context-engineering-corpus-knowledge.md` (recorded for the pattern, since the document it corrected no longer exists), and the rerun-contract drift moot for the same reason. - **Q11/Q12** deferred graduation and the critical-apparatus home to V7 "after the v3 wave". V7 resolved to graduate now rather than defer, because the memory tier does not survive a session; see `docs/specs/context-engineering-vertical-decisions.md`. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016uCQCPBraw7iVZ61F83EAJ --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to PR #2036, which corrected the primary characterization of the context-engineering source (a post on Anthropic's Claude blog — vendor-published, but a blog post rather than reference documentation — not "one practitioner's post"). Four sibling instances still carried the old characterization:
docs/topics/context-engineering-claude-5/design/proportionality-gate.mdseverity-ceiling bullet (load-bearing): theinfoceiling's rationale rested on "an unconfirmed practitioner preference". Re-derived honestly against the vendor-published status: the ceiling holds because an emitting rule sits in theOPINIONtier precisely when the corroboration pass found no official doc confirming it, anderror/warningassert a breach of documented doctrine — a force vendor blog advice without documentation behind it cannot carry. No verdict changes (ceiling staysinfo; default-off, explicit opt-in, never fix-applied all stand).proportionality-gate.mdemitting-rule rationale ("one practitioner's unconfirmed preference" → "vendor blog advice that no documentation confirms").proportionality-gate.mdD2 remediation-labelling bullet ("a practitioner's preference" → "uncorroborated vendor blog guidance").PLAN.mdPhase 2.5OPINIONclause (same rationale sentence, wording aligned).A sweep of
docs/topics/context-engineering-claude-5/for "practitioner", "unconfirmed preference", and similar found no further instances; the primary indesign/official-corroboration.mdline 3 is owned by open PR #2036 and deliberately untouched here. No version bump — repo docs, not a plugin.Test plan
npx markdownlint-cli2on both changed files: 0 errors.Related
No linked issue — docs follow-up to PR #2036 row-245 fix, umbrella tracking only.
🤖 Generated with Claude Code
https://claude.ai/code/session_01HbtPzLRe1yBavNpsmv5Tum