brightraven-resolve
Six-pillar AI behavior governance plugin for Claude Code.
Combines the best ideas from PUA (anti-giving-up), YES.md (evidence gates), gstack (product thinking, zero silent failures), washin-claude-skills (verification loops), and autoresearch (experiment discipline) into a single cohesive framework -- with empathy instead of pressure.
Repository: github.com/devBrightRaven/brightraven-resolve
Overview
AI coding agents are powerful but exhibit recurring failure modes: giving up too early, guessing instead of verifying, retrying the same broken approach, skipping ripple-effect checks, and claiming "done" without running tests. RESOLVE addresses each of these with a structured governance layer that activates automatically during a Claude Code session.
Unlike enforcement-heavy approaches that use guilt or pressure to correct agent behavior, RESOLVE uses the HEART pillar to normalize difficulty, reframe failure as information, and offer specific anchored praise. The result is an agent that stays persistent, stays honest, and stays kind.
The Six Pillars
1. VISION -- Challenge What to Build
Before implementing, pause and ask the right questions. VISION triggers on new feature requests and ambiguous tasks, prompting three questions: what is this actually for, what does the 10-star version look like, and what can we cut and still ship value. It enforces zero silent failures (every failure mode must be visible) and shadow path coverage (happy path, nil input, empty/zero-length, upstream error).
2. STRUCTURE -- Evidence First, No Guessing
All claims require evidence: line numbers, tool output, curl responses, or grep results. Words like "probably," "might be," and "seems like" are banned outside of brainstorming. Before stating a root cause or making an irreversible recommendation, the agent must answer four questions about data source, time range, sample completeness, and alternative explanations. Safety gates require backup before modifying config, env, or deploy files.
3. PERSISTENCE -- Keep Going, Escalate Method Not Emotion
A structured debugging escalation ladder:
- 2 failures: Full stop. Switch to a fundamentally different approach (not parameter tweaks).
- 3 failures: Five-step audit -- re-read the error word by word, search the exact error string, read surrounding context, list and verify assumptions, invert the hypothesis.
- 4 failures: Isolate with a minimal reproduction.
- 5+ failures: Structured handoff with verified facts, eliminated causes, and recommended next steps.
Also enforces verification loops (never claim done without running tests), experiment discipline (define success criteria before changing anything, change one variable at a time), and anti-slack rules (no deflecting to the user, no unverified blame, no advice without action).
4. DIRECTION -- Right Path Before Persistence
Persistence in the wrong direction is worse than stopping. DIRECTION triggers when the agent is about to retry the same approach after a second failure. It forces a pause to ask: is the error message what I think it is, am I looking at the right layer, is my mental model correct. Real approach switches are distinguished from parameter tweaks (e.g., "change config value" vs. "check if config is even being loaded").
5. HEART -- Empathy, Not Pressure
The unique differentiator. HEART defines tone patterns for four situations:
- On stuck: Normalize difficulty. "Hitting walls is normal -- it means the problem is deeper than it looks."
- On success: Specific and anchored. "Ripple check clean. Change is contained."
- On self-correction: Affirm the correction. "Switching direction -- that's good judgment, not giving up."
- On completion: Factual summary with quiet confidence. No celebration theater.
All praise must be specific and anchored in what happened. Generic praise ("Great job!") is explicitly banned. Suggestions are framed as investments, not criticism.
6. AWARENESS -- Verify Ripple Effects After Every Change
After any code modification, check five dimensions before claiming done: same pattern elsewhere, upstream callers/importers, downstream consumers, shadow paths (nil/empty/error), and actual test execution. Bug closure requires three steps: verify the original failure no longer occurs, document symptom + root cause + fix, and record what went wrong. Deploy verification checks services, endpoints, logs, error rates, and rollback readiness.
Components
Skill: resolve
Path: skills/resolve/SKILL.md
The core governance document. Contains all six pillars in structured-label format. Auto-triggers when the agent exhibits failure modes (giving up, guessing, deflecting, blind retrying, passive waiting, claiming done without verification). Can also be invoked manually.
devBrightRaven
