Skip to content

lessons: FIX-1649 epic wrap (cycle 21) - #2716

Merged
jhoffner merged 1 commit into
mainfrom
lessons/FIX-1649
Oct 4, 2026
Merged

jhoffner merged 1 commit into
mainfrom
lessons/FIX-1649

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 4, 2026 •

Copy link
Copy Markdown
Collaborator

What's asked of you

Nothing to approve in the grounding. This PR adds ledger rows only. The proposal pass is skipped, and the reason is below. Read the rows and the filed items. Merge when the rows look correct.

Why no proposal. Review cost was low on every measure. No direction artifact took a second round. No implementation PR took more than two fix waves (29 waves over 29 PRs; cycle 20 had 57 over 15). The expensive rework came from the closure runs, and the closure is the designed place to find it:

  • Three controls went WRONG on the closure's first run (FIX-1732, FIX-1733, FIX-1734). They repeat cycle 19's three shapes one for one: a control breaks more than its signal, a control misses a second path, or the fixture gives it nothing to change. FIX-1690 merged after the closure plan and caused two of the three. Only the closure's own control run can see this, and it did.
  • The 10-04 re-run found three child checks and one closure leg broken by merges to main (FIX-1737 B, C and D, and FIX-1718). Closure item 3 exists to catch this.
  • Codex found that GOAL_PART=bogus printed PASS with 0 verdicts. BP-003 already covers this, and one wave fixed it.

What would change my mind. A third closure where the reused controls break in the same three shapes, and the change that broke them merged before the closure plan. Then the plan could have seen it, and the closure plan's control table should get one line. The cycle file records this as claim 1.

Your decisions, filed and not proposed

What's in it

  • docs/internal/cycle-ledger/cycle-21.md: the new cycle file. It has 47 rows, the closure's runs, the control class, the dropped candidates, the filed items, the scores for cycles 18–20, and a finding map.
  • docs/internal/cycle-ledger.md: the index row for cycle 21.

Other filed items are in the cycle file: #2434 merged 5 minutes after it opened, before Codex; Linear states lag the merges; POC #2642 is still open; a zero-check guard for goals/lib/verdict.mts.

Scores: cycle 19's control-unit fix holds on one unconfounded instance (#2709 had no control-unit finding), so that claim closes. Cycle 20's race-primitive trigger had no qualifying PR. No changeset needed: internal docs only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq


Generated by Claude Code


Note

Low Risk
Internal documentation only; no runtime, auth, or product code changes.

Overview
Adds cycle 21 to the internal development-loop ledger for the Shift Manager lab shell epic wrap (FIX-1649, 2026-10-04).

docs/internal/cycle-ledger/cycle-21.md is a new ~318-line entry: 47 scored PRs (epic, specs, 29 implementation including closure #2709), load metrics vs cycle 20, closure run timeline, the recurring reused-control failure class (three WRONG controls on first closure run), skipped proposal rationale, filed follow-ups (reviewer exhaustion at 16 artifacts, open children, closure branch fixes without issues), scoring of cycles 18–20 claims, and claims for the next cycle.

docs/internal/cycle-ledger.md gains one index row pointing at that file.

Reviewed by Cursor Bugbot for commit 9c1009e. Configure here.

…ic, proposal skipped

Forty-seven rows: the epic PR and three amendments, fourteen specs and
spec amendments, and twenty-nine implementation PRs, the closure #2709
among them. No direction artifact took a second round, and no
implementation PR took more than two fix waves. The closure's runs found
three reused controls WRONG in cycle 19's three shapes, three child
checks broken by later merges, and a runner that passed with no
verdicts. Each was found on its designed path, so no grounding change
is proposed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cnm5DbhFmkarpesBpPQ9Dq
@vercel

vercel Bot commented Oct 4, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 4, 2026 11:22am UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 4, 2026 11:22am UTC
flow-state-dev-ui Ignored Ignored Oct 4, 2026 11:22am UTC

Request Review

@linear-code

linear-code Bot commented Oct 4, 2026

Copy link
Copy Markdown

FIX-1649

@jhoffner
jhoffner marked this pull request as ready for review October 4, 2026 19:43
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-04T19:48:01.891176Z 9c1009e Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@cursor

cursor Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 6710b6de-a793-41f3-a764-bc4174823e7a)

@jhoffner
jhoffner merged commit 3143994 into main Oct 4, 2026
16 checks passed

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review (cycle 21 ledger)

This PR is documentation-only: an index row plus a new cycle-21.md epic-wrap entry. I compared it to cycles 19–20, the distill-lessons skill, and the cycle-ledger header contract.

Verdict

Approve. The shape matches the instrument you have been using since roughly cycle 15: narrative lead → Method → per-PR table → Load → closure narrative → proposal decision → candidates / filed → forward claims → Finding map with checksum. For an epic with 47 scored artifacts, a wide table is expected, not accidental scope creep. The substantive call—proposal skipped because the recurring closure-control shapes are only visible on the closure’s first run—is argued in The class and Candidates considered and dropped, and it lines up with cycle 19’s precedent.

I do not think this entry invented a heavier doc species than cycle 19/20; it is longer mainly because the sample is larger (29 implementation PRs vs 15 in cycle 20).

Where complexity is real (but mostly inherited)

Area Take
47-row table + Finding map Duplication between table cells and map bullets is established convention (thread-id audit trail + footer sums). The map is not gratuitous; it is how prior cycles stay rebuildable.
Dense table cells Each row packs bot limits, POC refs, and multi-finding prose. That drives token cost more than row count. A slimmer cell convention (counts in table, thread detail only in map) would be a process change for future cycles, not a blocker here.
Manual REST harvest Method says every thread was read via GitHub REST. That is how distill-lessons is written today; there is no in-repo generator. A structured sidecar (JSON per PR) or a small verify script would simplify future wraps; this entry is consistent with current practice.

Optional simplifications (non-blocking)

These would shrink maintenance surface next time; I would not hold this PR for them unless you want to tighten the template repo-wide.

  1. “Proposal skipped” twice — opening paragraph and ## Proposal skipped largely repeat. One place (lead + short cross-ref) would be enough.
  2. Method inventory — listing every PR number before the table duplicates the table itself; a shorter scope paragraph (“47 rows below; rules follow cycle 20”) would age better.
  3. Per-row “Merged head … unread” — already summarized in Load / claims; repeating on ~25 rows is low signal (cycle 20 does the same; could be one Method bullet).
  4. Filed block length — operational notes (Linear lag, #2642 open, FIX-1735 on #2678) are useful but dilute the closure-control thesis; cycle 20’s filed section is similarly wide—worth a template discussion, not a rework of this file alone.

Cleaner alternative approach (bigger than this PR)

If the goal is less human duplication, the lever is upstream of this markdown:

  • Generate table rows + Finding map + footer from cached API payloads + a small human classification file (classes, felt-off, upstream-fix column).
  • Keep hand-written only judgment sections (lead, closure runs, The class, candidates, filed narrative).
  • Add a 20-line verifier that parses class counts per PR and asserts footer = sum(rows)—footer arithmetic on this entry checks out today (104 impl + 62 direction = 166), but there is no CI guard.

That is a distill-lessons / tooling change, not something this PR should absorb mid-wrap.

What I would not change

  • Dropping the mega-table (ledger contract).
  • Dropping the Finding map without replacing the thread-index + checksum role.
  • Forcing an upstream proposal when the entry correctly records skipped with evidence.

No changeset needed (internal docs).

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

- **The closure is where reuse is graded.** Run 1 found all three, and run 2 confirmed all six
controls RIGHT on the next `main`. That cost one fix PR (#2641, two waves) and one re-run.

## Proposal skipped

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify (optional): **Proposal skipped.** already appears in the opening (line 17), and this section mostly restates that verdict plus one orchestration.md quote. Collapsing to a single location (or a one-line ## Proposal skipped with “see lead”) would cut ~6 lines without losing the instrument.

3. **Unread merged heads.** Baseline: 25 of 29.
4. **Changeset length**, once more. Baseline: 0 of 7 fragments that Codex read.

## Finding map

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify (process, not a blocker): The Finding map mirrors class×counts already in the table; its unique value is T/SL positions and the footer checksum (lines 315–318). That split is established in cycles 15–21. If you ever want a leaner doc, generate map+footer from the table (or vice versa) rather than maintaining both by hand—this file is doing the right thing for today’s template.

finding this entry records. It is not yet a proposal, because the earliest point that can see each
one is the closure's own control run (see *Candidates considered and dropped*). **Proposal skipped.**

**Method — scope.** Forty-seven reviewed artifacts. They were found from FIX-1649's 35 Linear

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify (optional): Method pre-lists almost every PR number that appears again in the table (lines 52–100). Cycle 20 does this at smaller scale; here it is a second inventory. A shorter scope block (“47 artifacts; epic + amendments + specs + impl including closure #2709”) would be easier to maintain when numbers shift.

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Snob: already tight. No POC.

I read docs/internal/cycle-ledger/cycle-21.md, the new index row in docs/internal/cycle-ledger.md, and cycle 20's finding map, which is the shape this entry matches. distill-lessons asks for one row per artifact, the class counts, the prior-cycle scores, and the next claims. That is the 47-row table, the closure class, the dropped candidates, the filed items, and the finding-map checksum (104 implementation + 62 direction).

The lead and ## Proposal skipped state the same decision, and the method lists PR numbers the table lists again. Cutting both is about ten lines. The rows, the three control shapes, and the drops stay. The unread-head SHAs and the no-Codex marks sit inside rows that remain one line either way, and several name the head a bot did read (49fd744 on #2709, 2008bbb on #2641). Those SHAs are what the cycle 19 score cites. Moving the finding map into the cells adds the thread index to every row.

The PR body repeats the lead and the three filed decisions. That text is the ask. The cycle file is the record.

Head 9c1009e75.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9c1009e75a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +22 to +23
- the epic PR #2421 and three amendments: #2423, #2619, and #2648 (FIX-1737's spec, which also
amends the epic);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include the reviewed epic-wrap amendment in the sample

The declared exhaustive scope omits PR #2714 (spec/FIX-1649-wrap), even though its branch matches the stated epic-ID search and it merged roughly seven hours before this ledger commit. That PR contains review-fix commits for both Cursor (daa7b797) and Codex (5a51b7bb), making it a fourth reviewed epic amendment; excluding it leaves the 47-artifact sample and all downstream direction/finding totals incomplete.

Useful? React with 👍 / 👎.

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.

2 participants