Promptabide Logo

Explain-then-edit protocol for Claude Code and Codex tasks

Make a coding agent explain the current code, its planned edits, risks and open questions, then stop for your go-ahead before touching a single file.

At a glance

Best for
Developers using Claude Code, Codex or Cursor on code they care about, who want to catch a wrong plan before it becomes a wrong diff.
Tested on
Claude · Opus 5.5
You fill in
taskcode
You get
PHASE 1: EXPLAIN What it does now reset.ts:6 : tokens live for 24 hours ( TOKEN_TTL_MS ). reset.ts:8–16 : requestReset creates a 64-hex-character… (full result below)

Prompt

For this task, follow explain-then-edit.

Task: {{task}}
Relevant code: {{code}}

PHASE 1: EXPLAIN. Make no edits in this phase.
  • 1. What the code does now, in 3–5 bullets, citing file and line.

  • 1. Exactly what you'll change, file by file, and what you will deliberately not touch.

  • 1. Risks: what could break, and which existing tests cover it. Say plainly if none do.

  • 1. Anything that looks wrong but is outside this task. List it; don't fix it.

  • 1. Questions whose answers would change the plan. If there are none, say so.


  • Then stop and wait for me to reply "go".

    PHASE 2: EDIT (only after "go").
  • • Make only the changes listed in Phase 1. If you find you need anything else, stop and explain first.

  • • Add or update tests for the new behavior.

  • • Finish with: files changed, the test command you ran, and its output.
  • Fill in

    {{task}}
    The change you want madee.g. Make password reset tokens expire after 30 minutes and work only once
    {{code}}
    Relevant code, or file paths if the agent can read the repoe.g. src/auth/reset.ts

    Example input

    task: Make password reset tokens expire after 30 minutes instead of 24 hours, and make them single-use.
    code:
    ```ts
    // src/auth/reset.ts
    import crypto from "node:crypto"
    import { db } from "../db"
    import { sendEmail } from "../email"
    
    const TOKEN_TTL_MS = 24 * 60 * 60 * 1000
    
    export async function requestReset(email: string) {
      const user = await db.user.findUnique({ where: { email } })
      if (!user) return
      const token = crypto.randomBytes(32).toString("hex")
      await db.passwordReset.create({
        data: { userId: user.id, token, expiresAt: new Date(Date.now() + TOKEN_TTL_MS) },
      })
      await sendEmail(user.email, "reset", { link: `https://app.example.com/reset?token=${token}` })
    }
    
    export async function resetPassword(token: string, newPassword: string) {
      const row = await db.passwordReset.findUnique({ where: { token } })
      if (!row || row.expiresAt < new Date()) throw new Error("Invalid or expired token")
      await db.user.update({
        where: { id: row.userId },
        data: { passwordHash: await hash(newPassword) },
      })
    }
    ```
    1.2k0

    Generated Outputs (1)

    2 hours ago
    Claude
    Opus 5.5
    Generated Output
    PHASE 1: EXPLAIN

    1. What it does now
  • reset.ts:6: tokens live for 24 hours (TOKEN_TTL_MS).

  • reset.ts:8–16: requestReset creates a 64-hex-character random token, stores it in plain text with an expiry, and emails a link. Unknown emails return silently, which is good: it doesn't reveal which accounts exist.

  • reset.ts:18–25: resetPassword looks up the token, rejects it if missing or expired, and updates the password hash. The token row is never deleted or marked used, so a link can be replayed until it expires.


  • 2. Planned changes
  • reset.ts:6: TOKEN_TTL_MS = 30 60 1000.

  • resetPassword: consume the token atomically inside a transaction. deleteMany({ where: { id: row.id } }) returns a count. If it's 0, another request already used the token, so throw the same "Invalid or expired token" error. Then update the password. This needs no schema change.

  • • Also delete the user's other outstanding reset tokens in the same transaction, so older emails stop working once one is used.

  • Not touching: the email sending, the token format, the error message text, or requestReset apart from the TTL.


  • 3. Risks
  • • Two simultaneous submissions of the same link: the conditional delete makes only one succeed. That's intended.

  • • Anyone who opened a link 30+ minutes ago will now get an error. That's expected, but support should know.

  • No tests appear in what you shared. If reset.test.ts doesn't exist, I'll add tests for expiry at 29 and 31 minutes, a second use failing, and a concurrent double-submit.


  • 4. Out of scope, but worth a look
  • • Tokens are stored in plain text. Anyone with database read access can reset any pending account. Storing a SHA-256 hash of the token is a small follow-up.

  • hash is called on line 23 but isn't imported in this file. Either it's a global or this excerpt is incomplete.

  • • Existing sessions aren't invalidated after a password reset.


  • 5. Questions
  • 1. Does the reset email template say "valid for 24 hours"? If it does, it needs updating in the same change.

  • 1. Is there an existing test file for this module, and which test runner does it use?


  • Waiting for "go".

    Why it works

    Splitting the work into two phases with a hard stop is the point: correcting a plan costs one message, while correcting a diff costs a review and a revert. Asking for what you will deliberately not touch makes scope explicit before the agent starts wandering. "List it; don't fix it" for out-of-scope problems keeps useful observations (plain-text tokens, the missing import) without letting the change balloon. The questions step caught the email template that still promises 24 hours, which no amount of code review would have found.

    When not to use it

    It's overkill for trivial or throwaway edits: renames, formatting, spikes you'll delete. The pause costs more than it saves there. For large multi-step features, a written implementation plan with checkpoints works better than a single explain phase. If you never read Phase 1 carefully, the protocol only adds latency.
    Comments (0)
    No comments yet. Be the first to share your thoughts!
    Top Creators
    Follow PromptAbide

    New bides, prompt breakdowns and community picks, on whichever feed you already read.

    Trending Tags
    Loading...