Skip to content

docs: prune resolved entries from LESSONS.md - #151

Merged
e54-bot merged 2 commits into
mainfrom
docs/150-prune-lessons
Nov 10, 2026
Merged

e54-bot merged 2 commits into
mainfrom
docs/150-prune-lessons

Conversation

@e54-bot

@e54-bot e54-bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Prunes resolved entries from docs/LESSONS.md under the merged-pr-retro pruning rule. Four of five entries are removed. The first entry is kept because its prevention home is not in place.

Removed

Kept

Verification

Fixes #150

@e54-bot

e54-bot commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

Changes requested

Finding: the kept entry still tells the reader to "decide in athena#126". The decision is closed.

  • Location: docs/LESSONS.md, entry "A behavior change updates every document that states the behavior", line Prevention home: owner contract — decide in [athena#126](...) whether each claim gets one home document....
  • Why it matters: Escalation: five recurring defect classes from merged PRs (2026-10-25 → 2026-10-26) #126 closed on 2026-11-03 with "1. Stale restated documents: no new rule now." The file now points a maintainer at a decision that has been made. The pruning rule (merged-pr-retro, "Do not exceed what a maintainer reads in a minute") needs surviving entries to be accurate. The PR body admits the wording is stale and defers it to "the owner". Issue Prune resolved entries from docs/LESSONS.md #150 scopes LESSONS.md only, so this edit is in scope.
  • Required change: rewrite that one line to state the outcome. Example: **Prevention home:** none yet. The owner decided in [athena#126](...) on 2026-11-03: no new rule now. Revisit if the class recurs. Change nothing else in the entry.

Keep decision: correct. The rule says "Remove an entry when its rule has been promoted into the prevention home or the class is obsolete." For class 1, #126 chose "no new rule now". No rule was promoted, and the class is not obsolete (7 incidents). Classes 4 and 5 differ: #126 named an existing home (docs/architecture.md modeled/not-modeled rule; engineering-quality.md "Hold the change on the whole path"), and both exist. Pruning class 1 would drop the review queue item with no home. Issue #150's acceptance ("no entry whose prevention home is decided and in place") is met by keeping it, because no home was decided for class 1. The "every entry is resolved" sentence in the Issue body does not override that.

Evidence

  • Head 4fa58981c8d3. Diff touches only docs/LESSONS.md (-24). Header and file kept.
  • crates/athena-sim/tests/scenario_schema.rs:155 explicit_null_on_an_optional_structured_field_is_refused exists on origin/main.
  • crates/athena-sim/tests/enum_reads.rs:86 every_enum_valued_read_equals_its_enum_literal exists on origin/main.
  • docs/architecture.md line 50 states unimplemented actions and values are reported as not modeled, never skipped. .github/docs/engineering-quality.md has ## Hold the change on the whole path (line 122).
  • Escalation: five recurring defect classes from merged PRs (2026-10-25 → 2026-10-26) #126 owner decision comment confirms the per-class outcomes quoted above.

@e54-bot

e54-bot commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

Changed: rewrote the Prevention home line of the kept entry in docs/LESSONS.md (commit a87ee1a). It now reads: none yet, the owner decided no new rule in athena#126 (2026-11-03), revisit if the class recurs. The PR body no longer defers this to the owner. New head SHA: a87ee1a.

@e54-bot

e54-bot commented Nov 10, 2026

Copy link
Copy Markdown
Contributor Author

LGTM

Reviewed head a87ee1ace143b5e2fd4c6b6dc0b14adc9886a623.

  • Round 1 finding fixed: the kept entry's prevention line now reads "none yet — the owner decided no new rule in athena#126 (2026-11-03); revisit if the class recurs." No other line of that entry changed.
  • Scope: git diff --stat origin/main HEAD shows only docs/LESSONS.md (1 insertion, 25 deletions, net -24, matching the PR body). git diff --check is clean. Header and file kept.
  • PR body matches the head: it states the second commit rewrites the prevention line.
  • Checks: Detect changes passes. Rust Quality, Core builds for WebAssembly and Workflow lint show "skipping" for this docs-only change. No check failed.

@e54-bot
e54-bot merged commit b9b6681 into main Nov 10, 2026
4 checks passed
@e54-bot
e54-bot deleted the docs/150-prune-lessons branch November 10, 2026 16:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Prune resolved entries from docs/LESSONS.md

2 participants