Opus 4.7 prompt audit — remediation backlog

[virtualian]

Context

Audit of PAI prompts against Anthropic's published Opus 4.7 guidance (2026-04-17). Anthropic's own framing: "more literal instruction following; will not infer requests you didn't make; stricter effort calibration; fewer tool calls / subagents by default; more direct tone, fewer emoji; prefer positive over negative framing."

Full audit report: reports/20260417-opus-47-pai-prompt-audit.md (local, not yet committed).

Primary sources verified:

• https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7
• https://platform.claude.com/docs/en/about-claude/models/migration-guide
• https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
• https://www.anthropic.com/news/claude-opus-4-7

Findings

Critical (shipped-surface — affects every installer):

• C-1 (won't fix — misdiagnosis; see comment, 07a08d6) — loadAtStartup in .claude/settings.json references two files that don't exist in runtime or shipped release:
  • PAI/USER/AISTEERINGRULES.md
  • PAI/USER/PROJECTS/PROJECTS.md
  • Fix: remove from loadAtStartup.files list, or ship empty placeholders.
• C-2 — PAI/Algorithm/v3.7.0.md:27 says "When in doubt, invoke MORE capabilities not fewer." Anthropic's 4.7 migration guide documents the opposite default ("Fewer tool calls by default… Fewer subagents spawned by default; steer explicitly").
  • Fix: decide policy — if PAI genuinely wants more-not-fewer under 4.7, say so explicitly with a motivated rationale; otherwise invert.
• C-3 — Format inventory disagreement: ~/.claude/CLAUDE.md:50 lists three formats (ALGORITHM, NATIVE, MINIMAL); Algorithm/v3.7.0.md:7 lists four (adds ITERATION).
  • Fix: pick one authoritative list, have the other file reference it instead of restating.
• C-4 — "Euphoric Surprise — 9-10 ratings" goal (Algorithm:3, 70, 403, 430; SKILL.md:41, 70, 403, 430) collides with 4.7's documented shift: "more direct tone, fewer emoji, less validation-forward phrasing."
  • Fix: design decision — keep the framing with a documented rationale, or retire it in favour of the underlying ISC/verification mechanism.

High:

• H-1/H-2 — Imperative-verb inflation (~26 absolutes in Algorithm/v3.7.0.md; ~19 in 96 lines of AISTEERINGRULES.md). Anthropic's current prompt guide recommends motivated positives over bare negatives (canonical example: NEVER use ellipses → Your response will be read aloud by a text-to-speech engine, so never use ellipses…). Pass each negative rule through that rewrite.
• H-3 — "FIRST THING" (Algorithm:148) vs "FIRST ACTION" (Algorithm:152, 335, 348, 373, 394, 401, 428) ordering conflict at every phase entry. Pick one.
• H-4 — Algorithm:111 "every decision happens within Algorithm phases" vs Algorithm:196-199 FAST-PATH permitting phase-skipping. Either FAST-PATH is a formal Algorithm subset, or ALL-WORK-INSIDE needs an explicit FAST-PATH exception.
• H-5 — Stale ~/.claude/PAI/… paths (verified broken):
  • Algorithm/v3.7.0.md:463 — ~/.claude/PAI/PRDFORMAT.md
  • PRDFORMAT.md:143 — same
  • SKILL.md:445 + SKILLSYSTEM.md:227 — ~/.claude/skills/Science/Protocol.md
  • SKILL.md:409 + SKILLSYSTEM.md:832 — ~/.claude/PAI/THENOTIFICATIONSYSTEM.md
  • Fix: search-replace and confirm each target either exists or the reference is removed.
• H-6 — Atomic-scope lock (AISTEERINGRULES:54) vs capability-invocation floor (Algorithm:27) collide for atomic requests. Document precedence.
• H-7 — Algorithm:113 claims "Entry banner was already printed by CLAUDE.md" but CLAUDE.md contains no banner string. Either add the banner to CLAUDE.md or strike the assumption from Algorithm.
• H-8 — ~/.claude/CLAUDE.md:48 typo: "completes.Critical Rules" — missing newline.

Medium:

• M-1 — Fixed 8-word / 8–12-word mandates in Algorithm + PRDFORMAT conflict with Anthropic's 4.7 change Create Diataxis Documentation Pack #1 ("Response length varies by perceived task complexity; remove fixed-verbosity scaffolding").
• M-2 — FAST-PATH and SCOPE GATE overlap with undefined precedence.
• M-3 — Unverifiable quality rules (Euphoric Surprise, low-affect, intellectual honesty, high agency) — the model can't self-check these; under 4.7's "will not infer" posture they carry less weight than before.
• M-4 — Algorithm:7 vs Algorithm:8 ordering (response-format-first vs question-at-end) — resolution exists but buried; surface it more clearly.
• M-5 — Skill trigger ambiguity from intent-only matching (SKILLSYSTEM.md:571). Under 4.7's literal reading, overlapping trigger domains (Research / Investigation / Security) may mis-route.
• M-6 — SKILL.md:33 says "'just' does not reduce depth"; AISTEERINGRULES.md:54 uses "just" as a scope-lock trigger. Opposite weights for the same lexical cue.
• M-7 — Time-budget auto-compress (Algorithm:31) vs ALL-WORK-INSIDE (Algorithm:111) — document precedence.

Low:

• L-1..L-4 — Cosmetic inconsistencies in MEMORY.md index; phantom-capability removal-escape-hatch visibility; voice-notification failure handling; CRITICAL/MANDATORY applied to structural rules at algorithmic intensity.

Suggested sequencing (effort:payoff)

1. Low-effort quick wins: C-1, C-3, H-5, H-8 — file/path/typo fixes, low risk.
2. Policy decisions: C-2, C-4, M-1 — these aren't bugs, they're choices that need an owner.
3. Structural: H-1/H-2/H-3/H-4/H-6/H-7 — systematic pass through the Algorithm file.
4. Polish: the Medium and Low bucket.

Acceptance

This issue closes when each checkbox above is either (a) fixed with a commit reference or (b) marked "won't fix" with a one-line rationale.

[virtualian]

C-1 resolution — won't fix (misdiagnosis)

Live verification of LoadContext.hook.ts:92-97 shows the hook already handles missing loadAtStartup entries gracefully (existsSync guard + stderr warning + continue). The missing files are intentional user-override slots, documented in Releases/v4.0.3/.claude/PAI/SKILL.md:442 (USER rules) and :472 (PROJECTS registry).

The audit confused soft-loading for a bug. Commit 07a08d6 updates the _docs field in the shipped settings.json template so the optional-slot intent is discoverable without reading the hook.

Side-discovery (not this issue): v3→v4 path migration changed skills/PAI/USER/… to PAI/USER/…; config-gen.ts references the path but doesn't appear to create placeholders. Worth a separate ticket if we want the installer to drop stubs or a README.

Closing C-1.

[virtualian]

Deferring this audit-backlog. C-1 was resolved and landed separately (commit 07a08d6). Remaining 22 checkboxes are parked; reopen when prioritised.