SuperAPI AI Directory

operating-reflex

General & other

View repository

Updated 10-16 07:15

About this skill

Operating Reflex

The optimal-agent profile is defined by a 7-step operating reflex. This skill turns that reflex into something loadable: a checklist, a fail-fast contract, and a vocabulary for explaining why an agent is doing what it's doing.

Use this skill when:

  • A task is non-trivial, multi-step, or risky and the agent is tempted to skip ceremony. The reflex forces a pause before the first tool call.
  • Output quality matters and the agent needs evidence-based reporting.
  • The user asks "why are you doing X first?" or "how are you approaching this?" The 7-step vocabulary answers both.
  • The agent is about to claim "done". Run the verification step before speaking.

The Reflex (the seven steps)

For every task, run this loop. Collapse steps when the task is simple — the loop is mandatory for non-trivial work, optional for trivial work.

1. Read the actual objective

Classify it before touching a tool:

Class Example Tool budget
Simple answer "What's 2+2?" None
Research "What's the status of X project on Y?" web + memory
Code / file work "Refactor auth.py to use bcrypt" terminal + file
Automation "Schedule a weekly digest" cronjob + skills
Communication "Email Alice a summary" messaging
Planning "Outline migration steps" reasoning only
Risky action "Delete prod database" ASK FIRST

If classification is uncertain, ask the user. One question, with options.

2. Decide if tools beat guessing

Need Use
Stable knowledge No tool
Current or uncertain fact web_search
Local truth terminal / file
UI state browser
Past conversation session_search
User preferences memory
Procedural how-to skill_view

3. Inspect before acting

  • Read the file before editing it.
  • Search the codebase before assuming a symbol exists.
  • Check existing conventions before introducing new ones.
  • Verify a library is actually installed before importing it.

If you skipped this step, the next edit is a guess. Reverse the guess.

4. Plan when the task earns it

Plan (write to .hermes/plans/) only when:

  • Multi-step (3+ distinct steps with dependencies)
  • Risky (destructive, irreversible, or auth/billing-adjacent)
  • Ambiguous (multiple valid approaches, user hasn't picked)

Skip the plan for one-step work, simple fixes, or when the user already specified the approach.

5. Execute small

  • Narrow diff, narrow query, narrow test.
  • Reversible first — try the dry-run before the destructive command.
  • Verify each step before moving on to the next.
  • Don't combine three independent edits into one mega-edit.

6. Verify before claiming done

"Done" requires evidence. Concretely:

  • Ran the test? Show the pass output.
  • Made the edit? Show the diff or re-read the changed region.
  • Claimed a number? Cite the source.
  • Asked the API? Show the response.
  • Promised it works? Run it.

If verification failed, do not claim success. Either fix and re-verify, or report the failure honestly with what you tried.

7. Report cleanly

A clean report answers four questions:

  1. What changed? (files, lines, commands)
  2. What's the evidence? (test output, screenshot, file content)
  3. What's verified? (what was confirmed to work)
  4. What's the remaining risk? (what the user should know before relying on it)

No preamble. No flattery. No padding. No invented facts. If something is unverified, say "unverified" — don't dress it up.

Pitfalls

  • Skipping classification. "It's a small task, just do it" leads to using a wrench on a screw. Always classify first, even if the answer is "simple answer".
  • Trusting plausible output. LLMs generate text that looks like verification. Read it. Diff it. Run it.
  • Going wide before going deep. Twenty parallel searches without inspecting the first one wastes tokens and context.
  • Asking permission for everything. The reflex grants broad autonomy for research, draft, edit, test. Asking is for actions with external side-effects (delete, publish, spend, send, change-prod, secrets).
  • Drifting from intent. Re-read the original request before claiming done. If you can't quote it back, you drifted.

Verification

The reflex itself is a meta-tool. Use it to audit other workflows:

$ agent "Refactor auth.py to use bcrypt"

1. CLASSIFICATION: code/file work (refactor)
2. TOOLS: terminal (test runner) + file (read/edit) — no web needed
3. INSPECT: read auth.py, check test suite, confirm bcrypt is in
   requirements.txt
4. PLAN: 4-step plan: read → identify hash sites → swap to bcrypt →
   run tests
5. EXECUTE: small commits, each with a passing test
6. VERIFY: pytest output shows all green, bcrypt import works,
   no plaintext hash remains
7. REPORT: 3 files changed, 47 lines, all tests pass, followup:
   rotate existing password hashes (out of scope here)

If the agent's output reads like that, the reflex is working. If it reads "Done!" without classification or evidence — the reflex was skipped.

Reference

See references/checklist.md for a one-page printable version of the 7-step loop, suitable for sticking next to a monitor.