docs(playbooks,philosophy): ship DOC bundle 1 — surface-scoped claims, effort lane rules, Haiku delegation boundary - #1885
Conversation
…e effort ladder by lever order Three evidence-forced corpus rows land where this repo's model- and effort-routing doctrine already lives, rather than in the fable-5 playbook: that playbook's own chapter contract routes model-specific facts out to `context/model-adaptation/` (one file per model VERSION, audience-scoped), and a session model cannot lower its own effort mid-session, so a second effort-doctrine home would be the silent parallel way the convention registry's one-owner rule forbids. DOC-9 — §Model tiers. The tier table carried `Bulk mechanical sweeps | Haiku 4.5` with no capability rationale and so no stated boundary. Interleaved thinking is the one capability that does not travel down the ladder: a delegated task whose value is reasoning about intermediate tool results needs a model that interleaves; one that merely chains tool calls does not. Phrased by capability rather than family name, so it survives an alias moving under it. The narrowing matters and is stated: upstream is explicit that "Consecutive tool calls do not require interleaved thinking", so a non-interleaving model still chains tools and still completes a sweep — the bottom tier row stands, and only stops short of a fan-out whose worth is judgement between calls. DOC-13 — §Effort tiers grounding. Thinking is adaptive: the model decides per request whether and how much to think, the caller sets intent and optionally effort. So a lane pin is a posture, not a switch, and a turn carrying no thinking is the mechanism working rather than a pin misfiring. DOC-11 — §Effort tiers lane rules. The section already carried the RAISE direction and a cache caveat. Three genuine deltas: the reduce direction, which is the one upstream states outright, with the Warning's rationale that a level is a calibrated control where wording is not; per-message steering as the cache-safe escape hatch, which the cache caveat did not carry at all; and the effort-stability convention that falls out of it. Two deliberate restraints, both recorded in the prose so a later editor does not undo them. The cache text states the OUTCOME and refuses the mechanism: the platform page says the resolved effort value is rendered into the prompt, Claude Code's docs say effort is part of the cache key and not part of the prompt text — identical outcome, incompatible stated why, so naming one asserts more than either source supports. And the stability rule says "natural breaks", never `/clear`: the `/clear` naming appears only in the campaign slice's own candidate wording and is unsourced, where the harness Tip it derives from says `/compact`. Every restated volatile specific carries the four-part upstream-drift record. Sources re-fetched as raw markdown and verified this session, 2026-08-03: platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost.md (40477 bytes, byte-identical to the corpus slice snapshot), .../thinking.md (52769 bytes), code.claude.com/docs/en/model-config.md (83644 bytes). Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…face travels with it DOC-19, the corpus row its slice called "the single most transferable output" and the one that prevents the misreading that material most invites. The rule: a behavioral claim about Claude is a fact about the surface documenting it, never about the surface the session runs on. Consumer claude.ai and mobile, the raw API, and this harness are different products with different tools, memory, and system prompts. Same-vendor documentation is the easiest scope error to make precisely because it never feels like an inference — vendor authority is what makes the slip invisible. Lands in `context/calibration.md`, which owns claim grading, rather than `context/trust-and-authority.md`, which owns where an INSTRUCTION draws authority from; this is a factual claim's scope, not an instruction's standing. Both worked divergences ship, and both are stamped to their exact entry rather than stated in the present tense: - "Claude does not retain information across chats" — Claude Opus 4.1 entry, dated August 5 2025 — against Claude Code's two documented cross-session mechanisms, CLAUDE.md files and auto memory. - "Claude cannot open URLs, links, or videos" — Claude Sonnet 3.5 entry, dated November 22 2024 — against the documented `WebFetch` tool. The dating is not bookkeeping. Verifying the two claims at the source established that NEITHER sentence survives in a current entry: the first disappears after Opus 4.1, the second after Sonnet 3.5, with no reworded survivor at any later entry. Left present-tense they would have been exactly what this repo's own I19 names — a claim about the past told in the present tense — inside a repo that ships the scanner for it. Carried as dated, the staleness becomes the rule's second half instead: wrong surface and stale entry are independent errors, and clearing only the first still leaves you quoting a retired prompt. The chapter says so, and the third RULE generalizes it — a dated archive is scoped to its date as well as its surface. One wording correction against the row text, which called these "contradictions". They are divergences: a consumer prompt describing claude.ai and a memory doc describing Claude Code were never two claims about one surface, which is the card's own thesis. SKILL.md carries the distilled line under core doctrine, "Ground truth and checking — calibration", per the chapter/core-doctrine pairing that file follows throughout. Verified 2026-08-03 by raw-markdown fetch: the published system prompts (platform.claude.com/docs/en/release-notes/system-prompts.md, 471033 bytes, sentences located at :1427 and :2180 with occurrence counts across all entries), code.claude.com/docs/en/memory.md (35388 bytes, :9), and code.claude.com/docs/en/tools-reference.md (87836 bytes, :60 — note the WebFetch tool table is there, not in settings.md or iam.md). Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 4m 26s —— View job Code review — PR #1885Tasks
SummaryDocs-only PR (98/-5 across 5 files). No code, no security-relevant surface — the code-review lane's "always check" items (audit-log completeness, atomicity across multi-file writes) don't apply here; nothing for the security lane either. I independently re-fetched the three external sources this PR cites in
All citations check out exactly against the live pages — no stale or misattributed claims found. Other checks:
I wasn't able to run No correctness or maintainability findings. This is a clean, well-sourced documentation change. |
|
Claude finished @kyle-sexton's task in 1m 10s —— View job Security review complete
No security issues found. This PR is a documentation-and-doctrine-only change:
None of the changed files contain shell commands, GitHub Actions workflow definitions, hook contracts, |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9ef8a30a75
ℹ️ 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".
|
Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
…and the interleaving rule to extended reasoning Both Codex P2 threads on #1885 are correct. Neither row's thesis changes; both shipped sentences over-generalized past what their sources support. PRRT_kwDOTCGFQM6WAwM3 — the always-loaded SKILL.md line said a behavioral claim is "never" about the surface you are running on. False in the identity case: an agent running in Claude Code reading Claude Code's own docs has documenting surface == target surface, and the rule as written denied it. The owning chapter was already narrower ("a claim crosses between them only after a per-claim check"), so the two surfaces of one rule disagreed, and the always-loaded one was the wrong one. DOC-19's source thesis is cross-surface transfer — sysprompt CA-1 reads "claude.ai/mobile consumer-prompt claims never transfer to the harness without a per-claim check" — so the "never" belongs to the TRANSFER, not to the identity. The line now says the claim transfers only after a per-claim check, never on vendor authority alone, and names the same-surface case as clearing where it stands. The chapter's RULE gains the same explicit pass, which also answers the thread's second concern: naming the surface IS the check, so a same-surface claim is not redundantly re-verified. PRRT_kwDOTCGFQM6WAwM9 — the DOC-9 text said a non-interleaving model "lacks reasoning about each result before choosing the next call". That converts a narrow limitation into a general inability, and it contradicted the very quote sitting two lines above it. Re-read at the bytes (thinking.md:746-762, refetched raw): the Note says "Consecutive tool calls do not require interleaved thinking. Claude can chain tool calls with or without interleaved thinking; interleaving changes where thinking blocks appear between tool calls, not whether tool calls can chain." What the capability adds is a thinking block at the seam; what its absence removes is deliberation at that point — not the tool result from context, and not the ability to act on it. Note the doc's own lead sentence (:748) uses the looser "reasoning about each tool result" framing that this text had echoed; :755 is the doc correcting itself, and the tighter reading is the honest one. The routing rule tightens with it. It now requires interleaving only where extended reasoning between results is load-bearing — a mid-sweep judgement that must change what gets called next — instead of wherever results are reasoned about at all. That un-excludes the case the thread named: straightforward triage and research passes that decide at the end keep the bottom tier row, and only deliberation partway through leaves it. The capability's one-line definition is aligned to match ("a thinking block between tool calls", not "reasoning between tool calls"). CHANGELOG 0.6.3 is unreleased, so the correction folds into its existing entry rather than adding a version; that entry carried the same "never" wording and is fixed too. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Claude finished @kyle-sexton's task in 1m 18s —— View job Code review — PR #1885 (re-review after push)Tasks
SummaryCommit 1. SKILL.md over-generalized "never" (Codex thread on Before: "A behavioral claim about Claude is a fact about the surface documenting it, never about the one you are running on." That's false in the identity case Codex named — an agent in Claude Code reading Claude Code's own docs has documenting surface == target surface. After (SKILL.md:47): "...it transfers to the surface you are running on only after a per-claim check — never on vendor authority alone... Docs for your own surface clear that check where they stand; a claim from another surface... is a hypothesis until checked." This now matches the narrower rule already present in 2. Interleaving requirement over-generalized to all reasoning (Codex thread on Before: "a task that merely chains tool calls does not [need interleaving]... what it lacks is reasoning about each result before choosing the next call." That excluded ordinary triage/research sweeps that reason at the end, not just mechanical chaining — exactly Codex's point. After (PLUGIN-PHILOSOPHY.md:584-591): "require interleaving only where extended reasoning between tool results is load-bearing — a mid-sweep judgement that has to change what gets called next. A task that chains calls, or that reasons over its results at the end, does not need it." This now tracks the cited source text precisely ("interleaving changes where thinking blocks appear between tool calls, not whether tool calls can chain") instead of contradicting it. The capability's one-line definition at line 573 was also tightened from "reasoning between tool calls" to "a thinking block between tool calls," consistent with the fix. Correctly resolved. Other checks on this commit
No further findings. Both fixes are correct, sourced, and don't reopen the concerns the original review already cleared (citations, version bump, changelog parity). |
|
Claude finished @kyle-sexton's task in 1m 13s —— View job Security review complete
No security issues found. This PR remains a documentation-and-doctrine-only change; the latest commit (
None of the changed files contain shell commands, GitHub Actions workflow definitions, hook contracts, |
…undary in the docs profile (#1888) Lands two adopted Sitting-2 decisions in the anthropic-docs publisher profile — the campaign's consumer-facing tag-selection doctrine. `knowledge` 0.10.16 -> 0.10.17. ## PA-M — the harness-surface definition New bullet appended to the near-miss rule: **a harness surface is a surface a user can reach**, with three non-falsifying sub-shapes that harness-doc text can take without establishing one. Both the definition sentence and sub-shape (3) carry explicit `[campaign-owned amendment]` labels — the record shows the campaign making the selection-over-support choice, not inheriting an adjudication. Sub-shape (3) rests on its single attested instance (`env-vars.md:394`, a retry/fallback row) and carries its own over-broadening boundary: a doc line describing some *other* model's tier fails the sub-shape's own test. The landing site was derived three independent ways: the profile already uses "harness surface" as its negative-claim term (`:34`, `:54`); the adopted row's own text says "write into the profile"; and the 0.10.16 CHANGELOG deliberately held this exact question (J-12) for the dispositions interview this answers. ## PA-V — the bare-name boundary The `cc-applicable`/`mixed` boundary bullet now carries the fourth API surface (**model ID**) and the negative half the profile never stated: **bare names are not API surfaces** — a product name, display name, or docs-path slug never by itself triggers `mixed`. Ratified from the de facto standard 15+ rows already stood on (cross-vendor retag applied in-slice). Deliberately excluded: a `[campaign-owned amendment]` label (this ratifies an evidence-carried standard, not a campaign-invented definition) and "feature names" (present only in one slice's wording, not the adopted row — widening the enumeration would exceed the adopted authority). ## Verification Both commits independently verified by a second model with the implementer's rationale withheld: the PA-M landing audited across landing-site derivation, amendment fidelity (verbatim vs the adopted blockquote), self-fire (no profile or checklist conflict; no live campaign artifact violates the definition), and mechanics; the PA-V text was *authored* by that verifier from the adopted row and applied verbatim, with the producer re-confirming the authority citations at the bytes before editing. The one enumeration of the API-surface list repo-wide is this bullet — no drift introduced. markdownlint 0 errors; CHANGELOG newest-first, both entries folded into the unreleased 0.10.17. Downstream, already discharged against these rules: the four slice-local `api-only` ratifications (memory-tier) now cite the landed definition and route their three disclosed near-miss hits per these bullets. No linked issue ## Related - Sitting 2 of the doc-corpus decision block, ADOPTED 2026-08-03 after adversarial validation (21/21 CONFIRMED); PA-M ordered first carrying its amendment flags, exactly as the adoption block specifies. - Siblings this session: #1881, #1882, #1884, #1885, #1887 (open); standards#311 + ADR-0002; dotfiles#394, #399 (open). - The J-12 hold this closes: `knowledge` 0.10.16's CHANGELOG (PR #1879). --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…1, effort dial seam (#1887) Ships DOC bundle 2 of the doc-corpus campaign: DOC-6 and DOC-12 (thinking cost doctrine, rewritten against the EC-1 finding), DOC-10 (effort extend-or-cite deltas), DOC-8 (the two-dials seam). `playbooks` 0.6.3 -> 0.6.4. ## The EC-1 rewrite — the load-bearing change The thinking cost doctrine (fable-5 `context-economy.md` + one distilled `SKILL.md` line) states the harness override as **build-pinned behavior**: Claude Code sends `clear_thinking_20251015 keep:"all"` on every thinking-enabled request, on keep-all AND last-turn-only models alike — prior-turn thinking is retained and input-billed everywhere. The per-model keep-all/last-turn split is presented only as what a raw API caller gets, beside the override. The full four-part record ships: claim, basis (wire-captured request bodies, build pinned by byte size), as-of 2026-08-03, recheck trigger (any CC upgrade — the override is a build-time constant, not a documented contract), plus the three gating conditions and both escapes (`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`; a gateway dropping the field) under which per-model defaults resume. Observation and inference kept apart: the wire proves retention; input-billing is upstream's rule applied to it. ## The other rows - **DOC-10:** genuine deltas only — the harness corroboration + confirmation-dialog fact into §Effort tiers (A3/A4 already shipped); `opus-5.md`'s campaign-internal "Phase 6 cross-check" deferral replaced with live Effort/model-config pages that actually own per-model starting levels, preserving the TRUNCATED finding. - **DOC-8:** thinking and effort as two separate dials (`adaptive` is a thinking mode, never an effort value; effort is soft guidance, `max_tokens` the only strict limit) landed in the effort-doctrine owner where the frontmatter `effort` trap is reachable. Pins untouched — they move only through the dotfiles seam, per the row's own text; the consumer-state drafts are in the campaign's memory tier. - **Self-corrections shipped as follow-up commits (append-only):** one retracted drift claim (the corpus sentence survives verbatim at the live page — the original dispute was wrong) and one carry of the build pin onto the always-loaded surface plus removal of a session-residue sentence. ## Verification Independently verified cold by a second model (the implementer's report was lost to a session interruption; the audit ran from the diff and primary bytes alone). Every quoted fragment re-verified verbatim against raw fetches with byte-size pins matching the commits' own records; the build pin re-verified live (same byte count, so the as-of stamp holds); zero surviving unqualified keep-all claims; nothing trips catalog rows I17-I22/I19/I8-b; playbooks 0.6.4 + CHANGELOG parity/order/bump green; markdownlint 0 errors. **Ledger note (immutable commit message):** `00dc30749d` says "DOC-12 supplies the three buckets"; the shipped section carries two of the pricing page's three — ordinary output-token billing is the pointer's job, not restated. Recorded here per the campaign's history-stays-immutable practice. No linked issue ## Related - Phase 3b DOC chapters; bundle 1 merged as #1885; siblings #1881, #1882, #1884; standards#311 + ADR-0002; dotfiles#394, #399 (open — bundle 2's dotfiles Draft 1 now carries an explicit apply-on-top-of-#399 dependency note). - EC-1 empirical record: `EC-1-PROCEDURE-REPAIR-2026-08-02.md` + interview-checklist ratification (memory tier). --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…uthority, consistency rationale (#1893) ## Summary DOC bundle 3 of the doc-corpus application campaign — three evidence-forced rows, one playbooks bump (0.6.5 → 0.6.6): - **Verification surfaces table** (`fable-5/context/verification.md`): six-row map of the built-in verification surfaces to their canonical pages — spanning the harness, the managed Code Review service, and the Managed Agents platform API — including the one source item nothing implements (spec validation, shipped as a dated absence with a recheck trigger). Closes with the invocation/plan/version caveats that make "built-in" not mean "automatic". - **Channel-authority routing rule** (`fable-5/context/calibration.md` + one SKILL.md distillation line): the reference page that owns a term defines it; a vendor post corroborates — written once, never revised, and what it omits is invisible from inside it. Worked instance: the glossary's verification-loop entry carries the prerequisite-for-`/goal`/unattended-runs/dynamic-workflows fact a post-length definition drops. The paired glossary-row half of this row targets a graduated-corpus surface that does not exist yet and is deliberately unlanded. - **Consistency rationale for decomposing** (`fable-5/context/orchestration.md`): output consistency recorded beside context economy as the second rationale — fewer inconsistency errors across scaled workflows — with the tiebreak consequence, mechanism-agnostic, and deliberately in exactly one place (no SKILL.md line). All canonical URLs and anchors re-verified live 2026-08-03 in both raw-md and rendered forms. Independently verified (fresh-context, rationale withheld): FIX-FIRST with three one-line wording findings, all applied in `8786a772ec`; no blockers. No linked issue ## Related - #1885, #1887 — DOC bundles 1 and 2 (same evidence-forced class and delivery shape) - #1891 — the playbooks rehost this bundle's version bump follows (0.6.5 → 0.6.6) 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011UarawwEnZQu7cB6i7WatJ --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…s, residual-risk footer (#1898) ## Summary DOC bundle 4 of the doc-corpus application campaign — the three unblocked rows (playbooks 0.6.6 → 0.6.7; knowledge 0.10.19 → 0.10.20): - **Point at a per-model matrix; never copy one** (`fable-5/context/calibration.md` + one SKILL.md line): a third source-grading axis (volatility) beside the surface and channel axes — point at the vendor page that owns a per-model table; a stated matrix carries a re-check trigger naming the next model release; table presence is not reachability where you run. Worked instance corrected at the bytes: Claude Mythos 5 is a known registry model with full gating machinery and still not selectable — exactly one non-null provider id beside **seven** null siblings (the earlier "all eight null" figure was schema-disproven; the correction and its reason are in the CHANGELOG). - **Archive-reading conventions** (knowledge profile): a dated entry is not a content-change signal (two byte-identical entries five days apart prove it); absence of bold does not prove absence of change — deltas come from diffing entries, never reading markup; note a source artifact at the row, never silently repair it (with the one reader-facing exception stated). Recheck against the UNC-1 ruling confirmed no premise moved — the ruling touched tags, these are page properties. - **Residual-risk footer** (knowledge profile): the reduce-hallucinations page's own hedge, quoted verbatim (byte-compared live), scope unbroadened — hallucinations only, no validator named — with the cite-never-restate rider for graduated chapters. Fourth commit removes a cross-plugin dependency claim and an internal-record pointer from the knowledge CHANGELOG (self-caught; disclosed). Independently verified (fresh-context, rationale withheld): SHIP, zero findings — EC-3 seven-count, UNC-1 no-retag ruling, byte-identical-entries evidence, and the footer byte-compare all re-derived by the verifier. No linked issue ## Related - #1885, #1887, #1893 — DOC bundles 1-3 (same campaign, same delivery shape) - #1895 — the doc-queue repopulation this bundle's knowledge bump follows (0.10.19 → 0.10.20) 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011UarawwEnZQu7cB6i7WatJ --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Ships DOC bundle 1 of the doc-corpus campaign — the zero-gate set: DOC-19, DOC-11, DOC-13, DOC-9.
playbooks0.6.2 -> 0.6.3 (covers the DOC-19 chapter change; thedocs/PLUGIN-PHILOSOPHY.mdrows follow the repo's convention of not versioning repo-level doctrine — precedent a09efd7, 970d0cb).What ships where, and why there
plugins/playbooks/skills/fable-5/context/calibration.md, new section "A claim's product surface travels with it": claude.ai/mobile consumer-prompt claims never transfer to the harness without a per-claim check. Placed in calibration (claim grading), not trust-and-authority (instruction authority). One distilled line added to fable-5SKILL.mdcore doctrine.docs/PLUGIN-PHILOSOPHY.md§Model tiers and §Effort tiers — NOT the fable-5 context tree, by that tree's own rules: fable-5SKILL.mdexcludes model-version claims from its chapters ("live only undercontext/model-adaptation/"), those files are per-model-version audience-scoped, and §Effort tiers already owns effort doctrine (a second home would violate the one-owner rule). DOC-9 gives the tier table'sHaiku 4.5row its missing capability boundary (no interleaved thinking — reasoning-about-tool-results delegation needs an interleaving model; mechanical fan-out does not, and consecutive tool calls still chain without it). DOC-13's adaptive-thinking mental model grounds what a lane pin buys; DOC-11 adds the three genuinely missing lane rules.Deviations from the row text, each evidence-forced
system-prompts.md:1427); the cannot-open-URLs sentence under Sonnet 3.5 (Nov 22 2024,:2180); zero later occurrences or reworded survivors (471,033-byte snapshot, swept twice independently). Shipping them present-tense would have been the exact defect class this repo's own catalog flags. Also reworded "contradictions" -> "divergences" — the card's own thesis is that a claude.ai claim and a Claude Code doc were never two claims about one surface.model-config.md:677carriesinterleaved_thinkingas an admin-declared capability string; the per-model Haiku fact lives at platformthinking.md:758, with the:755narrowing ("Consecutive tool calls do not require interleaved thinking") stated in the row's favor./clear(unsourced; the harness Tip says/compact)..work/slice directories no consumer has. The mental model ships; the navigation stays in the campaign's own index.Consumer-state halves
Drafted, not committed:
.workmemory-tier drafts for the dotfiles seam (three CLAUDE.md additions with verbatim before-texts verified against dotfiles origin/main, routes, and the never-chezmoi applyconstraint). They land in a separate batched dotfiles PR.Verification
Independently verified by a second model with the implementer's rationale withheld: all four placements' cited grounds confirmed at the bytes; both staleness re-datings replayed (7 and 9 occurrences, zero later); all three DOC-11 deltas and both restraints verified at both platform and harness sources (live pages byte-identical to the corpus snapshots where claimed); the DOC-13 refusal and the cite-swap in the triage row confirmed; the versioning question adjudicated against repo precedent. Sources re-fetched raw this session with recorded lengths. markdownlint 0 errors;
check-changed-skills.shPASS; changelog parity/bump/order pass.No linked issue
Related