feat: integrate the Finding Your Unknowns corpus — reference doc, conventions, and contract deltas across 8 plugins - #3592
Conversation
Interview contract for integrating the verified Finding-Your-Unknowns corpus (slice finding-your-unknowns-0f25bd45): round-1 decisions locked (vehicles, binding codification posture, conditional-verdict evidence pass, vertical order, targeted live-doc checks). Brief accumulates as rounds resolve; the Plan section stays empty for /planning:plan. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…sign-off
Operator sign-off (".confirm all", 2026-09-01) closes the interview: the
Brief gains the seven acceptance criteria (sign-off Part G.5), the signed
constraint set (evidence-gate classification, registry discipline, ctx-eng
sequencing, schema stability), and the deferred-questions record with
per-item triggers and arbiters. The signed decision sheet (rev 2, both
final validators folded) is committed beside it as the durable input
contract for /planning:plan, including the operator's delivery amendment:
one session, one branch, one PR, waves as commit ordering.
Register gates clean: registered=17 open=0 answered=17, brief=ok.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…iew) Ten phases sequencing the signed contract: F1 reference doc, governance placements (registry rows, glossary, ctx-eng sequencing bullets), six per-plugin contract-delta phases with same-commit eval expectations, the Wave-3 heavies (E6 port gate, E1/E2 deviation-log convention), and the close-out phase (issues, cheat-sheet check, acceptance verification, the single PR). Includes the durable G-block placement copy, the execution shape (sequential main-session), the gate-passed decisions table, and the Tier-C design-gate early-exit record. A fresh-context plan review is in flight; confirmed findings will amend this draft before execution. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
All 15 reviewer findings verified against the repo and folded: Q7/Q10 cross-refs gain phase homes (wayfind in Phase 7, a new session-flow Phase 9, artifact-design as a prose mention in F1), criterion-1 traceability flips to the corpus-to-sheet direction off a committed disposition ledger, the phase gates switch from affected-tests (which selects nothing for these paths) to check-changed-skills, direct markdownlint, the em-dash ratchet, and the direct register test, the criterion-4 reconciliation and criteria-2-7 walk are recorded, and the sanity-check commands become self-verifying before/after pairs. Waves renumber to 11 phases. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
The graduated reference doc the signed integration contract calls F1: unknowns taxonomy and lifecycle, the five-pass pre-implementation workflow mapped to owning skills, the prompt-pattern catalog, the reply-affordance and export-button owner sections (with conformance surfaces), the opt-in deviation-log convention with its recorded registry trigger, the when-HTML taxonomy and scoping rule, the buy-in pattern with industry grounding, the author's anti-premature-codification warning quoted byte-faithfully with citation stamps, and the behavioral heuristics recorded as eval candidates rather than standing instructions. Fair-quotation permission basis and local citation shape stated in the doc header. lychee already excludes x.com, so no config change rode along. Phase 1 of docs/topics/finding-your-unknowns-integration/PLAN.md; sanity checks green (markdownlint 0 issues, typos clean, section and stamp greps). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
Two names-and-points convention-registry rows (reply affordance, export button) pointing at their owner sections in FINDING-YOUR-UNKNOWNS.md; glossary entries for the unknowns quadrants and blindspot finding types plus a map/territory rejected-terms row, curated per the curate-language entry discipline with a dated provenance note; three "Open, new" candidate bullets and a Phase-10 rebase note recorded in the context-engineering topic PLAN (no phase headings touched); and the acceptance-criterion-1 traceability spine committed into the topic dir - the 48-row V-id disposition ledger plus the delta wording record. Phase 2 of the integration plan; sanity checks green (markdownlint, typos, grep battery, no-phase-touch guard). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
blindspot's output contract gains the four-way finding taxonomy (Landmine / History / Convention / Missing concept) on every card and a closing one-line scan-scope disclosure naming which lanes ran and what was and was not scanned. Adopted at the finding-your-unknowns integration sign-off as team-convention-tier contract lines (D1, D4); rationale and provenance in docs/FINDING-YOUR-UNKNOWNS.md and the topic's signoff-sheet. Evals gain expectations for both lines in this commit; plugin 0.16.18 -> 0.17.0. Phase 3 of docs/topics/finding-your-unknowns-integration/PLAN.md. check-changed-skills green (0 errors). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…resh keys explain: rung-2 terms arrive as vocabulary-ladder entries (term, plain definition, a modeled "you can now say" sentence), and original-ask invocations gain a success condition judged by the user's next prompt (bare comprehension asks exempt by scope). quiz-me: questions are diff-sourced, every question anchors to the report section that teaches its answer with on-miss routing to that exact section, and the embedded answer key is fresh-context authored or verified. Adopted at the finding-your-unknowns integration sign-off (D12, D14, D16, D17a, F4); provenance in docs/FINDING-YOUR-UNKNOWNS.md and the topic signoff-sheet. Evals extended in this commit (including a new original-ask case); plugin 0.8.8 -> 0.9.0. Phase 4 of the integration plan. check-changed-skills green (0 errors). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
Stage 2's intent match now requires naming the existing behavior a change leans on (unchanged code whose contract the diff depends on), and the outcome report template gains a dedicated couplings table with an evidence column. The PR-prep edge case records that a quiz-me comprehension layer may precede the gate while the merge gate stays in confirm, one mechanism per concern. Adopted at the finding-your-unknowns integration sign-off (D19 contract, D18 doc line); provenance in docs/FINDING-YOUR-UNKNOWNS.md. Evals extended; plugin 0.5.10 -> 0.6.0. Phase 5 of the integration plan. check-changed-skills and the em-dash ratchet both green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…isclosure explore-directions: variants bind one identical data set (design is the only variable), the handover closes with a machine-legible direction/steal/skip/next-target reply template, and captures record steal/skip decisions at single-decision granularity so grafts compose. pressure-test: the HTML demo shell gains a validation answer set (forced choices whose options name their costs, free-text escape hatch, copy-out) and a visible fake-data disclosure footer; the capture step carries the filled answers into the durable record. Shared discipline gains the mock-before-you-wire ordering note. Adopted at the finding-your-unknowns integration sign-off (D20-D22, D24-D27); provenance in docs/FINDING-YOUR-UNKNOWNS.md. Evals extended; plugin 0.9.8 -> 0.10.0. Phase 6 of the integration plan. check-changed-skills and the em-dash ratchet both green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…ordering plan: rejected alternatives carry a one-line switch condition; Step 5 closes with pre-drafted one-line revision replies per flagged decision; the sanity-check paragraph names the every-step-lands-green expectation those checks back. interview: free-text answers get a free-text: resolution-field flag (register schema untouched; gate-invisibility recorded as a known limitation in context/loop.md). design: Phase 5 discussion rounds present findings in tweak-likelihood order. brainstorm gains the session-start rationale line, wayfind the five-pass workflow cross-ref. Adopted at the finding-your-unknowns integration sign-off (D28, D32, D33, D35, D36, D9, Q7); provenance in docs/FINDING-YOUR-UNKNOWNS.md. Evals extended for the four contract rows; check-open-questions test suite green; plugin 0.34.15 -> 0.35.0. Phase 7 of the integration plan. check-changed-skills green (0 errors). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
point-dont-copy's audit list gains the cross-stack port trap: a source-side primitive with no target-side analogue whose invariant the port silently drops must name the convention now carrying it, or the finding stands. The skill gains an argument-hint showing the canonical invocation (frontmatter only; description and trigger keywords untouched). Adopted at the finding-your-unknowns integration sign-off (E7, E8); provenance in docs/FINDING-YOUR-UNKNOWNS.md. Evals extended; plugin 0.12.20 -> 0.13.0 (changelog entry provisional, finalized when the same version's E6 port gate lands in the Wave-3 commit). Phase 8 of the integration plan. check-changed-skills green (0 errors). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
One doc line under the at-a-glance diagram: stages 0-3 expand, for unfamiliar territory, into the five-pass order the marketplace repo's docs/FINDING-YOUR-UNKNOWNS.md states with rationale (integration sign-off Q7). Doc-line-only bump 0.34.14 -> 0.34.15; no contract change, no eval delta. Phase 9 of the integration plan. check-changed-skills green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
… (Wave 3) point-dont-copy gains the external-reference port gate as a declared step delta on the shared re-anchor/audit/correct loop: a five-section semantics map (side-by-side pairs, preserved/changed/dropped ledger, edge-case parity, open questions) and a stop-and-wait confirmation gate, scoped to ports whose source of truth lives outside this repo's tree (vendored, foreign-language, other-repo); in-tree corrections stay do-it-now, and the no-analogue trap check feeds the dropped ledger. Verified against the shared method doc before landing: its declared-step-deltas allowance is the exact seam, no correct-forward reversal. Finalizes discipline 0.13.0's changelog entry; a new eval case covers the gate. The implementation plugin's deviation log gains typed entries (plan-confirmed / discovery / deviation / human-decision) with four deviation fields (plan said / found / chose / revisit) in implement-dispatch's owning contract, an interactive opt-in in implement Step 3, and a completion fold-back in Step 5 that reads DEVIATIONS.md and emits plan-amendment bullets. Recorded registry trigger: a second plugin reading the log graduates the contract to an owner doc. No registry row now, per the signed C5/M3. Evals extended in both skills; implementation 0.15.8 -> 0.16.0. Adopted at the finding-your-unknowns integration sign-off (E6 per C3 boundary, E1+E2 per C5); provenance in docs/FINDING-YOUR-UNKNOWNS.md. Phase 10 of the integration plan. check-changed-skills and the em-dash ratchet both green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…rtial) The dated close-out record: both criterion-1 sweeps (48/48 corpus rows, 45/45 sheet-row greps), the criteria 2-7 walk, and the three follow-up issues (#3589 eval candidates, #3590 E4 pitch-view deferral, #3591 recorded triggers). The phase tag stays open until the full affected-tests battery, still running, reports green; the PR follows it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…ition The digest suite caught two things the D28 change touched: the free-text-flag paragraph lands inside the digested open-question-register section of context/loop.md, and the new eval expectation sat in case 12, whose unrelated-reply scenario never has an answer arrive, making the criterion ungradeable there. Per the suite's own contract: both defenses re-read and confirmed intact (the flag adds scrutiny on answered rows and qualifies neither the ask-time write rule nor the gap/blocker register bindings), the expectation moved to case 1 where answers arrive, and the register-section and case-1 digests refreshed in the same change. Suite green (89/0); check-open-questions tests and check-changed-skills green; the battery's 13 other-ecosystem python suites run from their own lane, 785 passed + 330 subtests. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
…ded) All eleven phases DONE; PR #3592 recorded in the close-out record. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
Main advanced with the topic-docs v3.0.0 wave while this branch was in flight, bumping five of the same plugins. Resolution keeps both sides' changelog entries stacked newest-first and re-picks versions so the merged release supersedes both: discovery 0.17.0 -> 0.19.0 (main shipped its own 0.17.0 and 0.18.0), session-flow 0.34.15 -> 0.34.16 (identical-number collision with main's release), planning 0.35.0, verification 0.6.0, and implementation 0.16.0 stand above main's 0.34.16 / 0.5.11 / 0.15.9. Version/changelog parity verified for all eight touched plugins; check-changed-skills, interview-defenses, markdownlint, and the cheat-sheet check green on the merged tree. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
|
Claude finished @kyle-sexton's task in 6m 34s —— View job Code review complete
Finding (posted inline)
Everything else checked outSpot-checked cross-file consistency across the wave-2/wave-3 contract deltas and the accompanying eval/CHANGELOG/version-bump machinery (discovery:blindspot, education:explain/quiz-me, verification:confirm, prototype:explore-directions/pressure-test, planning:brainstorm/design/interview/plan/wayfind, discipline:point-dont-copy, implementation:implement/implement-dispatch, session-flow:workflow):
No other correctness issues found in the reviewed diff. |
|
Claude finished @kyle-sexton's task in 1m 4s —— View job Security review —
|
|
Last security-reviewed head: |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 72a5929c04
ℹ️ 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".
…act slice The topic-docs v3 wave completed the contract-tier burn-down on main while this branch was in flight: docs/topics/ is empty there, the prune gate now red-lines any slice left behind, and the context-engineering topic this branch had annotated graduated to ADR 0004. Close-out per the convention: the durable decision record becomes docs/adr/0025 (evidence chain, classification decision, consequences, recorded triggers), the glossary provenance points at the ADR, the branch's own slice (PLAN, signoff-sheet, disposition ledger, delta record, design resolution) prunes as working material preserved in this branch's history and pasted into the PR body, and the resurrected context-engineering PLAN.md is removed; its three candidate inputs re-home to a tracker issue, since acceptance criterion 5's named target no longer exists on main (deviation recorded in the PR). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
…footer Two Codex review findings, both verified real. The interview free-text flag now applies only to replies that RESOLVE their question (a complete free-text answer, or an explicit "you pick", which resolves to the recommendation); a partial or non-resolving reply keeps its row open under the drift check, so the flag can never launder a non-answer into a terminal answered row. The pressure-test disclosure footer no longer forces inventing production details: it states wiring location and flag when decided, and says "not decided / no flag planned" explicitly otherwise. The interview-defenses register-section digest is refreshed for the reworded paragraph (defenses re-read: the fix strengthens the no-silent-capture posture; suite green 89/0). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
|
Claude has reviewed this PR 5 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
|
Claude finished @kyle-sexton's task in 57s —— View job Security review —
|
|
Claude finished @kyle-sexton's task in 4m 39s —— View job Code review —
|
…rowed rule Review finding: the 0.35.0 bullet still described the flag as applying to any free-text answer, but c69c2e9 narrowed it to replies that resolve their question, with partial or non-resolving replies staying open under the drift check. The bullet now matches context/loop.md. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
… fix Same staleness the planning changelog had: the 0.10.0 bullet still described the pre-fix footer contract; it now records the explicit "not decided / no flag planned" fallback c69c2e9 added. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
|
Claude finished @kyle-sexton's task in 2m 4s —— View job Code review —
|
|
Claude finished @kyle-sexton's task in 2m 38s —— View job Code review —
|
…text rule Review finding: the relentless-me-mode-frontier-rounds expectation still graded the pre-fix, over-broad rule (any free-text answer flagged). It now matches the narrowed loop.md contract: a resolving free-text reply gets the flag, a partial or non-resolving reply keeps its row open. The case digest in interview-defenses.test.sh is refreshed in the same change per the suite's contract; suite green (89/0). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1
|
Claude finished @kyle-sexton's task in 51s —— View job Security review —
|
|
Claude finished @kyle-sexton's task in 1m 53s —— View job Code review —
|

