secrets-rotation

Files (1)

• SKILL.md

SKILL.md (first lines)

# secrets-rotation — an exposed secret is spent

Deleting the message, rewriting git history or redacting the log does not un-expose a
secret: the transcript, the remote, the backup and the provider's own logs already hold
it. The only fix is to make the exposed value worthless — **revoke it and issue a new one**.

What went wrong on real projects is not ignorance of that. It is that the rotation was
**remembered instead of tracked**: "rotate the exchange API keys" was carried forward
through seven session logs; "keys that passed through chat" appeared in seven summaries
of another project; a monitoring token pasted in plain text was never rotated. Each
session wrote the reminder again and nobody owned it.

## The moment you see one

1. **Never repeat the value.** Not in your answer, not in a task title, not in a log, not
   in a commit message. Name its **kind** and **where it is**: "OpenRouter API key, in the
   operator's message of 22.09, 14:10". `scripts/lib/secret-patterns.mjs` names the kind.
2. **Say it plainly, first line:** this key is compromised; revoking it is the only fix.
3. **Open one task, not a note** — in Beads if the project has it:

   ```bash
   bd create "Rotate <kind> exposed in <where> on <date>" -t bug -p 0 \
     -d "Exposed: <where>. Revoke at <provider console>, issue new, store in <secret store>, redeploy <consumers>, prove the old one is rejected."
   ```

   Priority 0 for a production credential or anything that moves money; 1 otherwise.
4. **If you can rotate it, rotate it** — the operator asked you to handle it, or your
   task covers that system. If it needs the operator (a provider console you cannot
   reach, a hardware token), the task's first line says exactly what they must click.

## Done means the old value is refused

A rotation is closed with evidence, not with "rotated":

- the new value is in the secret store the code reads — never in `CLAUDE.md`,
  `preferences.md`, memory files, a README or any file that is loaded into a model's
  context (one key in a preferences file reached 605 transcripts);
- every consumer was redeployed and uses it (`deploy-landed`, config check);
- **a call with the old value fails** — 401/403 from the provider. That is the proof.

## Carrying it forward

An open rotation task older than 48 hours goes to the top of the next session's report
and of `/inbox`, with its age. Do not re-list it in the session log as a fresh item —
link the task. Re-writing a reminder is how the seven-session carry-over happened.

From avelikiy/great_cto, MIT.

More from avelikiy/great_cto