Record scene-update-cycle knowledge: Safe By Shape, review rules, case study#62
Merged
Conversation
…tudy Distills the July 2026 hardening effort (issues #44/#45/#59/#60, PRs #51/#58/#61, parked branch integration/scene-update-hardening) into durable repository knowledge: - PHILOSOPHY.md: new "Safe By Shape" section — safety a reviewer can see as boxes and solid lines; dashed arrows (invisible couplings) as review-stoppers; reshape first, then re-fix deliberately. - AGENTS.md: lifecycle/update-loop smell list with real instances, instrument-before-attributing rule for behavior pins, the two complementary review modes, the park-the-fix rule, and a new "Working With The Maintainer" section (design rallies, concrete cases first, one failure mode = one issue = one test, explicit known-hole merge agreements). - docs/case-study-scene-update-cycle.md: the four failure modes as input -> expected -> actual, how each was actually found (including the mis-attributed pin), why the fixes were parked, and the smells that generalize. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Docs-only PR capturing durable review/debugging knowledge from the July 2026 scene update-cycle hardening effort, turning a set of hard-won failure modes and review heuristics into repository-reference material (while intentionally excluding operational/Notion-specific details).
Changes:
- Adds “Safe By Shape” to PHILOSOPHY.md as a structural review criterion and communication contract.
- Expands AGENTS.md with concrete lifecycle/update-loop review smells and a new “Working With The Maintainer” collaboration section.
- Introduces a case study document summarizing four compose/apply failure modes, how they were found, and why fixes were parked in favor of structural redesign.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| PHILOSOPHY.md | Adds “Safe By Shape” guidance to reinforce structure-first correctness and review legibility expectations. |
| AGENTS.md | Adds practical review/debugging heuristics and maintainer-collaboration expectations derived from the hardening effort. |
| docs/case-study-scene-update-cycle.md | New evidence-driven case study documenting the scene update-cycle bug family and transferable smells/lessons. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.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
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.
Docs-only PR distilling the July 2026 scene-update hardening effort into durable repository knowledge, per maintainer request. No code changes; Notion-specific operational details deliberately excluded.
What's in it
PHILOSOPHY.md — "Safe By Shape" (after Structure Over Vigilance): a sound component should be drawable as boxes and solid lines; a bug is water in a holey plastic bag — the shape itself is distorted. Four properties of a clean shape (one owner / drawn ports only / phases cannot be skipped / nothing reaches inside mid-phase), the dashed arrow as review-stopper, and the reshape-first-then-re-fix-deliberately principle. Also states the communication contract: correct but illegible fails review.
AGENTS.md — two additions:
docs/case-study-scene-update-cycle.md — the evidence: the four failure modes (reentrant flush, stale pending target, apply-window silent drop, tracker-commit swallow) as input → expected → actual with the concrete EditText/counter example, how each was actually found (including the pin whose stated mechanism was wrong for months), why the fixes were parked (three findings pointing at one missing current/next cycle owner), and the smells that generalize.
Notes
integration/scene-update-hardeningand issues Scene projection: pending update targets dangle when a structural rebuild deletes their subtree (use-after-free) #44/0.0.2 bug batch: verified correctness fixes (lifecycle, state, Flow, Win32 text) #45/[Bug] platform apply 中に state を書くと、その更新が無言で失われる #59/[Bug] apply 中に boundary 自身の state を書くと、更新が tracker 段階で無言に失われる #60 remain the working artifacts; the case study links them.🤖 Generated with Claude Code