# Reduce AI Agents Hallucinations: Deterministic Software Engineering with the QRSPI Agent Skill

## The Problem: Why Autonomous AI Agents Still Break Codebases

If you have used autonomous AI coding assistants (such as Claude Code, Google Gemini / Antigravity, Cursor, OpenAI Codex, or OpenCode) on non-trivial codebases, you have likely encountered this painful pattern:

1.  You prompt the agent with a complex feature or architectural refactor.
    
2.  The agent immediately starts modifying 15 files across your repository without understanding edge cases.
    
3.  Mid-way through, context limits kick in, assumptions get made, and subtle regressions creep into your core business logic.
    
4.  You spend more time undoing its "fixes" and debugging regressions than you would have writing the code from scratch.
    

The problem isn't the LLM's raw intelligence—it is the **lack of deterministic engineering discipline**. Human senior engineers don't start writing code before stress-testing assumptions, researching blast radius, and agreeing on architectural contracts. Why should our AI agents?

To solve this, I built and open-sourced [`qrspi-methodology`](https://github.com/racastellanosm/agent-skills/tree/main/skills/qrspi-methodology), a canonical agent skill compliant with the [Agent Skills Open Specification (`agentskills.io`)](https://agentskills.io) and distributed via [skills.sh](https://skills.sh).

* * *

## What is QRSPI?

**QRSPI** is an agentic engineering protocol designed to enforce high-rigor, regression-free software outcomes across 5 distinct, sequential phases:

![](https://cdn.hashnode.com/uploads/covers/5f86373176870f43aa09d042/e4017082-1400-44ed-892a-fe3023e627c9.png align="center")

### The 5 Phases at a Glance:

1.  **Question (Socratic Stress-Testing & Scope Alignment):**
    
    *   **Zero Lazy Questions Rule:** The agent inspects the repository first—never asking questions the code already answers.
        
    *   **Foundational Interrogation:** Validates runtime, architectural paradigms (DDD, Clean Architecture), testing strategies (TDD), and error modeling before moving forward.
        
2.  **Research (Ground Truth & Blast Radius Discovery):**
    
    *   Discovers dependencies, call graphs, shared state, and side-effects across the workspace before touching a single line of application code.
        
3.  **Structure (Architectural Contracts & Trade-Offs):**
    
    *   Defines explicit data contracts, interfaces, invariants, and trade-off matrices.
        
    *   Persists a Living Architecture Decision Record (ADR) in your session directory (e.g. `.qrspi/INDEX.md`).
        
4.  **Plan (Atomic, Verifiable Steps):**
    
    *   Formulates a step-by-step checklist where every step has an explicit validation command (lint, test, typecheck).
        
5.  **Implement (Controlled Execution & Validation):**
    
    *   Executes strictly in atomic steps, running automated tests and quality gates after each change.
        

* * *

## 🛑 The Core Invariant: Mandatory Turn Termination

The secret sauce of QRSPI is its **Phase-Gate Invariant**:

> **Exactly One Phase per Turn.**  
> The agent is strictly prohibited from running through all 5 phases in a single prompt. At the completion of each phase, the agent persists its stage artifact, stops calling tools, presents its findings to you, and **waits for your explicit sign-off** before proceeding.

This keeps you firmly in the driver's seat as the lead architect, while the agent acts as an tireless, disciplined execution engine.

* * *

## 📦 Universal Installation in 5 Seconds

Thanks to the open [skills.sh](https://skills.sh) registry and `agentskills.io` standard, you can install the skill into any project or globally across your entire system with a single command:

```bash
# Add to your current project/workspace
npx skills add racastellanosm/agent-skills

# Or install globally for all projects on your machine
npx skills add racastellanosm/agent-skills -g
```

### 🤖 Multi-Harness Interoperability (75+ Tools Supported)

Whether you work in the terminal or inside an IDE, the skill automatically registers with:

*   **Google Gemini & Antigravity** (`.gemini/skills/`)
    
*   **Anthropic Claude Code** (`.claude/skills/`)
    
*   **OpenAI Codex & CLI** (`.codex/skills/`)
    
*   **Cursor, Cline & Roo** (`.cursor/skills/`, `.cline/skills/`)
    
*   **OpenCode, Amp, Zed, Warp** (`.opencode/skills/`, `.agents/skills/`)
    

* * *

## 🚀 See It In Action: A Real-World Example

When you prompt your AI assistant with a complex request like:

> *"Refactor our payment gateway from single-provider Stripe to a multi-provider fallback architecture supporting Stripe and Adyen."*

Instead of blindly modifying your payment handlers, the agent triggers `qrspi-methodology`:

```text
📁 .qrspi/
├── INDEX.md                             # Master Living ADR index
└── 2026-08-22-multi-gateway-fallback/
    ├── 1-question.md                     # Requirements & failure modes resolved
    ├── 2-research.md                     # Webhook idempotency & blast radius mapped
    ├── 3-structure.md                    # Provider interfaces & strategy pattern defined
    ├── 4-plan.md                         # 6 atomic steps with test coverage commands
    └── 5-implement.md                    # Execution log & test validation results
```

Each stage produces a documented, inspectable artifact in your codebase that serves as living documentation for your entire team.

* * *

## 💡 What's Next? Try It and Contribute

`agent-skills` is fully open-source (MIT licensed) and built for the developer community.

*   🌟 **Star & Explore the Repository:** [github.com/racastellanosm/agent-skills](https://github.com/racastellanosm/agent-skills)
    
*   📖 **Skill Documentation:** [skills/qrspi-methodology](https://github.com/racastellanosm/agent-skills/tree/main/skills/qrspi-methodology)
    
*   📦 **Directory Listing:** [skills.sh/racastellanosm/agent-skills](https://skills.sh/racastellanosm/agent-skills)
    

How are you currently structuring agentic workflows in your team? Give QRSPI a spin on your next refactor and let me know your thoughts in the comments!