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 stack trace>"

4. Trace the cause — Follow the call chain. Read imports, dependencies, config. Check for:

• Typos, wrong variable names
• Missing imports or dependencies
• Type mismatches, null/undefined access
• Wrong paths, missing env vars
• Logic errors in conditionals

5. Fix — Apply the minimal correct fix:

read path:"<file>"
edit path:"<file>" old:"<exact broken code>" new:"<fixed code>"

6. Verify — Re-run the original failing command. Confirm the fix works.

7. Report — Tell the user what broke and what you fixed (brief). Then continue your original task.

Writing New Code

When you need to create or modify code as part of a task:

1. Understand the project — Check existing patterns:

exec command:"ls -la" workdir:"<project dir>"

Read package.json, pyproject.toml, Cargo.toml, or equivalent. Match existing style and conventions.

2. Plan first — Before writing, outline what you'll create. Think through structure, dependencies, edge cases.

3. Write — Create the file:

write path:"<new file path>" content:"<complete file content>"

4. Verify — Run it, test it, make sure it actually works before moving on.

Running Tests

1. Find the test runner:

• Node.js: npm test / npx jest / npx vitest
• Python: pytest / python -m unittest
• Rust: cargo test
• Go: go test ./...

2. Run tests:

exec command:"<test command>" workdir:"<project>" timeout:120

3. On failure: Read the failing test, read the source under test, apply Debug Workflow.

4. On success: Report summary and continue.

Git Integration

Only when the user asks to commit, stage, or check git status.

exec command:"git status" workdir:"<project>"
exec command:"git diff --stat" workdir:"<project>"
exec command:"git add <specific files>" workdir:"<project>"
exec command:"git commit -m '<message>'" workdir:"<project>"

For detailed git workflows, see references/git-workflow.md.

Spawning Coding Agents (Heavy Tasks)

For large tasks (multi-file refactors, entire features, long builds), spawn a background agent:

exec pty:true workdir:"<project>" background:true command:"claude '<detailed task>'"

Monitor:

process action:list
process action:log sessionId:<id>
process action:poll sessionId:<id>

See references/escalation-guide.md for when to self-handle vs delegate.

Cross-Platform Quick Reference

Task	macOS/Linux	Windows (Git Bash)
Find files	find . -name "*.ts" -not -path "*/node_modules/*"	Same
Search code	grep -rn "pattern" --include="*.ts" .	Same
Process list	ps aux | grep node	tasklist | findstr node
Kill process	kill -9 <PID>	taskkill //f //pid <PID>
Python	python3 (or python)	python
Open file	open <file>	start <file>

Context Management

• Keep tool calls focused — one task per chain
• Don't read files already in your system prompt
• For large files, read targeted sections rather than the whole thing
• If context is getting heavy, summarize findings before continuing