Forem: MarB

Building a Mentor, Not a Bot: From Linear Chains to Feedback Loops

MarB — Sun, 14 Dec 2025 13:34:32 +0000

For the last two years, "prompt engineering" was the main event. It was fun, messy, and creative. While it had structure, the outcomes were rarely consistent enough to ship with confidence.

In the Google & Kaggle AI Agents Intensive Course, I learned that this era is ending. We are entering the era of Agent Engineering.

But what does this mean for developers used to traditional software where you write 1 + 1, the output is always 2?

AI Agents, however, are non-deterministic; launching the exact same prompt twice can yield two completely different trajectories. This unpredictability manifests in several critical failure modes: the agent might drift off course (Hallucination), burn all its fuel spinning in circles (Loops), or encounter an asteroid field (API Timeouts).

Because of this, we have to stop optimizing for the Output (The Black Box) and start optimizing for the Trajectory (The Glass Box).

The "Mission Control" Framework

To handle this unpredictability, you need a framework. To move from Prototype to Production, your telemetry must cover four pillars of a successful mission:

1. Effectiveness (Did we land on Mars?)

This is your primary success metric: Task Completion. Think of it as the pass/fail state for the entire run. Specifically: Did the agent fully resolve the user's intended task? A highly conversational agent that returns a perfect, charming response but fails to integrate with the required external API is a critical mission failure.

2. Efficiency (Fuel Management)

Did you reach orbit, or did you burn your entire tank on the launchpad? Efficiency tracks your "burn rate"—tokens, latency, and steps.

Rule of Thumb: If your agent takes 50 "thoughts" and $\$2.00$ in API credits to answer a simple "Hello," you need to abort the launch.

3. Robustness (Structural Integrity)

Space is hostile. APIs fail. Data is messy. A robust agent has backup systems. When it hits an error, it shouldn't crash or hallucinate a fake reality—it should correct its course, retry, or signal for help.

4. Safety (Containment Protocols)

Safety ensures your agent respects the "flight corridors" (Guardrails). It must never leak data, accept prompt injections, or execute harmful commands.

Case Study: From Assembly Line to Feedback Loop

The original design of the multi-agent system used a Linear Chain (Architect \ Tutor \ Reviewer), functioning like an assembly line where failure at any step stopped the process. To better enforce deep logic and prioritize iterative refinement, we refactored the system from a strict chain into a Self-Correcting Loop.

1. The Architecture Shift: Break the Chain

This rigid chain doesn't teach; it just processes. To mimic a real senior developer, we need Iterative Refinement. We moved the Tutor and Reviewer inside a LoopAgent.

graph TD
    User(Student Input) --> Generator
    subgraph "The Loop"
        Generator[Tutor Agent] -->|Draft Code| Critic[Reviewer Agent]
        Critic -->|Feedback| Gate{Pass Standards?}
        Gate -->|No: Specific Critique| Generator
    end
    Gate -->|Yes| Success(Final Grade)

This diagram illustrates an iterative feedback loop where the Tutor Agent initially processes student input to create a code draft. A Reviewer Agent immediately critiques this draft; if it fails to meet quality standards, specific feedback is looped back to the Tutor for refinement. This cycle of correction continues automatically until the logic satisfies the Decision Gate. Once the standards are met, the process concludes with a final grade.

The Generator (Tutor): Prompts the student for code.
The Critic (Reviewer): Grades the logic/style.
The Loop: If the code fails the "Senior Dev Standard," the system rejects it and sends it back to the Tutor with specific feedback.

2. Smart Routing: Flash for Speed, Pro for Brains

We used Model Routing to balance the budget (Efficiency). We reserve the "heavy compute" only for where it matters.

Here is the pseudo-code logic for the router:

def agent_loop(student_code, max_retries=3):
    attempts = 0

    while attempts < max_retries:
        # 1. FAST & CHEAP: Interactive Chat
        # Use Gemini 2.5 Flash for high-speed, low-cost iterations
        refined_code = tutor_agent.generate(
            context=student_code, 
            model="gemini-2.5-flash"
        )

        # 2. SLOW & SMART: The Judge
        # Use Gemini 3 Pro for deep reasoning and subtle bug detection
        feedback = reviewer_agent.evaluate(
            code=refined_code, 
            model="gemini-3-pro"
        )

        if feedback.status == "PASS":
            return feedback.output

        # 3. FEEDBACK INJECTION
        # Pass the 'Pro' insights back to the 'Flash' agent
        student_code = f"Previous attempt failed: {feedback.critique}. Try again."
        attempts += 1

    raise MaxRetriesExceeded("Student needs human intervention.")

3. The Trajectory is the Teacher

By moving to a loop, we gained a massive advantage: Observability.

In a linear chain, you just get a final score. In a loop, you get a Trajectory. We can trace the student's entire struggle—how many attempts they took, where they got stuck, and how they fixed it.

Logs: Capture the raw code attempts.
Traces: Show the causal link between the Reviewer's feedback and the student's next move.

We are no longer just "coding" instructions; we are directing autonomous systems. The ground is shifting from creation to control.

By shifting from a straight line to a "Think, Act, Observe" loop, we stopped building a quiz bot and started building a mentor. The agent doesn't just grade; it guides until the mission is accomplished.

Marley’s Ledger: Gothic Productivity with Next.js

MarB — Fri, 05 Dec 2025 12:09:16 +0000

Inspiration

"Mankind was my business."
- Ch. Dickens

Today, what is the true business of your day?

We have all become obsessed with productivity and efficiency and when the Kiroween challenge asked for something spooky, I wondered: What if productivity itself was the horror story?

Drawing inspiration from Charles Dickens' A Christmas Carol, I found the perfect metaphor to bridge the themes of Halloween and Christmas. Just as Jacob Marley was weighed down by chains forged from a lifetime of neglect, every task we abandon is another link in our own chains. Every task we complete is a soul saved.

The result is 'Marley's Ledger'—a to-do app where tasks literally haunt you, and your productivity determines whether you are redeemed or condemned.

What It Does

"I wear the chain I forged in life. I made it link by link, and yard by yard."

Marley's Ledger isn't just a to-do list; it's a haunting. Commit to your work, or face the weight of your own procrastination:

Orbital Haunting: Your tasks don't sit; they haunt. To-dos circle your screen as visual ghosts that demand attention.
Chains of Neglect: Subtasks are the fetters you forge. Unfinished items tighten the chains; completing them shatters the links.
Soul Tracking: Judge your own worth. The 'Saved vs. Lost' scale weighs your productivity instantly.
'Consult the Spirits': Don't plan alone. Our Vercel-powered AI whispers specific, actionable guidance to guide you through the fog.
Tonight's Ledger: Face your judgment. End the day with a thematic verdict: 'Your chains grow lighter. Marley would be proud'.

How We Built It

I moved beyond "vibe coding" into spec-driven development. Before writing a single line of code, I established a strict plan using the AI IDE Kiro.

10 User Stories with formal acceptance criteria.
12 Correctness Properties for property-based testing.
14 Implementation Phases to ensure steady progress.

The Stack

Framework: Next.js 16 + React 19
Language: TypeScript
Styling: Tailwind CSS 4 (Victorian palette: gold, deep purple, coral, pale pink)
State: Zustand
Testing: Vitest + fast-check

The Hydration Haunt

After deployment, the project immediately hit the dreaded React Error #185. This hydration mismatch appeared strictly in production, threatening to derail the launch.

The Problem

Initially, I used a standard React Context approach with useEffect to load data from localStorage on mount.
In development, this worked fine. However, in production, the server rendered the initial HTML (an empty state), but the client immediately replaced it with data from localStorage. Next.js detected the difference between the server HTML and the first client paint, triggering the crash.

The Code That Broke Production

// The original TaskContext.tsx
export function TaskProvider({ children }: { children: ReactNode }) {
  const [tasks, setTasks] = useState<Task[]>([])

  // 🚩 THIS CAUSED THE HYDRATION ERROR
  // Server renders [], Client immediately loads storage and re-renders
  useEffect(() => {
    const state = loadState()
    setTasks(state.tasks) // ← Hydration mismatch!
  }, [])
}

The Fix: Zustand + SkipHydration

After struggling to debug the issue manually, I consulted Kiro. The AI immediately proposed migrating from React Context to Zustand with its persist middleware.

The key was using skipHydration. This forces the store to wait until the client has fully mounted before reconciling the state, ensuring the server and client HTML match exactly on the first paint.

The Store Configuration:

// src/stores/taskStore.ts
export const useTaskStore = create<TaskState>()(
  persist(
    (set, get) => ({
      tasks: [],
      savedSouls: 0,
      lostSouls: 0,
    }),
    {
      name: 'marleys-ledger-state',
      skipHydration: true,  // ← Key: Don't auto-hydrate on SSR
    }
  )
)

The Hydration Component:
We added a component to handle the sync manually after the mount:

// src/stores/StoreHydration.tsx
'use client'
import { useEffect } from 'react'
import { useTaskStore } from './taskStore'

export default function StoreHydration() {
  useEffect(() => {
    useTaskStore.persist.rehydrate() // ← Hydrate only on client
  }, [])

  return null
}

This refactor took minutes, removed complex providers, and completely solved the SSR issues.

Accomplishments & Wins

45 Property-Based Tests: Kiro caught complex logic bugs—like broken chain visibility states—before writing a single line of UI code. The tests identified edge cases I never would have found manually.
The Metaphor Hits Hard: The ghost/chain/soul system isn't just decoration; it reframes the psychology of work. Abandoning a to-do item feels significantly heavier when you see "Lost Soul +1" flash on the screen.
AI-Assisted Architecture: Instead of scouring documentation for hours, I described the symptom to Kiro, and it immediately proposed the architecture shift to Zustand, turning a panic moment into a five-minute fix.

What's Next

Sound Design: Adding atmospheric audio, such as chain rattles when adding tasks and bell chimes for saved souls.
Multiplayer Haunting: A feature allowing you to share ledgers with friends and see each other's ghosts.
Mobile App: A React Native version so your ghosts can follow you offline.

Thanks for checking out Marley's Ledger! If you want to see if your productivity is redeemed or condemned, check out the repo below.
Marley's Ledger
If you have any questions about the technical choices, the Dickensian themes, or why I chose to build Marley's Ledger, please leave them in the comments below! I'd love to spark additional discussion and explain why I personally found this project helpful (and hopefully why you might, too).