No linked issue
Summary
Lands the signed finding-your-unknowns integration in one PR (operator-directed delivery: one session, one branch): the corpus of Thariq Shihipar's "Finding Your Unknowns" field guide, its X-article methodology substrate, and the 20-demo HTML-effectiveness collection, absorbed as judgment-preserving contract deltas on existing skills plus a citable reference doc — never generator skills, per the source author's own warning, quoted byte-faithfully in the doc and treated as a binding constraint throughout. The decision record is ADR 0025 (
docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md); the branch's contract slice was graduated and pruned per the topic-docs convention (the prune gate), with the approved plan pasted below.Fix
Three waves as commit ordering:
docs/FINDING-YOUR-UNKNOWNS.md(taxonomy + lifecycle, five-pass workflow, pattern catalog, reply-affordance + export-button owner sections with conformance surfaces, opt-in deviation-log posture, when-HTML scoping, buy-in pattern with industry grounding, cautions, eval-candidate heuristics, fair-quotation basis and local citation shape); two names-and-points convention-registry rows; glossary entries (unknowns quadrants, blindspot finding types) + a map/territory rejected-terms row via the curate-language discipline; ADR 0025 as the graduated decision record.discipline:point-dont-copy(semantics map + stop-and-wait confirmation, scoped to sources of truth outside this repo's tree; declared step delta on the shared corrector loop) and the typed deviation-log convention in the implementation plugin (interactive opt-in, completion fold-back, recorded registry trigger).Behavioral-tier heuristics deliberately did NOT land as standing instructions (evidence-gated additions rule); they ship as doc lines + eval candidates tracked in #3589. Deferred items: #3590 (E4 prd pitch-view extension), #3591 (recorded triggers).
Recorded deviations after the base moved (topic-docs v3 wave merged mid-flight):
docs/topics/context-engineering-claude-5/PLAN.mdas the home for three candidate inputs; that slice graduated to ADR 0004 on main, so the candidates re-homed to Context-engineering effort: three candidate inputs + re-inventory note from the unknowns integration #3593 and the branch's edit to that file was dropped rather than resurrecting a pruned slice.docs/conventions/topic-docs/and thecontract-slice-prune-gate; the working material is preserved in this branch's history (last revision72a5929c) and the approved PLAN.md is pasted below.Verification
scripts/check-changed-skills.sh origin/main= 0 failed;scripts/check-purged-em-dashes.shclean; markdownlint 0 issues + typos clean across all changed markdown;node scripts/generate-cheatsheet.mjs --checkexit 0; ai-slop detector 0 findings over the changed set;contract-slice-prune-gategreen after the graduation commit.scripts/affected-tests.sh --run: 2569 assertions passed; the one failure was theinterview-defensesdigest ratchet correctly catching the D28 edit inside its pinned register section — defenses re-read and confirmed intact, the eval expectation moved to a gradeable case, digests refreshed per the suite's own contract, re-run green (89/0). The 13 other-ecosystem python suites run from their own lane: 785 passed + 330 subtests (the PowerShell suite is the Windows CI lane).Approved PLAN.md (contract slice, pruned per the topic-docs convention; last in-tree revision 72a5929)
Related
Refs #3589, Refs #3590, Refs #3591, Refs #3593. Decision record:
docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md(this PR); incumbent context-engineering record:docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md. Full working material (signoff-sheet, disposition ledger, delta record, verbatim PLAN): this branch's history at72a5929c.🤖 Generated with Claude Code
https://claude.ai/code/session_01GE7YPqWwqGSNYfVWj8DdF1