Opus 5.5: Why Your Old Prompts Need an Upgrade
Table of Contents
A new model is not only a faster or smarter version of the old one. It also reads your prompts differently. A line that helped an older model can make a newer model worse. This post explains what matters in Claude Opus 5.5, how to find the old lines in your prompts with one command, and how I used both to upgrade a real agent workflow.
1. What Changed in Opus 5.5
Opus 5.5 is different from older models in three ways:
- It works longer on its own. It can carry a big change, step by step, until the tests pass. It is best at long, multi-step work.
- It always thinks before it replies. You cannot turn thinking off. The model decides how much to think. You control this with the effort setting, not with words in the prompt.
- It reports clearly. At the end of a run, its summary says what it did, what it found, and what it needs from you.
It also follows instructions more closely and more literally than older models. This is good when your instructions are right. It is bad when your instructions were written to fix problems that the new model does not have.
2. Why Your Old Prompts Need Attention
Most prompts, skills, and CLAUDE.md files grow over time. Someone adds "think carefully" because an old model rushed. Someone adds "ALWAYS" in capital letters because an old model ignored a rule. These lines worked then. On Opus 5.5 they often cause the opposite problem.
| Old line | Why it was added | What it does on Opus 5.5 |
|---|---|---|
| "Think hard" / "think step by step" | Old models did not always think | Nothing useful. The model always thinks. Use effort instead. |
| "Find at least one issue in every file" | Old reviewers said "looks good" too fast | The model invents problems to fill the quota. |
| "Check ALL of the following" in capitals | Old models skipped rules | Over-applies the rule, even where it does not fit. |
| "Do not stall" | Old models stopped too early | Can push the model to stop or escalate too early. |
The lesson is simple: a prompt is written for one model. When the model changes, you must read your prompts again.
3. What to Change in Your Prompts
Anthropic's guide for Opus 5.5 gives a short list of changes. These are the ones that matter most for agent work:
- Say what "done" means. Give the whole task in one message, the finish line, and when to stop and ask.
- Delete "think hard" lines. To make it think less, lower the effort first.
- Say when to stop. Opus 5.5 sometimes stops only to report progress or to offer choices. Tell it the few real reasons to stop, for example before a destructive action.
- Split big work across subagents. For audits, migrations, and large reviews, give each part to its own subagent, and check each subagent's evidence.
- Keep the task list in a file. In a long run, old turns get summarized. A file stays.
- Ask it to mark what it could not confirm. "Mark anything you couldn't confirm, and say where you looked."
- Read "what it needs from you" first. Ask for a summary that starts with open decisions.
Here is an example of a good task prompt for Opus 5.5:
Migrate the payment endpoints from the old client to the new one.
Done means: every endpoint uses the new client, the old client is
deleted, and the test suite passes.
Stop and ask me only if a test fails for a reason you can't explain.
And a stop rule you can put in CLAUDE.md:
When a step doesn't need my input, keep going. Put status notes in the
same message as your next action.
Stop and ask only when you can't continue without me, or before anything
destructive: deleting data, force-pushing, or changing anything outside
this repository.4. Upgrading Prompts with /claude-api prompt-audit
Reading every prompt by hand is slow, and it is easy to miss things. Claude Code ships a built-in claude-api skill, and it has a command made for this job: prompt-audit. It looks for old prompt text ("cruft") that was written for older models and now hurts newer ones.
How to run it
Run the command alone to audit the whole working directory. Or add the files and the target model in plain words:
# Audit everything that reaches the model in this repo
/claude-api prompt-audit
# Or name the scope and the target model
/claude-api prompt-audit .mitra/agents/architect/workflows/challenge-me.md for Opus 5.5The audit does not stop to ask you questions. If you do not name the scope or the model, it chooses them from the repository and writes its choices at the top of the report. If a choice is wrong, run it again with a narrower request.
What it does, step by step
- Scope and target model. Which files to check, and for which model.
- Inventory. It finds all text that reaches the model: system prompts, skill files,
CLAUDE.md, tool descriptions, and the code that builds requests. - Provenance. It uses
git blameto see why a line was added, and for which model. - Scan. It compares each line with known old patterns in four groups: dated prompt text (pressure words, "think step by step", over-detailed scripts), brittle skill files, tool descriptions, and request settings.
- Report. Each finding gets a location (
file:line), the pattern, the reason, a confidence level, and an action. - Proposed diff. Only medium- and high-confidence findings get an edit. Low-confidence findings are only reported.
What it will not touch
A good audit is not a "make it shorter" tool. The skill keeps a list of things it must not delete: context that only you know (your product, your users, your quality bar), exact scripts for dangerous steps, tool contracts, and rules against failures that still happen. And if the prompt is clean, the diff is empty. Nothing is changed just to show a result.
After the audit
Treat each removed line as a guess, not a proven fix. Try the prompt on a small real task before and after. If a cut makes things worse, add the rule back in a short, simple form. And run the audit again at every new model release, because a prompt is written for one model.
5. Why a Challenge-Me Workflow Matters
When you write a design, an ADR, or a plan, you are the worst person to review it. You know what you meant, so you read what you meant, not what you wrote.
challenge-me is a review workflow from my Mitra agent framework. It runs one review session with two voices:
- Jamshid (Architect) presents the material and defends it.
- Kaveh (Engineer) reads it and challenges it: missing edge cases, contradictions with the code, unclear terms, security gaps.
They debate each point until they agree. They fix the files as they go. If they cannot agree after three rounds, they ask you, with clear options. You get a design that has already been attacked from the other side, before a real teammate reads it.
This kind of session is long, and it changes files. That is exactly where Opus 5.5 is strong, but only when the prompt gives it a clear finish line, clear stop rules, and a way to track progress. The old version of the workflow gave none of these.
6. How Challenge-Me Was Upgraded
The upgrade had two rounds: first, apply the lessons from the Opus 5.5 guide. Second, run /claude-api prompt-audit on the result.
Round 1: the lessons from Opus 5.5
Each lesson was added in one place only, so the workflow does not repeat itself:
| Lesson | Where it went |
|---|---|
| Say what "done" means | Session Start points to the Session End criteria: "Do not stop before it." |
| Say when to stop | The Escalation Protocol is now the only list of stops: a deadlock, or a destructive action. |
| Keep the task list in a file | A ledger inside the summary file that already existed. No new file. |
| Split big work across subagents | Kaveh's Read step. Kaveh checks each subagent's evidence himself. |
| Show how it fails | A new line in the objection format: a concrete input or sequence that breaks. |
| Mark what you could not check | Engagement rule 3: mark it UNVERIFIED and say where you looked. |
| Settled answers stay settled | An agreed item opens again only when new evidence contradicts it. |
| Read "needs from you" first | Summary order: Needs the user → Changed → Decided → Reviewed. |
Round 2: what the audit found
| Finding | Confidence | Result |
|---|---|---|
| "Kaveh must find at least one issue per artifact". A quota makes the model invent objections. | Medium | Fixed: a clean artifact is a valid result, with evidence. |
Tool names like view_file and grep_search that do not exist in Claude Code. |
Medium | Fixed: names removed. |
| The deadlock rule was in two places, with two different units ("rounds" and "exchanges"). | Medium | Fixed: one rule, in one place. |
| "Don't accumulate a to-do list" conflicted with the new ledger. | Medium | Fixed: "Do not defer an agreed fix." |
| A file-name rule in capital letters, with a long incident story. | Medium | Fixed: a plain rule with its reason. |
| "Challenge ALL of the following" in capital letters. | Medium | Fixed: "checks each category below that the materials contain". |
| "Relentless review" and "Do not stall" may push a harsh tone or an early escalation. | Low | Reported only. |
Two of these findings came from round 1 itself. The new ledger created the to-do list conflict, and the duplicate deadlock rule was missed. This is a good reason to run the audit after your own edits, not only before them.
The biggest finding: the workflow never loaded
The most important problem was not in the workflow file. It was in the command that loads it. The *challenge-me handler ran its loader from a folder (./.agent/...) that did not exist. The command failed, and the model quietly used its fallback: it made up a review on its own. It never read challenge-me.md. None of the rules in the file were in use.
The fix was one path (./.claude/...) in two command files. The lesson is bigger: before you tune a prompt, check that the model actually receives it.
One thing is still open: the new rules were checked by reading the files and running the loader, but not yet in a full live session. That test comes next.
7. The Full Challenge-Me Workflow
Here is the upgraded workflow in full. You can copy it and change the names, paths, and categories to fit your own project.
---
name: challenge-me
description: >
Dual-agent review session: Jamshid (Architect) hands materials to Kaveh (Engineer)
for a relentless adversarial review. They debate, challenge, and refine until they
reach agreement — or escalate unresolvable conflicts to the user.
---
This workflow simulates a **live adversarial review** between two Mitra agents:
| Voice | Agent | Bias |
| :--- | :--- | :--- |
| 🏛️ **Jamshid** | Architect | Structure, scalability, long-term trade-offs |
| ⚡ **Kaveh** | Engineer | Implementability, correctness, runtime safety |
You (the LLM) **play both roles in alternating turns**. Each turn must be
clearly prefixed with the agent's icon and name so the user can follow the
dialogue.
---
## 🎯 Objectives
1. **Relentless review** — Kaveh reads every material Jamshid presents (docs,
diagrams, ADRs, RFCs, code, schemas, configs) and challenges assumptions,
gaps, contradictions, and missing edge cases.
2. **Mutual convergence** — They debate back-and-forth until they reach explicit
agreement on every open question.
3. **Run without stopping** — Stop for the user only for the triggers in the
[User Escalation Protocol](#-user-escalation-protocol). **Do not stall — escalate promptly.**
---
## 🚀 Session Start Protocol
When this workflow is activated:
1. **Jamshid opens.** Identify the materials under review (the user will have
pointed to files, directories, or a topic). List every artifact you will
cover: docs, ADRs, diagrams, code files, schemas, etc.
2. **Open the ledger.** Write that list as a checklist in the session summary
file (path and name in [Session End](#-session-end)). Add each objection as a
line with its status (open / agreed / rebutted / user-decided). Update the
ledger after every turn. When a new item appears (from the review or from the
user during the session), add it. A long session gets its old turns
summarized, but the ledger stays, so read it (not the scrollback) to see
what is done and what is left.
3. **Kaveh acknowledges.** Confirm the scope and declare the first item to
inspect. The finish line is the Session End criteria. Do not stop before it.
4. Begin the **Review Loop** (below).
---
## 🔄 The Review Loop
Repeat until all materials are covered and all open items are resolved:
### Turn: ⚡ Kaveh (Challenger)
1. **Read** the next artifact deeply.
When the scope is large (many artifacts, or an audit across a codebase),
give each artifact to its own subagent. Check the evidence of each subagent
report yourself before you raise it as an objection.
2. **Challenge** — raise specific, numbered objections. Each objection must:
- Quote the exact line or section being challenged (file and line).
- Explain *why* it's a problem (ambiguity, incorrectness, missing edge
case, contradiction with code, domain mismatch, scalability risk, etc.).
- Show how it fails: a concrete input, state, or sequence that breaks.
- Propose a concrete fix or alternative.
3. **Cross-reference**:
- Check against `CONTEXT.md` / `CONTEXT-MAP.md` for glossary mismatches.
- Check against `src/` for code contradictions.
- Check against existing ADRs for decision conflicts.
### Turn: 🏛️ Jamshid (Defender)
1. **Respond** to each numbered objection:
- **Accept** — agree and describe the fix.
- **Rebut** — explain why the current design is correct, citing evidence.
- **Propose compromise** — offer a middle ground with rationale.
2. If accepting, **apply the fix inline** (update the artifact file immediately).
### Convergence Check
After each Jamshid response, check:
- ✅ **Agreed** — Both agents explicitly agree. Mark the item resolved and move on.
A resolved item is closed. Open it again only when new evidence contradicts it.
- 🔁 **Still debating** — Continue the exchange on the same point.
- 🚨 **Deadlocked** — Escalate (see the User Escalation Protocol).
---
## 🚨 User Escalation Protocol
These are the **only** reasons to stop and ask the user:
- **Deadlock** — a conflict is not resolved after 3+ exchanges on the same point.
- **Destructive action** — an agreed fix would delete data or files, rewrite
history, or change anything outside this repository. Ask before you apply it.
For all other items, continue. Do not stop to report progress, to ask
"continue?", or to offer choices that do not block the work. Put status notes
in the same turn as the next action.
For a deadlock:
1. **Summarize** the disagreement in 2–3 sentences: what Jamshid argues, what
Kaveh argues, and why neither will yield.
2. **Present options** to the user as one question with:
- Jamshid's position as option A.
- Kaveh's position as option B.
- A compromise (if one exists) as option C.
3. **Apply** the user's decision immediately and note it as a binding verdict.
4. Resume the Review Loop.
---
## 📋 What Gets Reviewed
Kaveh checks each category below that the materials contain:
| Category | What to check |
| :--- | :--- |
| **Architecture** | Component boundaries, coupling, cohesion, dependency direction |
| **Data models** | Schema correctness, normalization, index strategy, migration path |
| **APIs & contracts** | Endpoint design, error handling, versioning, backward compatibility |
| **ADRs** | Are the 3 conditions met? (hard to reverse, surprising, real trade-off) |
| **Diagrams** | Do they match the code? Are flows complete? Missing failure paths? |
| **RFCs / Proposals** | Feasibility, hidden complexity, missing alternatives |
| **Code** | Does it match the documented design? Dead code, race conditions, leaks |
| **Domain language** | Consistency with `CONTEXT.md`, overloaded terms, ambiguous naming |
| **Security** | Auth, authz, input validation, secrets handling, blast radius |
| **Operability** | Logging, monitoring, alerting, graceful degradation, rollback |
---
## ⚡ Engagement Rules
1. **Be specific, not vague.** "This might be a problem" is banned. Every
objection uses the format in Kaveh's **Challenge** step.
2. **No rubber-stamping.** A clean artifact is a valid result. Say what you
checked and give the evidence. Do not raise an objection you cannot support.
3. **Code-first verification.** Before making a claim about behavior, check the
actual source code. Don't guess. If you cannot check a claim, mark it
**UNVERIFIED** and say where you looked.
4. **Update artifacts inline.** When both agree on a fix, apply it to the file
immediately. Do not defer an agreed fix.
5. **Preserve existing comments and docstrings** unrelated to the changes.
6. **Glossary discipline.** If a term is resolved or refined during debate,
update `CONTEXT.md` immediately. Follow the format in
[.mitra/templates/CONTEXT-FORMAT.md](../../../templates/CONTEXT-FORMAT.md).
7. **ADR discipline.** Only create an ADR when all three conditions are met:
hard to reverse, surprising without context, real trade-off. Follow the
format in [.mitra/templates/ADR-FORMAT.md](../../../templates/ADR-FORMAT.md).
---
## 🧠 Domain Awareness & File Structure
Look for existing documentation in these directories. Only create files lazily
(when you have content to write).
- **Single-Context Projects**:
- Domain glossary: `artifacts/{project_id}/docs/CONTEXT.md`
- ADRs: `artifacts/{project_id}/docs/adr/`
- **Multi-Context Projects**:
- Context map: `artifacts/{project_id}/docs/CONTEXT-MAP.md`
- System-wide ADRs: `artifacts/{project_id}/docs/adr/`
- Sub-context glossary: `src/{context_directory}/CONTEXT.md`
---
## ✅ Session End
The session ends when:
1. Every artifact in scope has been reviewed.
2. Every objection has been resolved (accepted, rebutted, or user-decided).
3. Both agents turn the ledger into a **joint summary**, with the sections in
this order:
1. **Needs the user** — deferred items, open decisions, and UNVERIFIED claims.
Put it first, because the user reads it first.
2. **Changed** — what was changed, and in which files.
3. **Decided** — the decisions made, and the user verdicts.
4. **Reviewed** — the scope checklist, all items ticked.
The ledger and the summary are the same file, in `artifacts/{project_id}/architect/`, with the
standard `{YYYY-MM-DD}-challenge-session-summary-{topic-slug}.md` naming.
The topic slug is required. A date alone is not unique, so a second session on
the same day would silently overwrite the first. The slug is two to four words
that name what was reviewed, e.g. `2026-09-23-challenge-session-summary-testing-toolkit.md`.
If that file already exists, choose a different slug.8. Read More
challenge-me is one of many workflows in Mitra. Mitra is a set of agent personas (Analyst, Architect, Engineer, Designer, and more), each with its own skills and review workflows, built to run inside Claude Code and similar tools. To read more about these workflows and similar persona skills, visit the repository: