Skip to content

lessons: FIX-1903 shift-manager:dev epic cycle - #3447

Merged
jhoffner merged 4 commits into
mainfrom
claude/project-thread-k7msfx
Oct 19, 2026
Merged

jhoffner merged 4 commits into
mainfrom
claude/project-thread-k7msfx

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

What this is

This is the distill-lessons loop, run at wrap for epic FIX-1903 ("out of the box, shift-manager:dev develops Shift Manager and FSD"). It adds two things.

  1. Cycle 24 of the ledger (docs/internal/cycle-ledger/cycle-24.md and its index row).
  2. One sentence in tenet 5 (docs/philosophy.md): a prompt is a call site. No new BP.

What the ledger found

The proposal

Insert in tenet 5, after "A workaround every caller must copy is a smell.":

A prompt is a call site too: when the instruction is right and a model still does the wrong thing, fix what it was handed rather than adding instructions.

The sentence is scoped to a correct instruction, so a prompt that is missing or wrong (as in FIX-1185) is still fixed in the prompt. The examples (a schema that accepts the wrong shape, a document written for another profile, a tool that returns too little) live in the cycle entry, not the apex paragraph.

Dropped, with reasons in the cycle file:

Job audit: every addition considered, and the job it named

Addition Job Audit result
projectWorkspace({ checkouts }), ProjectCheckout (#3185); checkoutSource (#3194); RunLocation.orgless (#3199); fetch-before-cut and upstream pins (#3201) J1 say where a run's checkout comes from coherent, no fold
baseCommit on the run record, readRunCommits(…, baseCommit) (#3201) J1b count a run's own commits fold: the closure check re-derives the base → FIX-2015
probeClaudeAccount and its types (#3189); startHarness start check (#3189) J2 check a harness can run fold: Cursor's and Codex's sign-in checks live in Kitchen Sink app code; CLAUDE_CODE_PASS is copied twice → FIX-2014
mcpTools option and ClaudeCodeMcpTool* (#3261); projectMcpTools and RelayedMcp* (#3261); MCPCallToolOptions (#3261) J3 hand a run tools from MCP servers fold: the neutral relay type lives in a vendor package and is re-declared in workforce → comment on FIX-1986 (dedupe)
redactSecrets (#3261) J4 keep a secret out of what leaves the server fold: the Error Reporter's redact skips secrets under 8 chars, so a short MCP key leaks into a report → FIX-2012
mcpCredentialsCapability, defineMcpCredentialsCollection, mcpCredentialSchema, mcpCredentialProblem, MCP_CREDENTIALS_*; Settings route (#3261) J5 store a user's own credential coherent: one store, on FIX-1955's secret fields
setMcpServers and schemas, checkedMcpServers, isMcpServerName (#3261) J6 change one setting on a project coherent: third member of the setter family
openLab({ documents, skills }) (#3317) J7 give a profile's workers their standing documents fold: the profile replaces only the fixtures it names, and two more DevTeam fixtures still reach fsd runs → FIX-2013
addTask/dispatchTask input must be an object (#3308) deliver work no new entry, schema change only, no audit
Conversation passes groupToolCalls (#3272) none wiring, no audit

All new issues are in "Workforce: Shift Manager", in Backlog, and related to their source issues.

What's asked of you

Should we take the tenet 5 sentence, or reshape it?

  • It changes the grounding, so the distill-lessons review gate applies.
  • I recommend taking it. Both of FIX-1904: an item asked of the chief of staff is coded in the right project, and its goal runs alone #3205's prompt fixes came back as closure blockers, and the same shape cost three days in cycle 22.
  • What would change my mind: a case where the instruction was right, the prompt was still the owning layer, and this sentence pushed someone into a schema change.
  • If I'm wrong, the cost is a worker spending a minute asking what the model was handed before editing the prompt.

When you approve a spec by merging, should you wait for a requested Codex pass?

Two scheduling calls carried over from cycle 23:

  • FIX-1183, or a shared control grader. Five closures in a row have hit this.
  • Whether to run pnpm goal:all --model-free on main nightly. Right now goal checks rot between a merge and the next closure. goals/README.md deliberately keeps goals out of CI, so this call is yours.

Already handled at wrap:

Verification

  • Counts come from REST: pulls/{n}/reviews, /comments, and issues/{n}/comments. Linear children and issue text were read over GraphQL.
  • Each finding was given one class from its PR's reviews and inline threads. Direction approval and merge are one event here: none of the six direction PRs has a human approving review.
  • Fix carriage: git merge-base --is-ancestor ea68a989 <first head> returned YES for all 12 implementation PRs.
  • Each audit finding was read in the code:
    • redact.ts MIN_SECRET = 8 vs redactSecrets
    • CLAUDE_CODE_PASS in both files
    • the branch-naming and handbook markers
    • project-mcp-tools.ts "matched structurally"
  • Ran check-retired-terms, validate-model-strings, validate-reserved-names and validate-no-nul-bytes. All pass.
  • No changeset: these are internal process docs (BP-022).

🤖 Generated with Claude Code

https://claude.ai/code/session_01MJsSFWmTXycBXJU4s96Pk1

…net 5 says a prompt is a call site

Ledger rows for the epic PR, its amendment, four issue specs and twelve
implementation PRs (three outside the epic but born from it), plus the
wrap's job-surface map and one audit per job that grew. Four fold
candidates filed (FIX-2012..FIX-2015) and one comment on FIX-1986.

Proposed: one sentence in tenet 5. Two of #3205's prompt fixes left
their causes in place and both came back as closure blockers
(FIX-1965, FIX-1971), the same shape as cycle 22's #2768.

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

vercel Bot commented Oct 14, 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 15, 2026 3:28pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 15, 2026 3:28pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 15, 2026 3:28pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

FIX-1903

@jhoffner
jhoffner marked this pull request as ready for review October 15, 2026 14:14

@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 ledger + tenet 5)

This PR is docs-only and the measurement story is strong: class (a) is a real loop failure (prompt workarounds while z.unknown(), DevTeam fixtures, and FIX-1872’s path stayed broken), and tying it to tenet 5’s “fix at the owning layer” is coherent. I would not ask to drop the ledger entry or the philosophy sharpen outright.

Where the approach went further than the instrument needs is mostly surface area, not wrong conclusions.

What looks like the right minimum change

Cycles 22 and 23 landed their upstream fixes in operational text (goals/README.md, issue-implement race trigger) with a short apex mirror only when needed. This cycle proposes only docs/philosophy.md for (a). That is defensible (the gap is “nobody reads prompts as call sites”), but it inverts the usual distill pattern: implementers feel issue-implement / worker prompts daily; tenet 5 is always-loaded but easy to treat as abstract.

Cleaner alternative (if you want a smaller, more durable diff):

  1. Tenet 5: keep a minimal clause—e.g. “A prompt is a call site too.”—and let the parenthetical examples live in cycle-24.md (or a BP later), not in the apex paragraph that already carries depth/convergence material.
  2. Skill mirror: one sharpened sentence in issue-implement (or a shared worker checklist): when a model misbehaves on bad input shape / wrong standing doc / thin tool surface, fix that layer before editing WORKER.md. That is where #3205 actually failed.
  3. Drop or collapse Job surface + Job audits (~lines 181–226): these sections are not in 22/23 and read like audit-coherence deliverable pasted into the ledger. The routing (FIX-2012–2015, FIX-1986) belongs in Linear / epic wrap / project-spec; the ledger already has “Candidates considered and dropped” and “Filed, not proposed” patterns (cycle 21). A short Filed, not proposed block with issue ids + one-line finding each would preserve signal without a new mandatory section type for every epic wrap.
  4. De-duplicate narrative: FIX-1965 / FIX-1971 / #3205 / cycle-22 #2768 appear in the lede, class (a), the PR table, §(a), and scoring. Consider a thinner PR table (“primary class + one-line upstream miss”) and let §(a) carry the cross-cycle table only—same readability goal as 23’s crash-window section, which synthesizes rather than re-lists rows.
  5. Method boilerplate: “Endpoints and rounds” is nearly copy-paste from 23; a single line “Same counting rules as cycle 23” (with a link) would shrink maintenance if entries stay self-contained enough.

What I would not block on (owner / process)

  • (b)(c)(d)(e) as “owner ask, not text” — consistent with the ledger header.
  • Bundling philosophy in the same PR as the cycle file — reasonable when the entry is the proposal record.
  • Forensic length in the PR matrix — on par with 23; the issue is added sections, not the table alone.

Verdict

Comment, not approve: the upstream fix direction is sound, but the PR is larger than the smallest change that would move the loop—especially Job surface / Job audits and the long tenet-5 paragraph vs 22/23’s “sharpen existing execution docs first.” If you want one follow-up before merge, I’d prioritize moving or shrinking the job-audit block and splitting tenet 5 (minimal clause) + issue-implement (operational hook); everything else can be a tighten pass on redundancy.

Happy to approve a revision that keeps the (a) thesis and claims/scoring but drops the new audit appendix to filed-issue bullets.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread docs/internal/cycle-ledger/cycle-24.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-24.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-24.md Resolved
Comment thread docs/philosophy.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-24.md Resolved
…; fix sample count

Tenet 5 keeps only "a prompt is a call site too" and its rule; the
examples move into the cycle entry. The ledger's job-surface and
job-audit tables collapse to a "Filed, not proposed" list (the full
addition list stays in the PR body). The scope count is 18, matching the
table.

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

@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. The cycle 24 lead retells the (a) table. Fold #3485 (567f07ad7) into this branch and close that POC unmerged after this lands. Do not reset onto it.

Cut the sentences after the bold result. The incidents stay on the #3205 row, in class (c), and in the (a) table. The owner's #2768 remark was split between the lead and the cycle 22 cell; the cell should carry the whole sentence. "every run was refused" and "input became an object" move into the FIX-1965 cell.

Net −10 against c3175629 (3 insertions, 13 deletions). The tenet 5 sentence, every ledger row, the job list, and the audits stay. This file has no tests. What the deleted sentences said is still in the file: leg b's two failures and both closure ids on the #3205 row, leg b passed under the table, FIX-1872's later path in class (c), the schema and the DevTeam brief in the (a) table, and cycle 22's seen-versus-fixed line in the paragraph under it.

Left the tenet sentence, including the schema / document / tool shapes. That is the sentence this PR asks to approve. Shortening it to "A prompt is a call site too" drops the clause that an instruction is the workaround, and a worker who only reads the tenet would not know which layer. Also left the paragraph under the (a) table and the coherence readout under the job audits.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

Comment thread docs/internal/cycle-ledger/cycle-24.md Resolved
Folds the subtraction proposed in #3485: the bold result stays, the
owner's full #2768 sentence moves into the cycle 22 cell, and "every run
was refused" / "input became an object" move into the FIX-1965 cell.

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

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 15, 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-15T15:24:53.534259Z c81de4f Manual request
ℹ️ 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.

@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: c81de4f0f6

ℹ️ 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 thread docs/internal/cycle-ledger/cycle-24.md Resolved
Comment thread docs/internal/cycle-ledger/cycle-24.md Resolved
Comment thread docs/philosophy.md Resolved
…e approval endpoint

The tenet 5 sentence now applies only when the instruction is right, so a
genuinely missing or wrong prompt can still be fixed in the prompt. Each
cycle 24 row carries its findings' classes, with totals per kind, and the
endpoint note says the owner's merge is the direction approval here.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MJsSFWmTXycBXJU4s96Pk1
@jhoffner
jhoffner merged commit b4be041 into main Oct 19, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants