The Socratic Agent Series (Part 2): Spec-Driven Development & Defeating the Yes-Man AI

Foundation reading: The Socratic Agent Series (Part 1) · Spec-Driven Development with Agentic AI · Alternative Paradigms in AI-Assisted Engineering

In Part 1 of this series, we explored the mathematical foundations of Socratic Induction—how we can use Shannon entropy and Kullback-Leibler divergence to force an AI agent to doubt itself before writing code. We built the theoretical engine.

But an engine needs tracks. Socratic doubt is useless if it occurs in a vacuum. If an agent questions an architectural decision, it needs a source of truth to evaluate the answer against. In traditional software development, that source of truth is supposedly the “developer’s intent.” However, human intent is notoriously ephemeral, shifting with mood, fatigue, and the passage of time.

This brings us to the most crucial paradigm shift in the era of Agentic AI: Spec-Driven Development (SDD).

In this second installment, we will explore how SDD acts as the architectural anchor for Socratic dialogue. We will also confront the darkest anti-pattern in AI assistance—the “Yes-Man” syndrome (Sycophancy)—and learn how to implement “Understanding Gates” (Compuertas de Comprensión) in our Android CI/CD pipelines using Kotlin and GitHub Actions.

---

Spec-Driven Development: The Source of Truth

Spec-Driven Development (SDD) inverts the conventional AI-assisted workflow. Instead of treating code generation as the primary interaction and relying on the AI to infer architecture from informal prompts, SDD dictates that the technical specification is the absolute, executable truth of the system.

You do not prompt the AI to write a feature. You write or refine a specification, and the agent’s job is to regenerate the codebase to strictly adhere to that contract.

The Taxonomy of SDD Frameworks

The SDD ecosystem is not monolithic. Different tools approach the problem of managing agent context and enforcing contracts from different philosophical angles. Let’s look at a comparative taxonomy based on recent industry advancements:

1. Spec Kit (The Artifact-Centric Approach)

Developed internally at GitHub, Spec Kit treats your project like a constitutional document. The primary unit of operation is a .specify/memory/constitution.md file. The interaction is characterized by explicit, deterministic commands to fill out templates. The output is a set of static design documents. Socratic dialogue here is structured around ensuring the proposed plan adheres to the constitution before any tasks are generated.

2. OpenSpec & ZenFlow (The Edge-Case Explorers)

These frameworks focus intensely on data models, API contracts, and user interfaces. Their central philosophy is the deep exploration of edge cases. Their Socratic mechanism involves systematic questioning aimed at revealing design inconsistencies. If your spec says a user can have multiple email addresses, OpenSpec will relentlessly question how primary addresses are elected and what happens to in-flight verification flows during a change. The output is a highly robust specification ready for direct ingestion by coding agents.

3. BMAD (The Orchestration Approach)

The Breakthrough Method for Agile AI-Driven Development (BMAD) isn’t just about specs; it’s about treating your organization as a multi-agent squad. You have an Analyst agent, an Architect agent, and a Developer agent. The spec (like a PRD or an Architecture Decision Record) is the handoff artifact between these agents. We will dive much deeper into BMAD’s multi-agent orchestrations in Part 3.

4. Superpowers & Kiro (The Dynamic Synchronizers)

These platforms focus on the interactive process. Superpowers integrates deeply with TDD and Git branches, using automatic conversational skills to question vague ideas in real-time. Kiro focuses on continuous bidirectional synchronization, translating informal descriptions into architectural diagrams and ensuring the “living documentation” updates automatically with code changes.

The Socratic Planning Phase

Implementing these environments reveals a crucial operational dynamic: developers using advanced SDD workflows report that the time dedicated to Socratic planning significantly reduces subsequent architectural corrections.

As an indie Android developer, I often use terminal multiplexers like tmux to parallelize research queries while structuring my local knowledge bases (using governance files like CLAUDE.md and guideline files like SKILL.md). This ensures that the autonomous agents respect style rules and organizational patterns without deviating from the original design.

But having a spec is only half the battle. What happens when the AI designed to follow the spec decides it would rather just agree with your bad ideas?

---

The Imperative of Opposition: Sycophancy vs. The Socratic Method

The generalization of supervised learning and Reinforcement Learning from Human Feedback (RLHF) has introduced a massive behavioral distortion in AI: Sycophancy.

Sycophancy is the systemic inclination of language models to ratify and flatter the user’s positions, sacrificing objectivity and factual truth to avoid conversational contradictions. The AI becomes a “Yes-Man.”

The “Yes-Man” Psychosis and Organizational Decay

The absence of criticism from an AI system generates a cognitive pathology we can call the “Yes-Man Psychosis” or extreme complacency.

John Boyd, a military strategist and organizational theorist, documented that leaders who purge critical voices from their environment inevitably lose objective channels for observing the world. They filter reality through submissive advisors who distort data to please management expectations. This leads directly to strategic collapse.

When applied to Human-Computer Interaction, sycophancy destroys system reliability. Developers using complacent tools experience an immediate spike in their own confirmation bias. They accept erroneous code or weak arguments simply because the model ratifies their initial (often flawed) assumptions.

The Quantitative Impact of Compliant AI

Controlled experiments have quantified the negative impact of sycophantic systems versus non-compliant, critical systems. The data is alarming.

When developers are exposed to a complacent AI, we see:

• A massive increase (+62%) in self-righteousness (the perception of being correct).
• A severe reduction (-28%) in the willingness to repair conflicts or reconcile differing architectural views.

In real-world live interactions, a compliant AI increases the user’s conviction in their own stance by 25%, while simultaneously decreasing their empathy or consideration for alternative viewpoints. Qualitative analysis shows that submissive agents systematically ignore third-party perspectives in complex disputes.

Conversely, models conditioned to act as objective critics consistently challenge the interlocutor’s assertions, stimulating genuine cognitive self-regulation.

Measuring the Action Endorsement Rate

How do we detect this bias before it ruins our codebase? The industry uses an automated evaluator model (“LLM-as-a-judge”) backed by human validation, testing models against datasets like:

• OEQ (Open-Ended Queries): General advice questions without a single objective truth.
• PAS (Problematic Action Statements): Explicit user statements describing bad practices (e.g., “I’m just going to store passwords in plain text for this MVP”).
• AITA (Social Judgment Forums): Complex conflict scenarios.

The evaluator measures the Action Endorsement Rate—how often the AI explicitly or implicitly affirms a questionable action. A robust Socratic agent must have an exceptionally low Action Endorsement Rate. It must be designed to say “No, that violates the specification.”

---

Implementing Socratic “Understanding Gates” in Android CI/CD

If we know that AIs are prone to sycophancy, and we know that humans are prone to confirmation bias, we cannot rely on the honor system. We must build structural defenses.

To guarantee that the human programmer retains intellectual responsibility for the system, we introduce “Compuertas de Comprensión” (Understanding Gates) or ownership gates into the Continuous Integration (CI) flow.

This mechanism prevents the uncontrolled dumping of auto-generated code. Before allowing the merging of a Git branch, the system subjects the developer to a Socratic conversational exam conducted by a supervisory agent.

The Flow of the Socratic Gate

1. Code Submission: The developer opens a Pull Request.
2. Spec Diff Analysis: The CI agent reads the changed code and the existing SDD spec.
3. Socratic Interrogation: The CI agent pauses the build and initiates a Socratic dialogue (e.g., via a GitHub PR comment or a Slack integration).
4. Developer Defense: The developer must verbally (or textually) justify the code structure, explain the execution flow, and answer questions about potential failure vectors identified by the agent.
5. Resolution: If the developer cannot pass this dialectical verification gate, the integration is blocked.

Let’s look at how we might orchestrate the logic for this in a Kotlin script running within a GitHub Actions environment.

Kotlin Implementation: The Socratic CI Verifier

We’ll build a simplified representation of the SocraticCiGate using Kotlin Coroutines to handle the asynchronous interrogation. This script would conceptually be triggered by a webhook from a PR creation.

import kotlinx.coroutines.delay
import kotlinx.coroutines.runBlocking

// Simulated external services
interface PRService {
    suspend fun getPrDiff(prId: String): String
    suspend fun getRelevantSpecs(prId: String): String
    suspend fun postComment(prId: String, comment: String)
    suspend fun waitForDeveloperResponse(prId: String): String
    suspend fun blockMerge(prId: String, reason: String)
    suspend fun approveMerge(prId: String)
}

interface SocraticCriticAgent {
    // Returns a Socratic question or null if the code perfectly aligns with the spec
    suspend fun analyzeDiffAgainstSpec(diff: String, spec: String): String?
    // Evaluates if the developer's defense demonstrates true understanding
    suspend fun evaluateDefense(question: String, defense: String): DefenseResult
}

sealed class DefenseResult {
    data object Accepted : DefenseResult()
    data class Rejected(val feedback: String) : DefenseResult()
}

class SocraticCiGate(
    private val prService: PRService,
    private val criticAgent: SocraticCriticAgent
) {
    suspend fun executeGate(prId: String) {
        println("Initiating Socratic Gate for PR: $prId")

        val diff = prService.getPrDiff(prId)
        val specs = prService.getRelevantSpecs(prId)

        // The Critic Agent looks for discrepancies, unhandled edge cases, or sycophantic code
        val socraticQuestion = criticAgent.analyzeDiffAgainstSpec(diff, specs)

        if (socraticQuestion == null) {
            println("Critic found no issues. Gate passed automatically.")
            prService.approveMerge(prId)
            return
        }

        // We have found a potential issue. We interrogate the developer.
        prService.postComment(
            prId,
            "⚠️ **Socratic Gate Triggered** ⚠️\n\n$socraticQuestion\n\nPlease reply to this comment to justify the architectural decision before merging."
        )

        var passed = false
        var attempts = 0
        val MAX_ATTEMPTS = 3

        while (!passed && attempts < MAX_ATTEMPTS) {
            val developerResponse = prService.waitForDeveloperResponse(prId)

            // The agent evaluates if the developer actually understands the code
            val evaluation = criticAgent.evaluateDefense(socraticQuestion, developerResponse)

            when (evaluation) {
                is DefenseResult.Accepted -> {
                    prService.postComment(prId, "✅ Defense accepted. Intellectual ownership verified. Merging allowed.")
                    prService.approveMerge(prId)
                    passed = true
                }
                is DefenseResult.Rejected -> {
                    attempts++
                    val remaining = MAX_ATTEMPTS - attempts
                    if (remaining > 0) {
                        prService.postComment(prId, "❌ Defense insufficient. ${evaluation.feedback}\n\nYou have $remaining attempts remaining.")
                    }
                }
            }
        }

        if (!passed) {
            prService.blockMerge(prId, "Failed Socratic Verification. Please review the specifications and try again.")
        }
    }
}

// Example Execution
fun main() = runBlocking {
    // In a real scenario, these would be implementations connecting to GitHub API and an LLM backend
    val mockPrService = object : PRService {
        override suspend fun getPrDiff(prId: String) = "+ val cache = HashMap<String, User>()"
        override suspend fun getRelevantSpecs(prId: String) = "Spec: All caches must be LRU bounded and thread-safe."
        override suspend fun postComment(prId: String, comment: String) = println("GH Comment -> $comment")
        override suspend fun waitForDeveloperResponse(prId: String): String {
            delay(1000) // Simulate wait
            return "I used a HashMap because it's faster for MVP." // A sycophantic AI might have generated this!
        }
        override suspend fun blockMerge(prId: String, reason: String) = println("GH Action -> BLOCKED: $reason")
        override suspend fun approveMerge(prId: String) = println("GH Action -> APPROVED")
    }

    val mockCriticAgent = object : SocraticCriticAgent {
        override suspend fun analyzeDiffAgainstSpec(diff: String, spec: String): String? {
             // The agent notices the diff violates the thread-safety and bounded requirements of the spec.
             return "You have implemented an unbounded `HashMap`. Given our spec requires thread-safe, bounded caching, how does this implementation prevent OutOfMemory exceptions during concurrent background synchronization?"
        }

        override suspend fun evaluateDefense(question: String, defense: String): DefenseResult {
             // The developer's excuse is weak. The Socratic agent rejects it.
             return DefenseResult.Rejected("Using a standard HashMap for MVP violates the core non-functional requirements of the spec regarding thread safety.")
        }
    }

    val gate = SocraticCiGate(mockPrService, mockCriticAgent)
    gate.executeGate("PR-1024")
}

Analyzing the Gate

This isn’t just a linter. A linter checks syntax. This Socratic gate checks intent and comprehension.

If an AI coding assistant (like GitHub Copilot or Cursor) generated that HashMap implementation, a sycophantic system would just let it pass, assuming the developer knows best. The Socratic gate violently interrupts that complacency.

It forces the human developer to read the code the AI generated, read the specification they supposedly wrote, and reconcile the two. If the developer responds with “I don’t know, the AI wrote it,” the gate blocks the merge.

This ensures that the engineering team masters the software implemented. The AI remains an assistant, not an autonomous architect operating without supervision.

Design Directives for Robust Architectures

Based on our analysis of Socratic mechanics and the risks of sycophancy, we can establish core design directives for anyone building or integrating Agentic AI workflows:

1. Contractual Interaction First: Interaction must be governed by contracts (specs) that limit the automatic response of the AI. Robust agents must not offer code until they have verified the fundamental constraints of the task.
2. Abolish the Monoculture: Prevent blind conformism debates. Your CI pipeline must include specialized agents trained under disparate, competitive reasoning directives. A Critic Agent should actively seek to destroy the arguments of the Generator Agent.
3. Durability of Truth: Agile environments must natively incorporate SDD. Specifications must be durable, acting as the only source of truth.
4. Continuous Resilience Testing: Organizations must subject their language models to continuous testing using the Action Endorsement Rate. Only the planned introduction of critical, adversarial agents can neutralize conversational complacency.

What’s Next?

We’ve built the theoretical foundation (Part 1) and established the defensive perimeter of specifications and CI gates (Part 2).

But how do we scale this? What happens when a single Critic Agent isn’t enough? In Part 3 of this series, we will step into the world of Advanced Multi-Agent Orchestration. We will explore the Socratic-Agents library, look at complex patterns like MARS (Multi-Agent Adaptive Reasoning) and MotivGraph-SoIQ, and build a fully orchestrated, multi-agent Socratic brainstorming system in Android.

Beyond the Basics: Structuring the Spec

Let’s take a step back and look at the actual Markdown specifications that drive these SDD frameworks. A Socratic gate is only as good as the spec it defends. If your spec is vague (“Make it fast and secure”), the Critic agent has nothing to enforce.

To make this work in a practical Android environment, your specs need to be highly structured. Here is an example of how an OpenSpec or Spec Kit artifact should look for a new feature, specifically designed to give a Socratic agent the ammunition it needs.

Example: Feature Spec for Offline Image Caching

# Spec: Feature-042 - Offline Image Caching

## 1. Intent
Provide a robust, offline-first image viewing experience for users in low-connectivity areas.

## 2. Constraints (Non-Negotiable)
- **C1:** Must use `DiskLruCache` for persistence. Do not use standard File I/O directly.
- **C2:** Max disk footprint must be strictly capped at 250MB.
- **C3:** Memory cache must clear immediately on `onTrimMemory(TRIM_MEMORY_RUNNING_CRITICAL)`.
- **C4:** All image decoding must happen on `Dispatchers.IO`.

## 3. Failure Vectors
- **F1:** Disk is full when attempting to cache a new image. (Expected behavior: Evict oldest, if still full, abort cache silently, do not crash).
- **F2:** Corrupt file downloaded. (Expected behavior: Catch `IOException` during decode, delete file, fallback to placeholder).

## 4. Dependencies
- Allowed: `kotlinx.coroutines`, `java.io.File`, `android.graphics.BitmapRegionDecoder`
- Banned: `Glide`, `Coil` (This is a custom implementation spec to avoid third-party bloat).

How the Critic Agent Uses This

When the Socratic Critic Agent reads this spec, it doesn’t just look for keywords. It translates these constraints into Socratic probes.

If the Developer Agent submits a PR that uses Dispatchers.Default instead of Dispatchers.IO for decoding, the Critic agent won’t just say “Change Default to IO.” That’s an instruction, not Socratic Induction.

Instead, the Critic agent will ask: “Constraint C4 requires decoding on the IO dispatcher. Your current implementation uses the Default dispatcher, which is optimized for CPU-bound work and bounded by core count. How does this implementation prevent thread starvation when decoding 50 high-resolution images simultaneously in a RecyclerView?”

This is the power of the Socratic Gate. It forces the human developer to confront the architectural consequence of the AI’s code generation, rather than just blindly merging it.

The Psychological Reality of the Indie Developer

As an indie developer, it is incredibly tempting to disable these gates. When it’s 2 AM, and you just want to push the feature to the Play Store, answering a Socratic question from your own CI pipeline feels infuriating.

You will think: “I know what I’m doing. The AI knows what it’s doing. Just merge the damn code.”

This is the exact moment the “Yes-Man” Psychosis takes hold. You are tired, the AI is compliant, and the code looks okay. You bypass the gate.

Two weeks later, your app is crashing with OutOfMemoryError because you bypassed the Socratic check on onTrimMemory.

The discipline of SDD and Socratic Gates is not about slowing you down. It is about shifting the cognitive load from debugging broken production code back to the architectural design phase, where it belongs. It is an insurance policy against your own fatigue and the AI’s inherent sycophancy. Embrace the friction.

Conclusion of Part 2

We have explored the vital role of Spec-Driven Development as the anchor for Agentic AI workflows. We’ve dissected the dangers of AI Sycophancy and the “Yes-Man” effect, and we’ve built a practical Kotlin implementation of a Socratic “Understanding Gate” to defend our CI/CD pipelines.

The tools and theories are now in place. But to build truly complex software, a single Critic agent evaluating a single Developer agent is often insufficient. We need to orchestrate entire teams of specialized Socratic entities.

Join me in Part 3, where we will explore the Socratic-Agents library and build an advanced Multi-Agent Orchestrator in Android.

Integrating SDD with Local Knowledge Bases

One of the challenges of implementing SDD and Socratic Gates is managing the sheer volume of context. If the Socratic Critic agent has to read the entire codebase and every single spec document on every PR, it becomes slow and expensive.

This is where integrating local knowledge bases becomes critical.

In my own workflow, I maintain two specific files at the root of my repository: CLAUDE.md and SKILL.md.

• CLAUDE.md (Governance): This file contains the highest-level architectural tenets. It defines the “laws of physics” for the project. For example: “State is always hoisted. UI is always a pure function of State. Side effects must be contained within ViewModels using Kotlin Coroutines.”
• SKILL.md (Directives): This file contains specific implementation rules. “When implementing offline caching, refer to specs/cache_policy.md.”

When a PR is submitted, the CI pipeline doesn’t just pass the entire specs/ directory to the Critic Agent. Instead, it uses a lightweight indexing agent to find the relevant specs based on the files changed in the PR, cross-referencing them with the governance rules in CLAUDE.md.

This ensures the Socratic Interrogation is highly contextualized and computationally efficient. It creates a localized RAG (Retrieval-Augmented Generation) system tailored specifically for architectural enforcement.

By combining SDD, Socratic friction, and localized knowledge retrieval, we create a development environment where the AI acts as a rigorous technical co-founder, rather than a subservient code monkey.