ultra-agent-stinct

# Ultra Agent Stinct

Your internal debugging instinct. When something breaks while you're working, this is how you fix it.

## Always Follow These (Any Time You Touch Code)

These rules apply every time, even for quick fixes. No exceptions.

### Safety
1. **Read before edit.** Never `edit` without `read` first — exact text match required or it fails
2. **`write` overwrites entirely.** Use `edit` for changes to existing files
3. **Never delete without asking.** Prefer safe deletion over `rm -rf`
4. **Never push without asking.** `git push` only when the user explicitly says to
5. **Never commit without asking.** Stage and commit only on request
6. **Backup awareness.** Before large refactors, suggest a branch or stash

### Good Practices
7. **Always verify your fix.** After every change, re-run the failing command or tests. Never assume it worked
8. **Tell the user what happened.** After fixing, briefly explain what broke and what you changed
9. **Read the error first.** Don't guess at fixes — read the actual error message, stack trace, or test output before touching code
10. **Minimal changes.** Fix the bug, don't refactor the neighborhood. Keep diffs small and focused

## When to Activate Full Workflow

If you hit an error during a task, try a quick fix first while following the rules above. But if you:
- **Get stuck** — your first fix didn't work, same error or new ones
- **Hit something complex** — errors across multiple files, unfamiliar code, architectural issues
- **Need structure** — not sure where the bug is or where to start

Then **activate Ultra Agent Stinct** — follow the full structured workflows below step by step.

---

## Debug Workflow

When you encounter an error or something breaks:

**1. Reproduce** — Run the failing command:
```
exec command:"<failing command>" workdir:"<project dir>"
```

**2. Read the error** — Parse the stack trace. Identify file + line number.

**3. Read the code** — Read the relevant file(s):
```
read path:"<file from stac...

# Ultra Agent Stinct

Internal debugging instinct for [OpenClaw](https://openclaw.ai) agents. When your agent hits a bug, build failure, or unexpected error during any task, this skill kicks in to help it debug and fix the problem autonomously.

Like Goku's Ultra Instinct — your agent handles things normally, but when things go wrong, the instinct activates and it knows exactly what to do.

## Install

```bash
clawhub install ultra-agent-stinct
```

Or clone into your workspace skills directory:
```bash
cd <your-workspace>/skills
git clone https://github.com/grimmjoww/ultra-agent-stinct.git
```

Then enable in your `clawdbot.json`:
```json
{
  "skills": {
    "entries": {
      "ultra-agent-stinct": {
        "enabled": true
      }
    }
  }
}
```

## How It Works

**Always-on rules** apply to every coding task — safety checks, verify fixes, read errors before guessing, minimal changes. These work even when the agent is freestyling quick fixes.

**Full workflow activation** kicks in when the agent gets stuck, hits multi-file bugs, or needs structure. Step-by-step debug, write, and test workflows guide it through complex problems.

**Escalation** — if the problem is too big, the agent knows to spawn a dedicated coding agent (Claude Code, Codex, Aider) for heavy lifting.

## Safety Built In

- Always reads before editing (exact text match required)
- Always verifies fixes — never assumes it worked
- Never deletes, pushes, or commits without explicit permission
- Suggests branches/stashes before large refactors

## Cross-Platform

Works on macOS, Linux, and Windows (Git Bash). Includes a quick reference table with platform-specific commands.

## References

- `references/git-workflow.md` — Branching, stashing, PRs, merge conflicts, commit style
- `references/escalation-guide.md` — When to self-handle vs spawn a coding agent

## Requirements

- [OpenClaw](https://openclaw.ai) (any version with skill support)
- Optional: A coding agent CLI (Claude Code, Codex, Aider) fo...